bare-agent 0.9.0 → 0.10.1

package/README.md

@@ -11,7 +11,12 @@
 
 ```
 
-**Agent orchestration in ~2.7K lines of core. One required dep ([bareguard](https://npmjs.com/package/bareguard) ^0.2.0). Apache 2.0.**
+<p align="center">
+  <img src="https://img.shields.io/github/package-json/v/hamr0/bareagent?label=version&color=2a4f8c" alt="version (auto from package.json)">
+  <img src="https://img.shields.io/badge/license-Apache%202.0-2a4f8c" alt="license: Apache 2.0">
+</p>
+
+**Agent orchestration in ~2.7K lines of core. One required dep ([bareguard](https://npmjs.com/package/bareguard) ^0.2.0).**
 
 Lightweight enough to understand completely. Complete enough to not reinvent wheels. Not a framework, not 50,000 lines of opinions — just composable building blocks for agents. Single-gate governance via bareguard: every tool call traverses one policy hook, one audit log, one budget cap.
 
@@ -72,7 +77,7 @@ Every piece works alone — take what you need, ignore the rest.
 | **Scheduler** | Cron (`0 9 * * 1-5`) or relative (`2h`, `30m`). Persisted jobs survive restarts |
 | **Stream** | Structured event emitter. Pipe as JSONL, subscribe in-process, or custom transport |
 | **Errors** | Typed hierarchy — `ProviderError`, `ToolError`, `TimeoutError`, `CircuitOpenError`, `ValidationError`. Halt decisions (turn cap, budget cap, content rules) come from bareguard, not Loop |
-| **bareguard adapter** | `wireGate(gate)` returns `{ policy, wrapTools }` — one-line wiring to bareguard's `Gate`. Maps gate decisions to Loop's `policy` contract; `wrapTools` decorates tools so `gate.record` fires after every execute. `require('bare-agent/bareguard')` |
+| **bareguard adapter** | `wireGate(gate)` returns `{ policy, onLlmResult, onToolResult, filterTools, formatDeny }` — one-line wiring to bareguard's `Gate`. `policy` maps gate decisions to Loop's policy contract; `onLlmResult` + `onToolResult` forward every LLM and tool result to `gate.record` (so `budget.maxCostUsd` covers token-only workloads); `filterTools` drops denied tools from the catalog the LLM ever sees. Halt-severity decisions throw a typed `HaltError` and Loop exits cleanly — never leaks `[HALT: ...]` to the LLM. `require('bare-agent/bareguard')` |
 | **Browsing** | Web navigation, clicking, typing, reading via `barebrowse` (17 tools). Two modes: library tools (inline snapshots, pass to Loop) or CLI session (disk-based snapshots, token-efficient for multi-step flows). Optional `assess` tool (privacy scan) when `wearehere` is installed |
 | **Mobile** | Android + iOS device control via `baremobile`. Same two modes: library tools (`createMobileTools` — action tools auto-return snapshots) or CLI session (`baremobile` CLI — disk-based snapshots) |
 | **Shell** | Cross-platform `shell_read`, `shell_grep`, `shell_run` (argv, no shell), `shell_exec` (raw shell). Pure Node — no `grep`/`rg`/`findstr` dependency. Injection-proof `shell_run` for policy-gated use |
@@ -90,6 +95,73 @@ Every piece works alone — take what you need, ignore the rest.
 
 ---
 
+## Recipes
+
+### Wire bareguard into Loop
+
+```js
+const { Gate } = require('bareguard');
+const { Loop } = require('bare-agent');
+const { wireGate } = require('bare-agent/bareguard');
+
+const gate = new Gate({
+  budget: { maxCostUsd: 0.50 },
+  limits: { maxTurns: 20 },
+  audit:  { path: './audit.jsonl' },
+});
+await gate.init();
+
+const { policy, onLlmResult, onToolResult, filterTools } = wireGate(gate);
+const tools = await filterTools(myTools);      // drop tools denied by static policy
+
+const loop = new Loop({ provider, policy, onLlmResult, onToolResult });
+await loop.run([{ role: 'user', content: 'go' }], tools, { ctx: { userId: 42 } });
+```
+
+`onLlmResult` + `onToolResult` are what make `budget.maxCostUsd` actually cover token-heavy workloads — without them, budget only sees tool cost. `ctx` flows through to `gate.record` as `_ctx` for per-principal accounting.
+
+### Per-principal bypass (owner / admin role)
+
+Wrap the gate policy when a principal is trusted unconditionally:
+
+```js
+const { policy: gatePolicy } = wireGate(gate);
+
+const policy = async (toolName, args, ctx) => {
+  if (ctx?.role === 'owner') return true;       // bypass gate entirely
+  return gatePolicy(toolName, args, ctx);
+};
+
+new Loop({ provider, policy, onLlmResult, onToolResult });
+```
+
+Bypassing the gate also bypasses audit and budget — only do this for principals you trust unconditionally. For partial trust, use ctx-aware rules inside bareguard instead.
+
+### Custom deny strings (localize / strip prefix)
+
+```js
+const { policy } = wireGate(gate, {
+  formatDeny: (decision) => `Sorry — ${decision.reason || 'not allowed'}`,
+});
+```
+
+Halt-severity decisions bypass `formatDeny` (they throw `HaltError` and exit the loop without ever reaching the LLM).
+
+### Catch halts in your app
+
+```js
+const result = await loop.run(msgs, tools);
+if (result.error?.startsWith('halt:')) {
+  // budget cap, turn cap, or gate terminated. Inspect rule:
+  const rule = result.error.slice('halt:'.length);
+  // tell the user, schedule retry, escalate, etc.
+}
+```
+
+Halts also fire `loop:error` on the stream (`source: 'halt'`) and the `onError` callback (with a `HaltError` instance).
+
+---
+
 ## Cross-language usage
 
 Not using Node.js? Spawn bare-agent as a subprocess from any language. Ready-made wrappers in [`contrib/`](contrib/README.md) for Python, Go, Rust, Ruby, and Java — copy one file, no package registry needed.

package/index.js

@@ -10,7 +10,7 @@ const { Stream } = require('./src/stream');
 const { Retry } = require('./src/retry');
 const { runPlan } = require('./src/run-plan');
 const { CircuitBreaker } = require('./src/circuit-breaker');
-const { wireGate } = require('./src/bareguard-adapter');
+const { wireGate, defaultActionTranslator } = require('./src/bareguard-adapter');
 const {
   BareAgentError,
   ProviderError,
@@ -18,6 +18,7 @@ const {
   TimeoutError,
   ValidationError,
   CircuitOpenError,
+  HaltError,
 } = require('./src/errors');
 
 module.exports = {
@@ -32,10 +33,12 @@ module.exports = {
   runPlan,
   CircuitBreaker,
   wireGate,
+  defaultActionTranslator,
   BareAgentError,
   ProviderError,
   ToolError,
   TimeoutError,
   ValidationError,
   CircuitOpenError,
+  HaltError,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "files": [
     "index.js",
     "src/",
@@ -22,12 +22,14 @@
   },
   "exports": {
     ".": "./index.js",
+    "./errors": "./src/errors.js",
     "./providers": "./src/providers.js",
     "./stores": "./src/stores.js",
     "./transports": "./src/transports.js",
     "./tools": "./src/tools.js",
     "./mcp": "./src/mcp.js",
-    "./bareguard": "./src/bareguard-adapter.js"
+    "./bareguard": "./src/bareguard-adapter.js",
+    "./package.json": "./package.json"
   },
   "engines": {
     "node": ">=18"

package/src/bareguard-adapter.js

@@ -1,25 +1,42 @@
 'use strict';
 
+const { HaltError } = require('./errors');
+
 /**
  * Wire a bareguard Gate into bareagent's Loop.
  *
  * Returns:
- *   - `policy`   — async (toolName, args, ctx) closure for `new Loop({ policy })`.
- *                  Maps gate.check decisions to true (allow) or a deny string
- *                  (used verbatim by Loop as the LLM-visible reason).
- *   - `wrapTool` — wraps a single tool so its execute() also calls gate.record
- *                  with the result + duration (or error). Bareguard owns the
- *                  audit log and budget tracking; record() is what feeds them.
- *   - `wrapTools` — convenience: applies wrapTool to an array.
+ *   - `policy`        — async (toolName, args, ctx) closure for `new Loop({ policy })`.
+ *                       Allow → true; deny → tagged reason string; halt → throws HaltError.
+ *   - `onLlmResult`   — callback for `new Loop({ onLlmResult })`. Forwards every
+ *                       provider.generate result to gate.record as a `{type:'llm'}` action
+ *                       so `budget.maxCostUsd` covers token-only workloads.
+ *   - `onToolResult`  — callback for `new Loop({ onToolResult })`. Forwards every
+ *                       tool.execute result to gate.record with ctx in scope.
+ *   - `filterTools`   — async (tools) => filtered. Drops tools denied by gate.allows
+ *                       so the LLM never sees them. No audit, no record.
+ *   - `wrapTool` / `wrapTools` — DEPRECATED. Pre-BA1 shim that wraps execute() to
+ *                       call gate.record post-hoc. Loses _ctx and never sees LLM cost.
+ *                       Prefer `onToolResult` (and `onLlmResult` for budget correctness).
  *
- * Halt-severity decisions (budget exhausted, limits.maxTurns hit, etc.) come
- * back as deny strings tagged `[HALT: <rule>]`. Subsequent rounds halt the
- * same way; the LLM typically gives up and the loop exits naturally. For
- * earlier exit, watch the loop:error stream (the closure also calls onError
- * via Loop's policy-deny path) or wire `onError` to detect halt strings.
+ * Halt-severity decisions (budget exhausted, limits.maxTurns hit, gate terminated)
+ * throw HaltError from the policy closure; Loop catches it and exits cleanly with
+ * loop:error{source:'halt'} + loop:done — the deny is NOT fed back to the LLM.
  *
- * @param {object} gate - A bareguard Gate instance (must have .check and .record).
- * @returns {{policy: Function, wrapTool: Function, wrapTools: Function}}
+ * @param {object} gate - A bareguard Gate instance (must have .check, .record, .allows).
+ * @param {object} [options]
+ * @param {Function} [options.formatDeny] - (decision) => string. Transforms the deny
+ *   string fed to the LLM. Default: "[deny: <rule>] <reason>". Halt bypasses this
+ *   (HaltError doesn't reach the LLM).
+ * @param {Function} [options.actionTranslator] - (toolName, args, ctx) => action.
+ *   Builds the action object passed to `gate.check` and `gate.record`. Default:
+ *   `{ type: toolName, args, _ctx: ctx }`. Override when bareguard's primitives
+ *   need a specific shape — e.g. `bashCheck` requires `{type:'bash', cmd:...}`,
+ *   `fsCheck` requires `{type:'read'|'write'|'edit', path:...}`. The default shape
+ *   matches `tools.denylist` / `tools.allowlist` (which read `action.type`) but
+ *   does NOT activate `bash`/`fs`/`net` primitives — those need their own
+ *   `action.type` value. Adopters using those primitives must translate.
+ * @returns {{policy: Function, onLlmResult: Function, onToolResult: Function, filterTools: Function, wrapTool: Function, wrapTools: Function}}
  *
  * @example
  *   const { Gate } = require('bareguard');
@@ -30,29 +47,90 @@
  *     budget: { maxCostUsd: 0.50 },
  *     limits: { maxTurns: 20 },
  *     audit:  { path: './audit.jsonl' },
- *     humanChannel: async (ev) => ({ decision: 'deny' }),
  *   });
  *   await gate.init();
  *
- *   const { policy, wrapTools } = wireGate(gate);
- *   const loop = new Loop({ provider, policy });
- *   await loop.run(messages, wrapTools(myTools));
+ *   const { policy, onLlmResult, onToolResult, filterTools } = wireGate(gate);
+ *   const loop = new Loop({ provider, policy, onLlmResult, onToolResult });
+ *   const tools = await filterTools(myTools);
+ *   await loop.run(messages, tools);
  */
-function wireGate(gate) {
+function wireGate(gate, options = {}) {
   if (!gate || typeof gate.check !== 'function' || typeof gate.record !== 'function') {
     throw new Error('[wireGate] expects a bareguard Gate instance (must have .check and .record).');
   }
+  if (options.formatDeny != null && typeof options.formatDeny !== 'function') {
+    throw new Error('[wireGate] options.formatDeny must be a function (decision) => string');
+  }
+  if (options.actionTranslator != null && typeof options.actionTranslator !== 'function') {
+    throw new Error('[wireGate] options.actionTranslator must be a function (toolName, args, ctx) => action');
+  }
+  const formatDeny = options.formatDeny || defaultFormatDeny;
+  const translate = options.actionTranslator || defaultActionTranslator;
 
   const policy = async (toolName, args, ctx) => {
-    const decision = await gate.check({ type: toolName, args, _ctx: ctx });
+    const decision = await gate.check(translate(toolName, args, ctx));
     if (decision.outcome === 'allow') return true;
-    const tag = decision.severity === 'halt'
-      ? `[HALT: ${decision.rule}]`
-      : `[deny: ${decision.rule}]`;
-    return decision.reason ? `${tag} ${decision.reason}` : `${tag} ${toolName} denied`;
+    if (decision.severity === 'halt') {
+      throw new HaltError(decision.reason || `${toolName} halted by ${decision.rule}`, {
+        rule: decision.rule,
+        decision,
+      });
+    }
+    return formatDeny(decision, toolName);
   };
 
+  const onLlmResult = async ({ model, provider, usage, costUsd, durationMs, ctx }) => {
+    // LLM rounds bypass actionTranslator — they always use the canonical
+    // {type:'llm'} action so budget rules can match without translator collusion.
+    await gate.record(
+      { type: 'llm', args: { model: model || null, provider: provider || null }, _ctx: ctx ?? null },
+      {
+        costUsd: typeof costUsd === 'number' ? costUsd : 0,
+        tokens: (usage?.inputTokens || 0) + (usage?.outputTokens || 0),
+        durationMs: durationMs ?? null,
+      },
+    );
+  };
+
+  const onToolResult = async ({ name, args, result, error, durationMs, ctx }) => {
+    const action = translate(name, args, ctx);
+    if (error) {
+      await gate.record(action, {
+        error: error?.message || String(error),
+        durationMs: durationMs ?? null,
+      });
+    } else {
+      await gate.record(action, {
+        result: typeof result === 'string' ? result : JSON.stringify(result),
+        durationMs: durationMs ?? null,
+      });
+    }
+  };
+
+  const filterTools = async (tools) => {
+    if (!Array.isArray(tools)) {
+      throw new Error('[wireGate.filterTools] expects an array of tools');
+    }
+    if (typeof gate.allows !== 'function') {
+      throw new Error('[wireGate.filterTools] gate must have .allows (bareguard >= 0.2)');
+    }
+    const out = [];
+    for (const t of tools) {
+      if (await gate.allows(t.name)) out.push(t);
+    }
+    return out;
+  };
+
+  let warnedWrap = false;
   function wrapTool(tool) {
+    if (!warnedWrap) {
+      warnedWrap = true;
+      console.warn(
+        '[wireGate] wrapTool/wrapTools is deprecated — use new Loop({ policy, onLlmResult, onToolResult }) ' +
+        'so budget covers LLM cost and ctx reaches gate.record. wrap* will be removed in 1.0.',
+      );
+    }
     if (!tool || typeof tool.execute !== 'function') {
       throw new Error('[wireGate.wrapTool] tool must have an execute() function');
     }
@@ -87,7 +165,21 @@ function wireGate(gate) {
     return tools.map(wrapTool);
   }
 
-  return { policy, wrapTool, wrapTools };
+  return { policy, onLlmResult, onToolResult, filterTools, wrapTool, wrapTools };
+}
+
+function defaultFormatDeny(decision, toolName) {
+  const tag = `[deny: ${decision.rule}]`;
+  return decision.reason ? `${tag} ${decision.reason}` : `${tag} ${toolName} denied`;
+}
+
+// Canonical action shape: tool name as type, args nested, ctx tagged. Matches
+// bareguard's `tools.denylist`/`tools.allowlist` (which read `action.type`) but
+// does NOT activate `bash`/`fs`/`net` primitives — those require `action.type`
+// to be `bash`/`read`/`write`/etc. and read fields like `action.cmd` /
+// `action.path` at the top level. Override via `wireGate(gate, { actionTranslator })`.
+function defaultActionTranslator(toolName, args, ctx) {
+  return { type: toolName, args, _ctx: ctx ?? null };
 }
 
-module.exports = { wireGate };
+module.exports = { wireGate, defaultActionTranslator };

package/src/errors.js

@@ -43,6 +43,22 @@ class CircuitOpenError extends BareAgentError {
   }
 }
 
+// Signals a halt-severity governance decision (budget exhausted, turn cap hit,
+// gate terminated, etc.). Thrown by wireGate's policy closure and caught by
+// Loop's outer handler — does NOT propagate to the LLM as a tool result.
+// Loop exits cleanly: emits loop:error{source:'halt'} + loop:done, calls onError.
+class HaltError extends BareAgentError {
+  constructor(message, { rule, decision, context = {} } = {}) {
+    super(message || `[HALT: ${rule || 'unknown'}]`, {
+      code: 'HALT',
+      retryable: false,
+      context: { ...context, rule, decision },
+    });
+    this.rule = rule || null;
+    this.decision = decision || null;
+  }
+}
+
 module.exports = {
   BareAgentError,
   ProviderError,
@@ -50,4 +66,5 @@ module.exports = {
   TimeoutError,
   ValidationError,
   CircuitOpenError,
+  HaltError,
 };

package/src/loop.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { ToolError } = require('./errors');
+const { ToolError, HaltError } = require('./errors');
 
 // Average pricing per 1K tokens (USD). Adjust these to match your provider's rates.
 // Last updated: 2026-03-18. Source: public provider pricing pages.
@@ -43,11 +43,21 @@ class Loop {
    * @param {object} [options.retry] - Retry instance for backoff on failures.
    * @param {object} [options.stream] - Stream instance for event emission.
    * @param {object} [options.store] - Store instance for validate() health check.
-   * @param {Function} [options.policy] - Async (toolName, args, ctx) => true | string. Recommended wiring: closure that delegates to a bareguard Gate (`require('bare-agent/bareguard').wireGate(gate).policy`). Anything other than `true` denies; a string is fed to the LLM verbatim as the deny reason. All policy/budget/audit decisions live in bareguard — Loop just calls the closure and respects the verdict.
+   * @param {Function} [options.policy] - Async (toolName, args, ctx) => true | string. Recommended wiring: closure that delegates to a bareguard Gate (`require('bare-agent/bareguard').wireGate(gate).policy`). Anything other than `true` denies; a string is fed to the LLM verbatim as the deny reason. A throw of `HaltError` exits the loop cleanly. All policy/budget/audit decisions live in bareguard — Loop just calls the closure and respects the verdict.
+   * @param {Function} [options.onLlmResult] - Async ({model, provider, usage, costUsd, durationMs, ctx}) called after every successful provider.generate. Wire via `wireGate(gate).onLlmResult` so `budget.maxCostUsd` covers token-only workloads. Errors route through `_reportError` but never kill the loop.
+   * @param {Function} [options.onToolResult] - Async ({name, args, result, error, durationMs, ctx}) called after every tool.execute (success and failure). Wire via `wireGate(gate).onToolResult` so `gate.record` sees `ctx`. Errors route through `_reportError` but never kill the loop.
    * @throws {Error} `[Loop] requires a provider` — when options.provider is missing.
    */
   constructor(options = {}) {
     if (!options.provider) throw new Error('[Loop] requires a provider');
+    if (options.maxRounds !== undefined) {
+      throw new Error(
+        '[Loop] options.maxRounds was removed in v0.8 when single-gate governance landed. ' +
+        'Bound iteration via bareguard `new Gate({ limits: { maxTurns: N } })` and wire it with ' +
+        '`new Loop({ policy: wireGate(gate).policy })`. Loop\'s internal HARD_ROUND_LIMIT (100) is ' +
+        'a safety net only and not configurable.',
+      );
+    }
     this.provider = options.provider;
     this.system = options.system || null;
     this.checkpoint = options.checkpoint || null;
@@ -62,6 +72,14 @@ class Loop {
       throw new Error('[Loop] options.policy must be a function (toolName, args, ctx) => true | string');
     }
     this.policy = options.policy || null;
+    if (options.onLlmResult != null && typeof options.onLlmResult !== 'function') {
+      throw new Error('[Loop] options.onLlmResult must be a function');
+    }
+    if (options.onToolResult != null && typeof options.onToolResult !== 'function') {
+      throw new Error('[Loop] options.onToolResult must be a function');
+    }
+    this.onLlmResult = options.onLlmResult || null;
+    this.onToolResult = options.onToolResult || null;
     this._stopped = false;
     this._history = []; // for chat() stateful mode
   }
@@ -144,17 +162,19 @@ class Loop {
     let lastUsage = { inputTokens: 0, outputTokens: 0 };
     let totalCost = 0;
 
+    try {
     for (let round = 0; round < HARD_ROUND_LIMIT; round++) {
       if (this._stopped) break;
 
       let result;
+      const llmStartedAt = Date.now();
       try {
         const generate = () => this.provider.generate(msgs, tools, options);
         result = this.retry ? await this.retry.call(generate) : await generate();
       } catch (err) {
         this._reportError('provider', err, { round });
         if (this.throwOnError) throw err;
-        return { text: '', toolCalls: [], usage: lastUsage, cost: totalCost, error: err.message };
+        return { text: '', toolCalls: [], usage: lastUsage, cost: totalCost, error: err.message, msgs };
       }
 
       lastUsage = result.usage || lastUsage;
@@ -162,12 +182,32 @@ class Loop {
       const roundCost = estimateCost(model, lastUsage);
       if (roundCost !== null) totalCost += roundCost;
 
+      // BA1: forward LLM usage to gate.record (via wireGate) so budget.maxCostUsd
+      // covers token-heavy / tool-light workloads. Callback errors route through
+      // _reportError but never kill the loop — governance failure ≠ run failure.
+      if (this.onLlmResult) {
+        try {
+          await this.onLlmResult({
+            model,
+            provider: this.provider.name || null,
+            usage: result.usage || null,
+            costUsd: roundCost,
+            durationMs: Date.now() - llmStartedAt,
+            ctx,
+          });
+        } catch (err) {
+          if (err instanceof HaltError) throw err;
+          this._reportError('onLlmResult', err, { round });
+        }
+      }
+
       // No tool calls — LLM gave a final text response
       if (!result.toolCalls || result.toolCalls.length === 0) {
         this._safeEmit({ type: 'loop:text', data: { text: result.text } });
         this._safeCall('onText', this.onText, result.text);
         this._safeEmit({ type: 'loop:done', data: { text: result.text, usage: lastUsage, cost: totalCost } });
-        return { text: result.text, toolCalls: [], usage: lastUsage, cost: totalCost, error: null };
+        msgs.push({ role: 'assistant', content: result.text });
+        return { text: result.text, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, msgs };
       }
 
       // Execute tool calls
@@ -229,6 +269,9 @@ class Loop {
           try {
             verdict = await this.policy(tc.name, tc.arguments, ctx);
           } catch (err) {
+            // BA2: HaltError bubbles past the per-tool try/catch to the outer
+            // handler so halt exits cleanly without ever reaching the LLM.
+            if (err instanceof HaltError) throw err;
             verdict = `[Loop] policy error: ${err.message}`;
           }
           if (verdict !== true) {
@@ -241,26 +284,57 @@ class Loop {
           }
         }
 
+        const toolStartedAt = Date.now();
+        let toolResult;
+        let toolError;
         try {
           const execute = () => tool.execute(tc.arguments);
-          const toolResult = this.retry ? await this.retry.call(execute) : await execute();
+          toolResult = this.retry ? await this.retry.call(execute) : await execute();
           const content = typeof toolResult === 'string' ? toolResult : JSON.stringify(toolResult);
           msgs.push({ role: 'tool', tool_call_id: tc.id, content });
           this._safeEmit({ type: 'loop:tool_result', data: { tool: tc.name, result: content } });
         } catch (err) {
-          const toolErr = err instanceof ToolError ? err : new ToolError(err.message, { context: { tool: tc.name } });
-          const errMsg = `[Loop] Tool error: ${toolErr.message}`;
+          toolError = err instanceof ToolError ? err : new ToolError(err.message, { context: { tool: tc.name } });
+          const errMsg = `[Loop] Tool error: ${toolError.message}`;
           msgs.push({ role: 'tool', tool_call_id: tc.id, content: errMsg });
           this._safeEmit({ type: 'loop:tool_result', data: { tool: tc.name, error: errMsg } });
         }
+
+        // BA1: forward tool result/error to gate.record (via wireGate) with ctx in
+        // scope — fixes the lost-_ctx issue that wrapTool can't solve.
+        if (this.onToolResult) {
+          try {
+            await this.onToolResult({
+              name: tc.name,
+              args: tc.arguments,
+              result: toolResult,
+              error: toolError || null,
+              durationMs: Date.now() - toolStartedAt,
+              ctx,
+            });
+          } catch (err) {
+            if (err instanceof HaltError) throw err;
+            this._reportError('onToolResult', err, { tool: tc.name });
+          }
+        }
       }
     }
+    } catch (err) {
+      // BA2: HaltError is a clean governance exit, not a runtime failure.
+      // No throw even when throwOnError:true — the gate halted us deliberately.
+      if (err instanceof HaltError) {
+        this._reportError('halt', err, { rule: err.rule, reason: err.decision?.reason ?? null });
+        this._safeEmit({ type: 'loop:done', data: { text: '', halted: true, rule: err.rule, cost: totalCost } });
+        return { text: '', toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${err.rule}`, msgs };
+      }
+      throw err;
+    }
 
     // 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: '', warning, cost: totalCost } });
-    return { text: '', toolCalls: [], usage: lastUsage, cost: totalCost, error: warning };
+    return { text: '', toolCalls: [], usage: lastUsage, cost: totalCost, error: warning, msgs };
   }
 
   /**
@@ -329,9 +403,10 @@ class Loop {
   async chat(text, tools = [], options = {}) {
     this._history.push({ role: 'user', content: text });
     const result = await this.run(this._history, tools, options);
-    if (result.text) {
-      this._history.push({ role: 'assistant', content: result.text });
-    }
+    // Sync _history from the full msgs run() built (tool-call messages, tool results,
+    // and final assistant text). Strip the leading system message if one was prepended.
+    const effectiveSystem = options.system || this.system;
+    this._history = effectiveSystem ? result.msgs.slice(1) : result.msgs.slice();
     return result;
   }
 

package/src/mcp-bridge.js

@@ -284,9 +284,10 @@ function buildSystemContext(servers, tools, denied) {
 
   const byServer = {};
   for (const t of tools) {
-    const parts = t.name.split('_');
-    const server = parts[0];
-    (byServer[server] = byServer[server] || []).push(t.name.replace(`${server}_`, ''));
+    const sep = t.name.indexOf('_');
+    const server = sep > 0 ? t.name.slice(0, sep) : t.name;
+    const tool = sep > 0 ? t.name.slice(sep + 1) : '';
+    (byServer[server] = byServer[server] || []).push(tool);
   }
   for (const [server, toolNames] of Object.entries(byServer)) {
     lines.push(`  ${server}: ${toolNames.join(', ')}`);
@@ -449,43 +450,52 @@ async function createMCPBridge(opts = {}) {
   if (needsRefresh) {
     // Discover from IDE configs
     const discovered = discoverServers(opts.configPaths);
+
     if (discovered.size === 0 && !config) {
       return { tools: [], servers: [], systemContext: '', denied: [], close: async () => {} };
     }
 
-    // Connect to all discovered servers and list their tools
-    const freshTools = new Map();
-    const connectResults = new Map();
-    const errors = [];
-
-    const toDiscover = opts.servers
-      ? [...discovered.entries()].filter(([n]) => opts.servers.includes(n))
-      : [...discovered.entries()];
-
-    await Promise.all(toDiscover.map(async ([name, def]) => {
-      try {
-        const result = await connectAndListTools(name, def, timeout);
-        freshTools.set(name, result.mcpTools);
-        connectResults.set(name, result.client);
-      } catch (err) {
-        errors.push({ server: name, error: err.message });
-      }
-    }));
-
-    if (errors.length > 0) {
-      console.warn('[MCP Bridge] Some servers failed to connect:', errors);
-    }
+    // Only attempt connection when discovery found something.
+    // If discovered.size === 0 but config exists, fall through and use the existing config
+    // rather than wiping it on a transient discovery failure.
+    if (discovered.size > 0) {
+      const freshTools = new Map();
+      const connectResults = new Map();
+      const errors = [];
+
+      const toDiscover = opts.servers
+        ? [...discovered.entries()].filter(([n]) => opts.servers.includes(n))
+        : [...discovered.entries()];
+
+      await Promise.all(toDiscover.map(async ([name, def]) => {
+        try {
+          const result = await connectAndListTools(name, def, timeout);
+          freshTools.set(name, result.mcpTools);
+          connectResults.set(name, result.client);
+        } catch (err) {
+          errors.push({ server: name, error: err.message });
+        }
+      }));
 
-    // Merge with existing config (preserves user's allow/deny)
-    config = mergeBridgeConfig(config, new Map(toDiscover), freshTools);
+      if (errors.length > 0) {
+        console.warn('[MCP Bridge] Some servers failed to connect:', errors);
+      }
 
-    // Write the config file
-    writeBridgeConfig(bridgePath, config);
-    console.log(`[MCP Bridge] Wrote ${bridgePath}`);
+      // Only write config when at least one server connected successfully.
+      // If all servers failed, retain the existing config unchanged so
+      // user-curated allow/deny settings are not destroyed on transient failures.
+      if (freshTools.size > 0) {
+        config = mergeBridgeConfig(config, new Map(toDiscover), freshTools);
+        writeBridgeConfig(bridgePath, config);
+        console.log(`[MCP Bridge] Wrote ${bridgePath}`);
+      } else if (!config) {
+        return { tools: [], servers: [], systemContext: '', denied: [], close: async () => {} };
+      }
 
-    // Close the discovery connections — we'll reconnect below using the config
-    for (const client of connectResults.values()) {
-      await killServer(client.child);
+      // Close the discovery connections — we'll reconnect below using the config
+      for (const client of connectResults.values()) {
+        await killServer(client.child);
+      }
     }
   }
 

package/src/planner.js

@@ -40,7 +40,7 @@ class Planner {
    */
   async plan(goal, context = {}) {
     if (this._cacheTTL > 0) {
-      const cacheKey = goal + '|' + (context.info || '');
+      const cacheKey = JSON.stringify({ goal, info: context.info || '' });
       const cached = this._cache.get(cacheKey);
       if (cached && Date.now() < cached.expiresAt) {
         return cached.result;
@@ -63,7 +63,7 @@ class Planner {
     const steps = this._parse(result.text);
 
     if (this._cacheTTL > 0) {
-      const cacheKey = goal + '|' + (context.info || '');
+      const cacheKey = JSON.stringify({ goal, info: context.info || '' });
       this._cache.set(cacheKey, { result: steps, expiresAt: Date.now() + this._cacheTTL });
     }
 

package/src/provider-clipipe.js

@@ -74,7 +74,7 @@ class CLIPipeProvider {
   /**
    * Spawn the CLI process, pipe prompt to stdin, collect stdout.
    * @param {string} prompt
-   * @param {string[]} [extraArgs=[]] - Additional args prepended to this.args.
+   * @param {string[]} [extraArgs=[]] - Additional args appended after this.args.
    * @returns {Promise<string>}
    */
   _spawn(prompt, extraArgs = []) {

package/src/retry.js

@@ -14,9 +14,9 @@ const DEFAULT_RETRY_ON = (err) => {
 
 class Retry {
   constructor(options = {}) {
-    this.maxAttempts = options.maxAttempts || 3;
+    this.maxAttempts = options.maxAttempts !== undefined ? options.maxAttempts : 3;
     this.backoff = options.backoff || 'exponential';
-    this.timeout = options.timeout || 60000;
+    this.timeout = options.timeout !== undefined ? options.timeout : 60000;
     this.retryOn = options.retryOn || DEFAULT_RETRY_ON;
     this.jitter = options.jitter !== undefined ? options.jitter : false;
   }
@@ -30,9 +30,9 @@ class Retry {
    * @throws {Error} Rethrows the last error when maxAttempts is exhausted or error is not retryable.
    */
   async call(fn, options = {}) {
-    const max = options.maxAttempts || this.maxAttempts;
+    const max = options.maxAttempts !== undefined ? options.maxAttempts : this.maxAttempts;
     const retryOn = options.retryOn || this.retryOn;
-    const timeout = options.timeout || this.timeout;
+    const timeout = options.timeout !== undefined ? options.timeout : this.timeout;
 
     for (let attempt = 1; attempt <= max; attempt++) {
       let timeoutId;

package/src/scheduler.js

@@ -22,7 +22,7 @@ class Scheduler {
       : [];
     this._timer = null;
     this._nextId = this._jobs.length
-      ? Math.max(...this._jobs.map(j => j.id)) + 1
+      ? this._jobs.reduce((max, j) => Math.max(max, j.id), 0) + 1
       : 1;
   }
 
@@ -80,15 +80,16 @@ class Scheduler {
         try {
           await handler(job);
         } catch (err) {
-          this.onError?.(err, job);
+          try { this.onError?.(err, job); } catch { /* swallow onError throws */ }
+        } finally {
+          this._running.delete(job.id);
+          if (job.type === 'once') {
+            job.status = 'done';
+          } else {
+            job.nextRun = this._parseSchedule(job.schedule).toISOString();
+          }
+          this._save();
         }
-        this._running.delete(job.id);
-        if (job.type === 'once') {
-          job.status = 'done';
-        } else {
-          job.nextRun = this._parseSchedule(job.schedule).toISOString();
-        }
-        this._save();
       }
     };
     tick();

package/src/store-jsonfile.js

@@ -24,7 +24,7 @@ class JsonFileStore {
       ? JSON.parse(readFileSync(this._path, 'utf8'))
       : [];
     this._nextId = this._data.length
-      ? Math.max(...this._data.map(d => d.id)) + 1
+      ? this._data.reduce((max, d) => Math.max(max, d.id), 0) + 1
       : 1;
   }