bare-agent 0.8.0 → 0.10.0

package/README.md

@@ -11,7 +11,12 @@
 
 ```
 
-**Agent orchestration in ~2.4K lines of core. One required dep ([bareguard](https://npmjs.com/package/bareguard)). 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,11 +77,13 @@ 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 |
-| **MCP Bridge** | Auto-discover MCP servers from IDE configs (Claude Code, Cursor, etc.), expose as bareagent tools. Static allow/deny via `.mcp-bridge.json`, `systemContext` for LLM awareness. Runtime policy lives in `Loop({ policy })` — one hook for MCP + native tools alike. Zero deps |
+| **MCP Bridge** | Auto-discover MCP servers from IDE configs (Claude Code, Cursor, etc.), expose as bareagent tools. Static allow/deny via `.mcp-bridge.json`, `systemContext` for LLM awareness. Runtime policy lives in `Loop({ policy })` — one hook for MCP + native tools alike. Returns both bulk `tools` (one per MCP tool) and `metaTools` (`mcp_discover` + `mcp_invoke` for token-thrifty access to large catalogs). Zero deps |
+| **Spawn** | Fork a child bareagent process as a specialist agent. LLM-callable form blocks until child exits; library form returns a handle (`wait`, `onLine`, `kill`). One JSONL channel per child — child stderr captured and re-emitted as `child:stderr` events on the parent stream. Threads `BAREGUARD_AUDIT_PATH` / `BAREGUARD_PARENT_RUN_ID` / `BAREGUARD_BUDGET_FILE` / `BAREGUARD_SPAWN_DEPTH` so the family stitches into one audit + budget. `bareguard ^0.2.0` adds `spawn.ratePerMinute` + `limits.maxDepth` per-family caps |
+| **Defer** | Append a `{action, when}` record to a JSONL queue for a separate waker (cron / systemd timer / `examples/wake.sh`) to fire later. Two-phase governance: emit-time `gate.check` on the `defer` action; fire-time `gate.check` on the inner action when the waker re-invokes. `bareguard ^0.2.0` adds `defer.ratePerMinute` family-wide cap |
 
 **Providers:** OpenAI-compatible (OpenAI, OpenRouter, Groq, vLLM, LM Studio), Anthropic, Ollama, CLIPipe (any CLI tool via stdin/stdout with real-time streaming), Fallback, or bring your own (one method: `generate`). All return the same shape — swap freely.
 
@@ -84,7 +91,74 @@ Every piece works alone — take what you need, ignore the rest.
 
 **Cross-language:** Runs as a subprocess. Communicate via JSONL on stdin/stdout from Python, Go, Rust, Ruby, Java, or anything that can spawn a process. Ready-made wrappers in [`contrib/`](contrib/README.md).
 
-**Deps:** 1 required (`bareguard` for governance — single-gate policy + audit + budget). Optional: `cron-parser` (cron expressions), `better-sqlite3` (SQLite store), `barebrowse` (web browsing), `baremobile` (Android + iOS device control), `wearehere` (privacy assessment via barebrowse).
+**Deps:** 1 required (`bareguard ^0.2.0` for governance — single-gate policy + audit + budget + per-family rate caps). Optional: `cron-parser` (cron expressions), `better-sqlite3` (SQLite store), `barebrowse` (web browsing), `baremobile` (Android + iOS device control), `wearehere` (privacy assessment via barebrowse).
+
+---
+
+## 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).
 
 ---
 

package/bin/cli.js

@@ -1,7 +1,35 @@
 #!/usr/bin/env node
 'use strict';
 
+/**
+ * bin/cli.js — bareagent subprocess entry point.
+ *
+ * Two modes (auto-detected by flag presence):
+ *
+ *   1. Stdio JSONL mode (no --config):
+ *      Reads JSONL requests `{ method, params: { goal | messages } }` from stdin,
+ *      runs Loop with no special tools, emits JSONL events on stdout. Used by
+ *      contrib/ subprocess wrappers and ad-hoc invocations.
+ *
+ *   2. Config-driven agent mode (--config <path>):
+ *      Loads a JSON specialist/orchestrator config, wires the configured tools
+ *      and bareguard Gate, reads ONE input record from stdin, runs Loop, emits
+ *      JSONL events on stdout, exits when loop:done fires. This is what the
+ *      `spawn` tool uses to fork child agents (PRD §10.6).
+ *
+ *      Config schema (v0.9):
+ *      {
+ *        "systemPrompt":  "string",
+ *        "provider":      "openai" | "anthropic" | "ollama",
+ *        "model":         "gpt-4o-mini" (etc),
+ *        "tools":         ["shell_read", "shell_grep", "spawn", "defer", ...],
+ *        "gate":          { ...bareguard config; humanChannel headless-defaults to deny }
+ *      }
+ */
+
 const { createInterface } = require('node:readline');
+const fs = require('node:fs');
+const path = require('node:path');
 const { Loop } = require('../src/loop');
 const { Stream } = require('../src/stream');
 const { JsonlTransport } = require('../src/transport-jsonl');
@@ -12,60 +40,221 @@ const flag = (name) => {
   return i >= 0 ? args[i + 1] : undefined;
 };
 
-const providerName = flag('provider') || 'openai';
-const model = flag('model');
+const configPath = flag('config');
+
+if (configPath) {
+  runConfigMode(configPath).catch((err) => {
+    process.stdout.write(JSON.stringify({ type: 'loop:error', data: { source: 'cli', error: err.message } }) + '\n');
+    process.exit(1);
+  });
+} else {
+  runStdioMode();
+}
+
+// ─── Mode 2: config-driven ────────────────────────────────────────────────
+
+async function runConfigMode(cfgPath) {
+  const cfg = readConfig(cfgPath);
+  const stream = new Stream({ transport: new JsonlTransport() });
+
+  // Provider
+  const provider = createProvider(cfg.provider || 'openai', cfg.model);
+
+  // Tools — registry resolved by name from a curated set of built-ins.
+  const tools = await resolveTools(cfg.tools || [], { stream });
+
+  // Bareguard Gate (optional but strongly recommended for spawn children)
+  let policy = null;
+  let wrapToolsFn = (t) => t;
+  if (cfg.gate) {
+    try {
+      const { Gate } = require('bareguard');
+      const { wireGate } = require('../src/bareguard-adapter');
+
+      // Headless humanChannel default: warn once, deny safely. Overridden if
+      // the config explicitly sets humanChannel (rare in JSON, but supported
+      // via a require path).
+      let humanChannel = cfg.gate.humanChannel;
+      if (typeof humanChannel === 'string') {
+        // Allow `humanChannel: "./my-channel.js"` — load from a file relative to config.
+        const fnPath = path.resolve(path.dirname(cfgPath), humanChannel);
+        humanChannel = require(fnPath);
+      }
+      if (typeof humanChannel !== 'function') {
+        let warned = false;
+        humanChannel = async (event) => {
+          if (!warned) {
+            process.stderr.write(`[cli] no humanChannel configured — ${event.kind} on ${event.rule} auto-denying.\n`);
+            warned = true;
+          }
+          return { decision: 'deny' };
+        };
+      }
+
+      const gate = new Gate({ ...cfg.gate, humanChannel });
+      await gate.init();
+      const wired = wireGate(gate);
+      policy = wired.policy;
+      wrapToolsFn = wired.wrapTools;
+    } catch (err) {
+      process.stderr.write(`[cli] failed to wire bareguard: ${err.message}. Continuing without policy gate.\n`);
+    }
+  }
+
+  // Read ONE input record from stdin (JSON or raw string). Treat blank stdin
+  // as no input — let the systemPrompt drive the loop alone.
+  const stdin = await readStdin();
+  const initialMessage = buildInitialMessage(cfg, stdin);
+
+  const loop = new Loop({
+    provider,
+    system: cfg.systemPrompt || null,
+    stream,
+    policy,
+    onError: (err, meta) => {
+      process.stderr.write(`[loop:error ${meta.source}] ${err.message}\n`);
+    },
+  });
+
+  const wrapped = wrapToolsFn(tools);
+  await loop.run([initialMessage], wrapped);
+  // Stream's loop:done event has already been emitted; exit clean.
+  process.exit(0);
+}
 
-function createProvider() {
-  if (providerName === 'openai') {
+function readConfig(cfgPath) {
+  const abs = path.resolve(cfgPath);
+  let raw;
+  try { raw = fs.readFileSync(abs, 'utf8'); }
+  catch (err) { throw new Error(`[cli] cannot read config at ${abs}: ${err.message}`); }
+  try { return JSON.parse(raw); }
+  catch (err) { throw new Error(`[cli] config at ${abs} is not valid JSON: ${err.message}`); }
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let buf = '';
+    if (process.stdin.isTTY) return resolve('');
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { buf += chunk; });
+    process.stdin.on('end', () => resolve(buf.trim()));
+    // Safety: don't hang forever if stdin never closes.
+    setTimeout(() => resolve(buf.trim()), 100).unref();
+  });
+}
+
+function buildInitialMessage(cfg, stdin) {
+  if (!stdin) {
+    return { role: 'user', content: cfg.defaultPrompt || 'Begin.' };
+  }
+  // Try to parse as JSON; fall back to raw string.
+  let parsed;
+  try { parsed = JSON.parse(stdin); } catch { /* fine */ }
+  if (parsed && typeof parsed === 'object') {
+    if (typeof parsed.content === 'string') {
+      return { role: 'user', content: parsed.content };
+    }
+    return { role: 'user', content: JSON.stringify(parsed) };
+  }
+  return { role: 'user', content: stdin };
+}
+
+async function resolveTools(names, ctx) {
+  const tools = [];
+  for (const name of names) {
+    const resolved = await resolveOneTool(name, ctx);
+    if (resolved) tools.push(...(Array.isArray(resolved) ? resolved : [resolved]));
+  }
+  return tools;
+}
+
+async function resolveOneTool(name, ctx) {
+  switch (name) {
+    case 'shell_read':
+    case 'shell_grep':
+    case 'shell_run':
+    case 'shell_exec': {
+      const { createShellTools } = require('../tools/shell');
+      const { tools } = createShellTools();
+      return tools.find(t => t.name === name) || null;
+    }
+    case 'shell_*': {
+      const { createShellTools } = require('../tools/shell');
+      return createShellTools().tools;
+    }
+    case 'spawn': {
+      const { createSpawnTool } = require('../tools/spawn');
+      return createSpawnTool({ stream: ctx.stream }).tool;
+    }
+    case 'defer': {
+      const { createDeferTool } = require('../tools/defer');
+      return createDeferTool().tool;
+    }
+    default:
+      process.stderr.write(`[cli] unknown tool name in config: ${name}\n`);
+      return null;
+  }
+}
+
+// ─── Mode 1: stdio JSONL (legacy) ─────────────────────────────────────────
+
+function runStdioMode() {
+  const providerName = flag('provider') || 'openai';
+  const model = flag('model');
+  const stream = new Stream({ transport: new JsonlTransport() });
+  const loop = new Loop({ provider: createProvider(providerName, model), stream });
+
+  let pending = 0;
+  let closing = false;
+
+  const rl = createInterface({ input: process.stdin });
+  rl.on('line', async (line) => {
+    pending++;
+    try {
+      const req = JSON.parse(line);
+      const messages = req.params?.messages || [
+        { role: 'user', content: req.params?.goal || '' },
+      ];
+      const result = await loop.run(messages, []);
+      stream.emit({ type: 'result', data: result });
+    } catch (err) {
+      stream.emit({ type: 'error', data: { error: err.message } });
+    } finally {
+      pending--;
+      if (closing && pending === 0) process.exit(0);
+    }
+  });
+
+  rl.on('close', () => {
+    closing = true;
+    if (pending === 0) process.exit(0);
+  });
+}
+
+// ─── Shared: provider construction ────────────────────────────────────────
+
+function createProvider(name, model) {
+  if (name === 'openai') {
     const { OpenAIProvider } = require('../src/provider-openai');
     return new OpenAIProvider({
       apiKey: process.env.OPENAI_API_KEY,
       ...(model && { model }),
     });
   }
-  if (providerName === 'anthropic') {
+  if (name === 'anthropic') {
     const { AnthropicProvider } = require('../src/provider-anthropic');
     return new AnthropicProvider({
       apiKey: process.env.ANTHROPIC_API_KEY,
       ...(model && { model }),
     });
   }
-  if (providerName === 'ollama') {
+  if (name === 'ollama') {
     const { OllamaProvider } = require('../src/provider-ollama');
     return new OllamaProvider({
       ...(model && { model }),
       ...(flag('url') && { url: flag('url') }),
     });
   }
-  process.stderr.write(`Unknown provider: ${providerName}\n`);
+  process.stderr.write(`Unknown provider: ${name}\n`);
   process.exit(1);
 }
-
-const stream = new Stream({ transport: new JsonlTransport() });
-const loop = new Loop({ provider: createProvider(), stream });
-
-let pending = 0;
-let closing = false;
-
-const rl = createInterface({ input: process.stdin });
-rl.on('line', async (line) => {
-  pending++;
-  try {
-    const req = JSON.parse(line);
-    const messages = req.params?.messages || [
-      { role: 'user', content: req.params?.goal || '' },
-    ];
-    const result = await loop.run(messages, []);
-    stream.emit({ type: 'result', data: result });
-  } catch (err) {
-    stream.emit({ type: 'error', data: { error: err.message } });
-  } finally {
-    pending--;
-    if (closing && pending === 0) process.exit(0);
-  }
-});
-
-rl.on('close', () => {
-  closing = true;
-  if (pending === 0) process.exit(0);
-});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "files": [
     "index.js",
     "src/",
@@ -9,7 +9,7 @@
     "LICENSE",
     "NOTICE"
   ],
-  "description": "Lightweight, composable agent orchestration for autonomous agents. Single-gate governance via bareguard, cross-platform shell tools, MCP bridge. ~2.4K lines core, one required dep.",
+  "description": "Lightweight, composable agent orchestration for autonomous agents. Multi-agent primitives (spawn, defer, MCP meta-tools), single-gate governance via bareguard, cross-platform shell tools, MCP bridge. ~2.7K lines core, one required dep.",
   "license": "Apache-2.0",
   "author": "hamr0",
   "repository": {
@@ -44,7 +44,7 @@
     "governance"
   ],
   "dependencies": {
-    "bareguard": "^0.1.1"
+    "bareguard": "^0.2.0"
   },
   "optionalDependencies": {
     "barebrowse": "^0.5.0",
@@ -60,6 +60,6 @@
     }
   },
   "scripts": {
-    "test": "node --test test/**/*.test.js"
+    "test": "node --test --test-force-exit test/**/*.test.js"
   }
 }

package/src/bareguard-adapter.js

@@ -1,25 +1,34 @@
 '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).
+ * @returns {{policy: Function, onLlmResult: Function, onToolResult: Function, filterTools: Function, wrapTool: Function, wrapTools: Function}}
  *
  * @example
  *   const { Gate } = require('bareguard');
@@ -30,29 +39,84 @@
  *     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');
+  }
+  const formatDeny = options.formatDeny || defaultFormatDeny;
 
   const policy = async (toolName, args, ctx) => {
     const decision = await gate.check({ type: toolName, args, _ctx: 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 }) => {
+    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 = { type: name, args, _ctx: ctx ?? null };
+    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 +151,12 @@ 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`;
 }
 
 module.exports = { wireGate };

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,
 };