bare-agent 0.15.0 → 0.16.1

package/README.md

@@ -66,8 +66,9 @@ Every piece works alone — take what you need, ignore the rest.
 
 | Component | What it does |
 |---|---|
-| **Loop** | Think → act → observe → repeat. Calls any LLM, executes your tools, loops until done. Returns estimated USD cost per run. Governance via `Loop({ policy })` — wire bareguard's `Gate` through `wireGate(gate)` and every tool call (native, MCP, browsing, mobile) traverses one chokepoint with per-caller `ctx` routing. Bareguard owns the audit log, budget caps, and halt decisions; Loop respects the verdict. Context engineering via `Loop({ assemble })` — a per-round `assemble(msgs, ctx)` chokepoint to recall/compress/trim the window sent to the model (the seam litectx plugs into); returns a view, the canonical transcript stays intact, fail-open. The exported `unitAssembler`/`toUnits`/`fromUnits` adapter lets a consumer work over a neutral unit `{id, role, content, kind, pinned, atomic, tokensApprox}` — bareagent owns the grammar (atomic tool-pair bundling, pinned system/task, a pairing seatbelt), the consumer owns content + relevance. The CE function reads its inputs from the per-run `ctx` — litectx's budget-fitter uses `ctx.budget` (and `ctx.task`), so you **must** populate it via `run(msgs, tools, { ctx })`: an unset `ctx.budget` means the fitter has no budget, keeps everything, and returns the window unchanged — a silent no-op, not a bug (see `examples/litectx-assemble.mjs`). For summary-window compaction the Loop also lends a provider-bound `ctx.summarize(excerpt) => Promise<string>` (R-C6): the consumer owns when/what to summarize and the splice, bareagent makes the one model call (counted against the budget via `onLlmResult`, tagged `kind:'summarize'`). For an unbounded long-running agent there's the **destructive** counterpart `Loop({ trim })` (RT-2) — a per-round bound on the canonical transcript that evicts old turns *after* harvesting them; wire it with the exported `unitTrimmer({ trim, onHarvest, policy })` over litectx's `trim` verb (harvest-before-evict, fail-open; `harvestKey` gives the stable upsert id), opt-in (requires a consumer on litectx ≥ 0.16.0). `onError` + `loop:error` surface every silent-ish failure (callback throw, Checkpoint timeout) |
+| **Loop** | Think → act → observe → repeat. Calls any LLM, runs your tools, loops until done, returns estimated USD cost per run. Three opt-in seams hook external libraries in without touching your code: **`policy`** (governance — wire bareguard for one gated chokepoint over every tool call), **`assemble`** (context engineering — recall/compress/trim the window per round; the seam [litectx](https://npmjs.com/package/litectx) plugs into, transcript untouched), and **`trim`** (destructively bound the transcript for unbounded runs, harvesting turns before eviction). Each is a single chokepoint, fail-open, off by default. `onError` + `loop:error` surface every silent failure |
 | **Planner** | Break a goal into a step DAG via LLM. Built-in caching (`cacheTTL`) |
+| **assessComplexity** | Pure-code pre-planner (no LLM): rates a goal `simple`/`medium`/`complex`/`critical` from its text via keyword scoring + a critical safety override. `needsPlanning` gates whether to spend a Planner pass; `critical` flags security/production/compliance work for extra scrutiny. Free, instant, debuggable via `signals` |
 | **runPlan** | Execute steps in parallel waves. Dependency-aware, failure propagation, per-step retry |
 | **Retry** | Exponential/linear backoff with jitter. Respects `err.retryable` |
 | **CircuitBreaker** | Fail fast after N errors. Auto-recovers after cooldown. Per-key isolation |
@@ -78,13 +79,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, 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')` |
+| **bareguard adapter** | `wireGate(gate)` → `{ policy, onLlmResult, onToolResult, filterTools, formatDeny }`: one-line wiring to bareguard's `Gate`. Routes every LLM + tool result through the gate so budget caps cover token-heavy workloads, drops denied tools before the LLM ever sees them, and turns halts into a clean exit. `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. Returns both bulk `tools` (one per MCP tool) and `metaTools` (`mcp_discover` + `mcp_invoke` for token-thrifty access to large catalogs). Connecting runs a server's `command` (which may come from a cwd `.mcp.json`): pass `confirmServer` to vet each before it spawns — otherwise the bridge warns naming every command it runs. Every RPC is time-bounded (`timeout` for the handshake, `callTimeout` for `tools/call`), and a server that breaks its stdin pipe fails the connection instead of crashing the host. 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 |
+| **MCP Bridge** | Auto-discover MCP servers from your $HOME/IDE configs (Claude Code, Cursor, …) and expose them as bareagent tools — bulk (`tools`) or token-thrifty meta-tools (`mcp_discover` + `mcp_invoke`) for large catalogs. Same `Loop({ policy })` hook governs MCP and native tools alike. The project-cwd `.mcp.json` is **opt-in** (untrusted-repo safety); vet every server spawn with `confirmServer`; every RPC is time-bounded. Zero deps |
+| **Spawn** | Fork a child bareagent as a specialist agent — LLM-callable (blocks until exit) or a library handle (`wait`, `onLine`, `kill`). The whole family stitches into one audit log + budget; `bareguard ^0.2.0` adds per-family rate + depth caps. `timeoutMs` caps wall-clock, opt-in `idleTimeoutMs` kills a child gone silent (slow-but-working children survive) |
+| **Defer** | Queue a `{action, when}` record for a separate waker (cron / `examples/wake.sh`) to fire later. Governed twice — once when emitted, again when it fires. `bareguard ^0.2.0` adds a family-wide rate 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. The OpenAI provider warns if it would send your key over plaintext `http://` to a non-loopback host (use `https`, or drop `apiKey` for keyless local endpoints).
 
@@ -94,6 +95,8 @@ Every piece works alone — take what you need, ignore the rest.
 
 **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).
 
+This table is the map, not the manual — per-component wiring and API detail live in the [Integration Guide](bareagent.context.md) and [Usage Guide](docs/02-features/usage-guide.md).
+
 ---
 
 ## Recipes

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.15.0 | Node.js >= 18 | one required dep (`bareguard ^0.4.2`) | Apache 2.0
+> v0.16.1 | Node.js >= 18 | one required dep (`bareguard ^0.4.2`) | Apache 2.0
 >
 > Full human guide with composition examples, design philosophy, and recipes: [Usage Guide](docs/02-features/usage-guide.md)
 
@@ -14,7 +14,7 @@ npm install bare-agent
 ```
 
 Eight entry points:
-- `require('bare-agent')` — Loop, Planner, StateMachine, Scheduler, Checkpoint, Memory, Stream, Retry, runPlan, CircuitBreaker, wireGate, defaultActionTranslator, **toUnits, fromUnits, unitAssembler** (the `assemble` context-units adapter, v0.13+), **unitTrimmer, harvestKey** (the destructive `trim` seam adapter — RT-2 harvest-before-evict, needs a consumer on litectx ≥ 0.16.0), BareAgentError, ProviderError, ToolError, TimeoutError, ValidationError, CircuitOpenError, **HaltError**
+- `require('bare-agent')` — Loop, Planner, **assessComplexity** (pure-code no-LLM pre-planner → `{level, score, needsPlanning, signals}`), StateMachine, Scheduler, Checkpoint, Memory, Stream, Retry, runPlan, CircuitBreaker, wireGate, defaultActionTranslator, **toUnits, fromUnits, unitAssembler** (the `assemble` context-units adapter, v0.13+), **unitTrimmer, harvestKey** (the destructive `trim` seam adapter — RT-2 harvest-before-evict, needs a consumer on litectx ≥ 0.16.0), BareAgentError, ProviderError, ToolError, TimeoutError, ValidationError, CircuitOpenError, **HaltError**
 - `require('bare-agent/errors')` — same error classes via a stable subpath (v0.10.1+) for adopters who want to import only the error surface
 - `require('bare-agent/providers')` — OpenAI, Anthropic, Ollama, CLIPipe, Fallback (the canonical short names; `*Provider` aliases — `OpenAIProvider`, `AnthropicProvider`, etc. — are also exported and match the class names, so either destructure works, v0.12.1+)
 - `require('bare-agent/stores')` — SQLite (FTS5), JsonFile
@@ -31,6 +31,8 @@ Eight entry points:
 |---|---|
 | Call an LLM with tools and get a result | Loop + a Provider |
 | Break a goal into steps | Planner + a Provider |
+| Size a goal before planning (no LLM) | assessComplexity — `needsPlanning` gates a Planner pass |
+| Kill a spawned child that hangs silently | createSpawnTool / spawnChild `{ idleTimeoutMs }` |
 | Execute a step DAG with parallelism | runPlan + executeFn |
 | Track task state (pending/running/done/failed) | StateMachine |
 | Run agent turns on a schedule (cron, timers) | Scheduler |
@@ -249,16 +251,17 @@ invoked tool name lives in `args.name`. To deny specific MCP tools when
 using metaTools, use `tools.denyArgPatterns: { mcp_invoke: [/"name":"linear_admin_/] }`
 or `content.denyPatterns` over the serialized action.
 
-**Vetting server commands (v0.11.0).** Connecting to a server runs its
-`command`, and discovery reads `.mcp.json` from the cwd (an untrusted
-repo) as well as your home/IDE configs. Pass `confirmServer(name, def)
-=> boolean` to `createMCPBridge` to approve each server **before its
-command is spawned** (return `false` to skip it; a throw fails closed).
-Default trusts all discovered servers — unchanged behavior. **When no
-`confirmServer` is set, the bridge prints a one-time warning naming every
-command it is about to spawn** (before the first spawn, discovery included),
-so a cwd `.mcp.json` can't run a command unannounced — `confirmServer` is
-still how you actually *gate* it.
+**Vetting server commands (v0.11.0; cwd default tightened v0.16.1).** Connecting
+to a server runs its `command`. **Default discovery now scans only your
+$HOME/IDE configs — NOT the project-cwd `./.mcp.json`** (v0.16.1): a checked-in
+config in an untrusted repo would otherwise auto-spawn arbitrary commands. To
+include the project config, pass `createMCPBridge({ includeProjectConfig: true })`,
+or a `confirmServer` hook (which implies it, since the hook vets every command).
+Explicitly-passed `configPaths` are honored verbatim. Pass `confirmServer(name,
+def) => boolean` to approve each server **before its command is spawned** (return
+`false` to skip it; a throw fails closed). When no `confirmServer` is set, the
+bridge still trusts all *discovered* servers and prints a one-time warning naming
+every command it is about to spawn — `confirmServer` is how you actually *gate* it.
 
 **RPC timeouts (Unreleased).** Every JSON-RPC round-trip is now bounded, so a
 server that never answers can't hang the bridge or the loop. `opts.timeout`
@@ -552,13 +555,13 @@ new CLIPipe({ command: 'claude', args: ['--print'], systemPromptFlag: '--system-
 new CLIPipe({ command: 'ollama', args: ['run', 'llama3.2'] })
 ```
 
-All return `{ text, toolCalls, usage: { inputTokens, outputTokens } }`. CLIPipe always returns `toolCalls: []` and zero usage (CLI tools don't report tokens).
+All return `{ text, toolCalls, usage: { inputTokens, outputTokens }, model? }`. The optional `model` (v0.16.1+) is the id the response was produced by — Loop prefers it over `provider.model` for cost accounting. CLIPipe always returns `toolCalls: []` and zero usage (CLI tools don't report tokens), and omits `model`.
 
 **Error body (v0.11.0):** on an HTTP error the OpenAI/Anthropic/Ollama providers throw a `ProviderError` whose `message` carries the upstream error string. The full parsed response is **not** attached to `err.body` by default (so an unexpected field can't leak through logs that dump the error object). Pass `{ exposeErrorBody: true }` to attach it for debugging.
 
 **Plaintext-key warning (Unreleased):** the OpenAI provider's `baseUrl` accepts `http://` (for local/OpenAI-compatible endpoints), but a `Bearer` key sent over plaintext http to a **non-loopback** host is exposed on the wire. The provider now warns once when that happens. Loopback hosts (`localhost`/`127.0.0.0/8`/`::1` — local proxies, Ollama-style endpoints) stay silent, since that's the legitimate keyless-local case. The header is **not** stripped (some local proxies want a key), so use `https` for any remote endpoint, or drop `apiKey` when the local endpoint needs none.
 
-**Cost estimation:** Loop automatically estimates USD cost per run based on model and token usage. The `cost` field appears in every `loop.run()` result and in `loop:done` stream events. Pricing covers OpenAI and Anthropic models; unknown models use a default average. To adjust rates, edit `COST_PER_1K` at the top of `src/loop.js`.
+**Cost estimation:** Loop automatically estimates USD cost per run based on model and token usage. The `cost` field appears in every `loop.run()` result and in `loop:done` stream events. Pricing covers OpenAI and Anthropic models; unknown models use a default average. To adjust rates, edit `COST_PER_1K` at the top of `src/loop.js`. The model is resolved as `result.model || provider.model` (v0.16.1+) — providers now echo the model in their `generate()` result, so cost accounting holds even when `provider.model` is absent or varies per response, e.g. behind `FallbackProvider` or `CircuitBreaker.wrapProvider` (the wrapper also preserves `model`/`name` passthrough props). Wire `onLlmResult` (via `wireGate`) and a `budget.maxCostUsd` cap then halts on token-heavy workloads too.
 
 ## Store options
 
@@ -640,7 +643,7 @@ All error classes extend `Error` — `instanceof Error` always works. The `retry
 ## Key contracts
 
 - Loop builds messages in OpenAI format internally. Each provider normalizes to its native format.
-- `provider.generate(messages, tools, options)` must return `{ text, toolCalls, usage }`.
+- `provider.generate(messages, tools, options)` must return `{ text, toolCalls, usage }` (and may include `model` for accurate cost accounting).
 - Store must implement `store(content, metadata) → id`, `search(query, options) → [{id, content, metadata, score}]`, `get(id)`, `delete(id)`.
 - Components are independent: Memory doesn't know Loop, Scheduler doesn't know Planner. You compose them.
 

package/index.d.ts

@@ -1,5 +1,6 @@
 import { Loop } from "./src/loop";
 import { Planner } from "./src/planner";
+import { assessComplexity } from "./src/complexity";
 import { StateMachine } from "./src/state";
 import { Scheduler } from "./src/scheduler";
 import { Checkpoint } from "./src/checkpoint";
@@ -22,4 +23,4 @@ import { TimeoutError } from "./src/errors";
 import { ValidationError } from "./src/errors";
 import { CircuitOpenError } from "./src/errors";
 import { HaltError } from "./src/errors";
-export { Loop, Planner, StateMachine, Scheduler, Checkpoint, Memory, Stream, Retry, runPlan, CircuitBreaker, wireGate, defaultActionTranslator, toUnits, fromUnits, unitAssembler, unitTrimmer, harvestKey, BareAgentError, ProviderError, ToolError, TimeoutError, ValidationError, CircuitOpenError, HaltError };
+export { Loop, Planner, assessComplexity, StateMachine, Scheduler, Checkpoint, Memory, Stream, Retry, runPlan, CircuitBreaker, wireGate, defaultActionTranslator, toUnits, fromUnits, unitAssembler, unitTrimmer, harvestKey, BareAgentError, ProviderError, ToolError, TimeoutError, ValidationError, CircuitOpenError, HaltError };

package/index.js

@@ -2,6 +2,7 @@
 
 const { Loop } = require('./src/loop');
 const { Planner } = require('./src/planner');
+const { assessComplexity } = require('./src/complexity');
 const { StateMachine } = require('./src/state');
 const { Scheduler } = require('./src/scheduler');
 const { Checkpoint } = require('./src/checkpoint');
@@ -25,6 +26,7 @@ const {
 module.exports = {
   Loop,
   Planner,
+  assessComplexity,
   StateMachine,
   Scheduler,
   Checkpoint,

package/package.json

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

package/src/circuit-breaker.d.ts

@@ -57,14 +57,18 @@ export class CircuitBreaker {
      */
     reset(key?: string): void;
     /**
-     * Wrap a provider so generate() goes through the circuit breaker.
-     * @param {{ generate: (...args: any[]) => Promise<any> }} provider - Provider with generate().
+     * Wrap a provider so generate() goes through the circuit breaker. Passthrough props (e.g.
+     * `model`, `name`) are preserved so Loop cost accounting — which reads `provider.model` —
+     * keeps working through the wrapper.
+     * @param {{ generate: (...args: any[]) => Promise<any>, [k: string]: any }} provider - Provider with generate().
      * @param {string} [key] - Circuit key.
-     * @returns {{ generate: (...args: any[]) => Promise<any> }} Wrapped provider with generate().
+     * @returns {{ generate: (...args: any[]) => Promise<any>, [k: string]: any }} Wrapped provider.
      */
     wrapProvider(provider: {
         generate: (...args: any[]) => Promise<any>;
+        [k: string]: any;
     }, key?: string): {
         generate: (...args: any[]) => Promise<any>;
+        [k: string]: any;
     };
 }

package/src/circuit-breaker.js

@@ -112,13 +112,16 @@ class CircuitBreaker {
   }
 
   /**
-   * Wrap a provider so generate() goes through the circuit breaker.
-   * @param {{ generate: (...args: any[]) => Promise<any> }} provider - Provider with generate().
+   * Wrap a provider so generate() goes through the circuit breaker. Passthrough props (e.g.
+   * `model`, `name`) are preserved so Loop cost accounting — which reads `provider.model` —
+   * keeps working through the wrapper.
+   * @param {{ generate: (...args: any[]) => Promise<any>, [k: string]: any }} provider - Provider with generate().
    * @param {string} [key] - Circuit key.
-   * @returns {{ generate: (...args: any[]) => Promise<any> }} Wrapped provider with generate().
+   * @returns {{ generate: (...args: any[]) => Promise<any>, [k: string]: any }} Wrapped provider.
    */
   wrapProvider(provider, key) {
     return {
+      ...provider,
       /** @param {...any} args */
       generate: (...args) => this.call(() => provider.generate(...args), key),
     };

package/src/complexity.d.ts

@@ -0,0 +1,31 @@
+export type ComplexityResult = {
+    /**
+     * - Assessed complexity tier.
+     */
+    level: "simple" | "medium" | "complex" | "critical";
+    /**
+     * - Raw heuristic score (100 for a critical override).
+     */
+    score: number;
+    /**
+     * - false for `simple`, true otherwise — the routing hint.
+     */
+    needsPlanning: boolean;
+    /**
+     * - Which signals fired, for transparency/debugging.
+     */
+    signals: string[];
+};
+/**
+ * @typedef {object} ComplexityResult
+ * @property {'simple'|'medium'|'complex'|'critical'} level - Assessed complexity tier.
+ * @property {number} score - Raw heuristic score (100 for a critical override).
+ * @property {boolean} needsPlanning - false for `simple`, true otherwise — the routing hint.
+ * @property {string[]} signals - Which signals fired, for transparency/debugging.
+ */
+/**
+ * Assess the complexity of a goal/prompt from its text alone (no LLM).
+ * @param {string} prompt - The goal to classify.
+ * @returns {ComplexityResult}
+ */
+export function assessComplexity(prompt: string): ComplexityResult;

package/src/complexity.js

@@ -0,0 +1,149 @@
+'use strict';
+
+/**
+ * Keyword complexity assessor — a fast, pure-code "pre-planner" that classifies a goal as
+ * simple / medium / complex / critical from its text alone, with NO LLM call. Ported (concept,
+ * not line-for-line) from Aurora's SOAR keyword assessor. It exists to drive a routing decision:
+ * a `simple` goal can run single-shot; `medium`+ warrants a Planner pass; `critical` (security,
+ * production, compliance, financial) flags work that deserves extra scrutiny (e.g. a checkpoint /
+ * adversarial verification) before acting.
+ *
+ *   const { level, needsPlanning } = assessComplexity(goal);
+ *   const steps = needsPlanning ? await planner.plan(goal) : [{ id: 's1', action: goal }];
+ *
+ * Concept, deliberately lightweight: a critical-keyword override, tiered action-verb scoring
+ * (simple verbs subtract, complex verbs add the most), feature nouns + scope + structure signals,
+ * and two calibrated thresholds. It is a heuristic — transparent and debuggable via `signals`, not
+ * a model. On the upstream validation corpus it lands ~89% (the fuller LLM-free original ~95%);
+ * the gap is long-tail ambiguity ("add a button" is genuinely context-dependent).
+ */
+
+const has = (/** @type {Set<string>} */ words, /** @type {Set<string>} */ set) =>
+  [...set].filter(w => words.has(w));
+const wordSet = (/** @type {string} */ s) => new Set(s.match(/\b\w+\b/g) || []);
+// Escape regex metacharacters so a keyword can't break (or alter) the word-boundary match — the
+// lists below are plain words today, but a future entry like "c++" or ".net" must stay literal.
+const esc = (/** @type {string} */ k) => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const hasAny = (/** @type {string} */ s, /** @type {string[]} */ list) =>
+  list.some(k => new RegExp(`\\b${esc(k)}\\b`).test(s));
+
+// --- critical safety override: high-stakes work jumps straight to the top tier ---
+const CRIT_INCIDENT = ['emergency', 'outage', 'breach', 'vulnerability', 'exploit', 'corruption', 'data loss', 'incident', 'penetration'];
+const CRIT_COMPLIANCE = ['gdpr', 'hipaa', 'pci', 'compliance', 'regulation'];
+const SEC_CONTEXT = ['security', 'production', 'authentication', 'authorization'];
+const CRIT_ACTIONS = ['fix', 'patch', 'investigate', 'secure', 'protect', 'mitigate', 'prevent', 'respond', 'handle'];
+const FINANCIAL = ['payment', 'transaction', 'billing', 'financial'];
+const SECURE_ACTS = ['encrypt', 'secure', 'protect', 'audit'];
+
+/** @param {string} s lowercased prompt */
+function isCritical(s) {
+  if (hasAny(s, CRIT_INCIDENT) || hasAny(s, CRIT_COMPLIANCE)) return true;
+  if (hasAny(s, SEC_CONTEXT) && hasAny(s, CRIT_ACTIONS)) return true;     // e.g. "fix security ..."
+  if (hasAny(s, FINANCIAL) && hasAny(s, SECURE_ACTS)) return true;        // e.g. "encrypt payment ..."
+  return false;
+}
+
+// --- tiered keyword scoring: verb "weight" reflects how much work the ask implies ---
+const COMPLEX_VERBS = new Set(['implement', 'design', 'architect', 'refactor', 'integrate', 'migrate', 'build', 'create', 'develop', 'construct', 'engineer', 'establish', 'transform', 'overhaul', 'rewrite', 'restructure', 'optimize']);
+const ANALYSIS_VERBS = new Set(['explain', 'compare', 'analyze', 'debug', 'understand', 'investigate', 'describe', 'evaluate', 'review', 'examine', 'diagnose', 'trace', 'why', 'difference']);
+const MEDIUM_VERBS = new Set(['add', 'update', 'fix', 'write', 'change', 'modify', 'remove', 'delete', 'improve', 'enhance', 'extend', 'convert', 'rename', 'move', 'test', 'configure', 'setup', 'set', 'enable', 'disable']);
+const SIMPLE_VERBS = new Set(['what', 'show', 'list', 'get', 'find', 'print', 'check', 'read', 'open', 'run', 'where', 'which', 'display', 'view', 'see', 'tell', 'give', 'name', 'count', 'who', 'when', 'is']);
+const SCOPE = new Set(['all', 'every', 'entire', 'across', 'comprehensive', 'complete', 'codebase', 'project', 'system', 'application', 'full', 'whole', 'everything', 'throughout']);
+const DOMAINS = new Set(['security', 'performance', 'scalability', 'reliability', 'testing', 'authentication', 'authorization', 'caching', 'logging', 'monitoring', 'database', 'api', 'frontend', 'backend', 'infrastructure', 'deployment', 'docker', 'kubernetes', 'microservices', 'distributed']);
+// Feature/system nouns: paired with an action verb they signal a real feature, not a one-liner.
+const COMPLEX_NOUNS = new Set(['authentication', 'authorization', 'oauth', 'jwt', 'session', 'sessions', 'pipeline', 'workflow', 'notification', 'notifications', 'dashboard', 'crud', 'plugin', 'framework', 'websocket', 'websockets', 'realtime', 'pagination', 'search', 'validation', 'migration', 'schema', 'registration']);
+const SEQUENCE = ['first', 'then', 'after that', 'finally', 'next', 'afterwards', 'subsequently', 'step by step', 'and then', 'as well as', 'additionally', 'along with'];
+const CONSTRAINTS = ['without breaking', 'without changing', 'maintaining', 'ensuring', 'backward compatible', 'backwards compatible', 'must not', 'should not', 'preserve', 'without affecting'];
+
+const SIMPLE_THRESHOLD = 11;
+const MEDIUM_THRESHOLD = 28;
+
+// Bound the text the assessor scans. Several signal patterns contain `.*`, which can backtrack
+// quadratically on adversarial input (e.g. "integrate "×N with no "with" — O(n²)). Complexity is
+// fully determined by the opening of a goal, so capping the working string makes every scan
+// linear-bounded and removes the DoS surface for callers that pass untrusted end-user text.
+const MAX_ASSESS_LEN = 4000;
+
+/**
+ * @typedef {object} ComplexityResult
+ * @property {'simple'|'medium'|'complex'|'critical'} level - Assessed complexity tier.
+ * @property {number} score - Raw heuristic score (100 for a critical override).
+ * @property {boolean} needsPlanning - false for `simple`, true otherwise — the routing hint.
+ * @property {string[]} signals - Which signals fired, for transparency/debugging.
+ */
+
+/**
+ * Assess the complexity of a goal/prompt from its text alone (no LLM).
+ * @param {string} prompt - The goal to classify.
+ * @returns {ComplexityResult}
+ */
+function assessComplexity(prompt) {
+  if (typeof prompt !== 'string' || !prompt.trim()) {
+    return { level: 'simple', score: 0, needsPlanning: false, signals: ['empty'] };
+  }
+  const text = prompt.trim().slice(0, MAX_ASSESS_LEN);
+  const lower = text.toLowerCase();
+  if (isCritical(lower)) {
+    return { level: 'critical', score: 100, needsPlanning: true, signals: ['critical_override'] };
+  }
+
+  const words = wordSet(lower);
+  const wc = text.split(/\s+/).length;
+  /** @type {string[]} */
+  const signals = [];
+  let score = 0;
+  /** @param {number} n @param {string} [sig] */
+  const add = (n, sig) => { score += n; if (sig) signals.push(sig); };
+
+  const complex = has(words, COMPLEX_VERBS);
+  const analysis = has(words, ANALYSIS_VERBS);
+  const medium = has(words, MEDIUM_VERBS);
+  const simple = has(words, SIMPLE_VERBS);
+  const scope = has(words, SCOPE);
+  const domains = has(words, DOMAINS);
+
+  if (complex.length) add(complex.length * 25, 'complex_verbs');
+  if (analysis.length) add(Math.min(analysis.length * 15, 20), 'analysis_verbs');
+  if (medium.length) add(medium.length * 12, 'medium_verbs');
+  if (simple.length) add(-Math.min(simple.length * 3, 10), 'simple_verbs');
+  if (scope.length) add(scope.length * 12, 'scope');
+  if (domains.length > 1) add(domains.length * 8, 'multi_domain');
+  else if (domains.length) add(5, 'domain');
+
+  // feature noun + an action verb => a real feature (pushes single-verb asks up a tier)
+  const nouns = has(words, COMPLEX_NOUNS);
+  if (nouns.length && (medium.length || complex.length)) add(nouns.length * 10, 'feature_nouns');
+  if (/\b(?:dark\s*mode|feature\s*flags?|real-?time|end-?to-?end|full-?stack)\b/.test(lower)) add(12, 'feature_pattern');
+  if (/\bintegrate\b.*\bwith\b/.test(lower)) add(15, 'integration');
+  if (/\b(?:improve|optimize)\s+(?:performance|speed|efficiency)\b/.test(lower)
+    && !/\b(?:this|the)\s+(?:function|method|query|loop)\b/.test(lower)) add(15, 'open_ended');
+
+  // structure / sequencing — multi-step asks are heavier
+  const seq = SEQUENCE.filter(m => lower.includes(m)).length;
+  if (seq) add(seq * 8, 'sequence');
+  const constraints = CONSTRAINTS.filter(m => lower.includes(m)).length;
+  if (constraints) add(constraints * 12, 'constraints');
+  const listItems = (text.match(/(?:^|\n)\s*(?:\d+[.)]|[-*])\s/g) || []).length;
+  if (listItems) add(listItems * 9, 'list');
+
+  // length: longer prompts trend more complex
+  if (wc > 40) add(15, 'long'); else if (wc > 20) add(10); else if (wc > 10) add(5);
+
+  // architectural / open-ended questions read simple lexically but imply design work
+  if (/\bbest\s+(?:way|approach|practice|architecture)\b|\barchitecture\s+for\b|\bhow (?:should|can|do) (?:we|i)\b.*\b(?:handle|design|implement|build)\b/.test(lower)) add(15, 'design_question');
+  if (/^(?:what is|where is|which|who|is there)\b/.test(lower)) add(-8, 'simple_question');
+
+  // a trivial edit (typo, comment, log line, version bump) stays simple even though its verb is
+  // "medium" weight — gated to trivial OBJECTS so real medium work isn't wrongly demoted.
+  const trivial = /\b(?:fix|add|remove|delete|rename|update|change)\b.*\b(?:typo|comment|console\.?log|variable|version|line|import)\b/.test(lower)
+    || /\bwrite\s+(?:a|the)\s+function\s+(?:that|to|which)\b/.test(lower);
+  if (trivial && !complex.length && !scope.length && wc <= 10) {
+    score = Math.min(score, SIMPLE_THRESHOLD);
+    signals.push('trivial_edit');
+  }
+
+  const level = score <= SIMPLE_THRESHOLD ? 'simple' : score <= MEDIUM_THRESHOLD ? 'medium' : 'complex';
+  return { level, score, needsPlanning: level !== 'simple', signals };
+}
+
+module.exports = { assessComplexity };

package/src/loop.js

@@ -331,7 +331,7 @@ class Loop {
         const startedAt = Date.now();
         const result = await loop.provider.generate(prompt, [], { temperature: 0, ...genOpts });
         const usage = (result && result.usage) || null;
-        const model = loop.provider.model || null;
+        const model = (result && result.model) || loop.provider.model || null;
         const cost = estimateCost(model, usage);
         if (cost !== null) totalCost += cost;
         loop._safeEmit({ type: 'loop:summarize', data: { usage, costUsd: cost, durationMs: Date.now() - startedAt } });
@@ -421,7 +421,9 @@ class Loop {
       }
 
       lastUsage = result.usage || lastUsage;
-      const model = this.provider.model || null;
+      // Prefer the model the response reports (robust when provider.model is absent or varies per
+      // response — e.g. FallbackProvider, or a CircuitBreaker-wrapped provider that drops .model).
+      const model = result.model || this.provider.model || null;
       const roundCost = estimateCost(model, lastUsage);
       if (roundCost !== null) totalCost += roundCost;
 

package/src/mcp-bridge.d.ts

@@ -74,7 +74,11 @@ export type RpcClient = {
  *
  * @param {object} [opts]
  * @param {string} [opts.bridgePath] - Path to .mcp-bridge.json. Default: .mcp-bridge.json in cwd.
- * @param {string[]} [opts.configPaths] - IDE config paths for discovery.
+ * @param {string[]} [opts.configPaths] - Explicit config paths for discovery. When given, honored
+ *   verbatim. When omitted, only the trusted $HOME/IDE defaults are scanned (NOT `./.mcp.json`).
+ * @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 {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
@@ -82,16 +86,17 @@ export type RpcClient = {
  * @param {boolean} [opts.refresh=false] - Force re-discovery regardless of TTL.
  * @param {(name: string, def: ServerDef) => boolean | Promise<boolean>} [opts.confirmServer]
  *   Vet each discovered server BEFORE its `command` is spawned. Connecting to an
- *   MCP server runs its command, and discovery reads configs from the cwd (a
- *   `.mcp.json` in an untrusted repo) as well as the user's home/IDE configs.
- *   Return false to skip a server (its command is never executed). A throw is
- *   treated as a deny (fail-closed). Default: every discovered server is trusted
- *   (unchanged behavior) — pass this to gate command execution.
+ *   MCP server runs its command. Return false to skip a server (its command is
+ *   never executed). A throw is treated as a deny (fail-closed). Default: every
+ *   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}>}
  */
 export function createMCPBridge(opts?: {
     bridgePath?: string | undefined;
     configPaths?: string[] | undefined;
+    includeProjectConfig?: boolean | undefined;
     servers?: string[] | undefined;
     timeout?: number | undefined;
     callTimeout?: number | undefined;
@@ -110,10 +115,15 @@ export function createMCPBridge(opts?: {
     close: Function;
 }>;
 /**
- * @param {string[]} [configPaths]
+ * @param {string[]} [configPaths] - Explicit config paths. When given, honored verbatim (the
+ *   caller owns the choice). When omitted, the trusted $HOME/IDE defaults are scanned.
+ * @param {{ includeProjectConfig?: boolean }} [opts] - When no explicit `configPaths` are given,
+ *   set `includeProjectConfig: true` to also scan `./.mcp.json`. Default false — see PROJECT_CONFIG_PATH.
  * @returns {Map<string, ServerDef>}
  */
-export function discoverServers(configPaths?: string[]): Map<string, ServerDef>;
+export function discoverServers(configPaths?: string[], { includeProjectConfig }?: {
+    includeProjectConfig?: boolean;
+}): Map<string, ServerDef>;
 /**
  * Build the LLM-callable meta-tool surface from a fully-connected bridge.
  * Shares the underlying tool array and RPC clients with the bulk surface —

package/src/mcp-bridge.js

@@ -62,8 +62,12 @@ const { ToolError } = require('./errors');
 
 // --- Config discovery (from IDE configs) ---
 
-const DEFAULT_CONFIG_PATHS = [
-  () => join(process.cwd(), '.mcp.json'),                              // project
+// The project-cwd `.mcp.json` is the untrusted-repo vector: discovering it auto-spawns its
+// `command`, so cloning a hostile repo and running an agent inside it would be arbitrary code
+// execution. It is therefore NOT in the trusted defaults — these are user/IDE-authored configs
+// under $HOME, which the user owns. The project config is opt-in (see `includeProjectConfig`).
+const PROJECT_CONFIG_PATH = () => join(process.cwd(), '.mcp.json');
+const TRUSTED_CONFIG_PATHS = [
   () => join(homedir(), '.mcp.json'),                                  // home
   () => join(homedir(), '.claude', 'mcp_servers.json'),                // Claude Code
   () => join(homedir(), '.config', 'Claude', 'claude_desktop_config.json'), // Claude Desktop
@@ -71,11 +75,22 @@ const DEFAULT_CONFIG_PATHS = [
 ];
 
 /**
- * @param {string[]} [configPaths]
+ * @param {string[]} [configPaths] - Explicit config paths. When given, honored verbatim (the
+ *   caller owns the choice). When omitted, the trusted $HOME/IDE defaults are scanned.
+ * @param {{ includeProjectConfig?: boolean }} [opts] - When no explicit `configPaths` are given,
+ *   set `includeProjectConfig: true` to also scan `./.mcp.json`. Default false — see PROJECT_CONFIG_PATH.
  * @returns {Map<string, ServerDef>}
  */
-function discoverServers(configPaths) {
-  const paths = configPaths || DEFAULT_CONFIG_PATHS.map(fn => fn());
+function discoverServers(configPaths, { includeProjectConfig = false } = {}) {
+  let paths;
+  if (configPaths) {
+    paths = configPaths;
+  } else {
+    paths = TRUSTED_CONFIG_PATHS.map(fn => fn());
+    // Project config kept at highest precedence (front) when explicitly opted in — preserves the
+    // historical "project overrides home" ordering for callers that want it.
+    if (includeProjectConfig) paths.unshift(PROJECT_CONFIG_PATH());
+  }
   /** @type {Map<string, ServerDef>} */
   const servers = new Map();
 
@@ -594,7 +609,11 @@ function buildMetaTools(tools, discoveredAt) {
  *
  * @param {object} [opts]
  * @param {string} [opts.bridgePath] - Path to .mcp-bridge.json. Default: .mcp-bridge.json in cwd.
- * @param {string[]} [opts.configPaths] - IDE config paths for discovery.
+ * @param {string[]} [opts.configPaths] - Explicit config paths for discovery. When given, honored
+ *   verbatim. When omitted, only the trusted $HOME/IDE defaults are scanned (NOT `./.mcp.json`).
+ * @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 {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
@@ -602,11 +621,11 @@ function buildMetaTools(tools, discoveredAt) {
  * @param {boolean} [opts.refresh=false] - Force re-discovery regardless of TTL.
  * @param {(name: string, def: ServerDef) => boolean | Promise<boolean>} [opts.confirmServer]
  *   Vet each discovered server BEFORE its `command` is spawned. Connecting to an
- *   MCP server runs its command, and discovery reads configs from the cwd (a
- *   `.mcp.json` in an untrusted repo) as well as the user's home/IDE configs.
- *   Return false to skip a server (its command is never executed). A throw is
- *   treated as a deny (fail-closed). Default: every discovered server is trusted
- *   (unchanged behavior) — pass this to gate command execution.
+ *   MCP server runs its command. Return false to skip a server (its command is
+ *   never executed). A throw is treated as a deny (fail-closed). Default: every
+ *   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}>}
  */
 async function createMCPBridge(opts = {}) {
@@ -632,9 +651,10 @@ async function createMCPBridge(opts = {}) {
     catch { return false; }
   };
 
-  // Connecting to a server EXECUTES its `command`, which can originate from a
-  // cwd-relative .mcp.json in an untrusted repo (discoverServers reads project
-  // configs). With no confirmServer hook, every discovered command runs unvetted.
+  // Connecting to a server EXECUTES its `command`. The project-cwd `.mcp.json` is excluded from
+  // default discovery (see TRUSTED_CONFIG_PATHS / includeProjectConfig), so the untrusted-repo
+  // path is closed by default; this warning covers the residual case where home/IDE configs (or an
+  // explicit opt-in) contribute commands and no confirmServer hook is present to vet them.
   // Warn ONCE per call, BEFORE the first spawn — and the first spawn is the
   // discovery phase on a cold/refresh run, not the main-connect phase below.
   let warnedUnvetted = false;
@@ -654,8 +674,11 @@ async function createMCPBridge(opts = {}) {
   const needsRefresh = opts.refresh || !config || isExpired(config);
 
   if (needsRefresh) {
-    // Discover from IDE configs
-    const discovered = discoverServers(opts.configPaths);
+    // Discover from IDE configs. The project-cwd `.mcp.json` is excluded by default (untrusted-repo
+    // RCE vector); it is scanned only on explicit opt-in, or when a `confirmServer` hook is present
+    // (which vets every command before it spawns, so cwd discovery is safe under it).
+    const includeProjectConfig = opts.includeProjectConfig === true || !!confirmServer;
+    const discovered = discoverServers(opts.configPaths, { includeProjectConfig });
 
     if (discovered.size === 0 && !config) {
       return { tools: [], servers: [], systemContext: '', denied: [], close: async () => {} };

package/src/provider-anthropic.js

@@ -83,6 +83,7 @@ class AnthropicProvider {
     return {
       text,
       toolCalls,
+      model: data.model || this.model,
       usage: {
         inputTokens: data.usage?.input_tokens || 0,
         outputTokens: data.usage?.output_tokens || 0,

package/src/provider-ollama.js

@@ -60,6 +60,7 @@ class OllamaProvider {
           ? JSON.parse(tc.function.arguments)
           : tc.function.arguments,
       })),
+      model: data.model || this.model,
       usage: {
         inputTokens: data.prompt_eval_count || 0,
         outputTokens: data.eval_count || 0,

package/src/provider-openai.js

@@ -72,6 +72,7 @@ class OpenAIProvider {
         name: tc.function.name,
         arguments: JSON.parse(tc.function.arguments),
       })),
+      model: data.model || this.model,
       usage: {
         inputTokens: data.usage?.prompt_tokens || 0,
         outputTokens: data.usage?.completion_tokens || 0,

package/tools/defer.js

@@ -133,16 +133,19 @@ async function readQueue(queuePath) {
   const path = resolveQueuePath(queuePath);
   try {
     const text = await fsp.readFile(path, 'utf8');
-    /** @type {Record<string, Record<string, any>>} */
-    const records = {};
+    // Fold append-only status lines by id (latest wins). A Map — not a plain object — so an
+    // attacker-influenced id from a tampered queue file (e.g. "__proto__", "constructor") is just
+    // an ordinary key and cannot reach the prototype-setter path. Also require a string id.
+    /** @type {Map<string, Record<string, any>>} */
+    const records = new Map();
     for (const line of text.split('\n')) {
       if (!line.trim()) continue;
       let r;
       try { r = JSON.parse(line); } catch { continue; }
-      if (!r.id) continue;
-      records[r.id] = { ...records[r.id], ...r };
+      if (typeof r.id !== 'string' || !r.id) continue;
+      records.set(r.id, { ...records.get(r.id), ...r });
     }
-    return Object.values(records);
+    return [...records.values()];
   } catch (/** @type {any} */ err) {
     if (err.code === 'ENOENT') return [];
     throw err;

package/tools/grep-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/tools/grep-worker.js

@@ -0,0 +1,20 @@
+'use strict';
+
+/**
+ * Worker thread for shell_grep's matching phase. Runs the (potentially expensive) regex search
+ * off the main thread so the parent can enforce a hard timeout via `worker.terminate()` — JS
+ * regex backtracking is uninterruptible on its own thread, so isolation is the only sound bound
+ * against catastrophic patterns that slip past the static guard. See tools/shell.js `grepPath`.
+ */
+
+const { workerData, parentPort } = require('node:worker_threads');
+const { _grepCore } = require('./shell.js');
+
+// parentPort is non-null inside a worker, but the type is nullable for the main-thread case.
+if (!parentPort) throw new Error('grep-worker.js must be run as a worker thread');
+const port = parentPort;
+
+_grepCore(workerData).then(
+  (result) => port.postMessage({ ok: true, result }),
+  (err) => port.postMessage({ ok: false, error: err && err.message ? err.message : String(err) }),
+);

package/tools/shell.d.ts

@@ -4,6 +4,12 @@ export type GrepArgs = {
     recursive?: boolean | undefined;
     maxMatches?: number | undefined;
     flags?: string | undefined;
+    /**
+     * - Hard wall-clock ceiling in ms (default 5000). The match runs in a
+     * worker thread; on overrun the worker is terminated and the call rejects, so a pattern that slips
+     * past `looksCatastrophic` can no longer hang the host event loop.
+     */
+    timeout?: number | undefined;
 };
 export type RunArgvArgs = {
     argv: string[];
@@ -29,3 +35,31 @@ export type ToolDef = import("../types").ToolDef;
 export function createShellTools(): {
     tools: ToolDef[];
 };
+/**
+ * @typedef {object} GrepArgs
+ * @property {string} pattern
+ * @property {string} path
+ * @property {boolean} [recursive]
+ * @property {number} [maxMatches]
+ * @property {string} [flags]
+ * @property {number} [timeout] - Hard wall-clock ceiling in ms (default 5000). The match runs in a
+ *   worker thread; on overrun the worker is terminated and the call rejects, so a pattern that slips
+ *   past `looksCatastrophic` can no longer hang the host event loop.
+ */
+/**
+ * The actual search: walk, skip binaries, regex-test each line. Runs in a worker thread (see
+ * grep-worker.js) so a runaway regex is killable via `worker.terminate()`. JS RegExp has no
+ * execution timeout and backtracking is uninterruptible on its own thread — isolation is the
+ * only sound bound (the static `looksCatastrophic` guard is a best-effort fast-reject, not a
+ * guarantee; a grounded bypass like `(a|a|a)*` passes it yet backtracks exponentially).
+ * @param {GrepArgs} args
+ */
+export function _grepCore({ pattern, path: rawPath, recursive, maxMatches, flags }: GrepArgs): Promise<{
+    hits: {
+        file: string;
+        line: number;
+        text: string;
+    }[];
+    truncated: boolean;
+    fileCount: number;
+}>;

package/tools/shell.js

@@ -17,9 +17,11 @@
 const fs = require('node:fs/promises');
 const path = require('node:path');
 const { exec, execFile } = require('node:child_process');
+const { Worker } = require('node:worker_threads');
 
 const DEFAULT_READ_MAX_BYTES = 256 * 1024;       // 256 KB
 const DEFAULT_GREP_MAX_MATCHES = 200;
+const DEFAULT_GREP_TIMEOUT_MS = 5_000;           // hard ceiling on a single grep — bounds ReDoS
 const DEFAULT_EXEC_TIMEOUT_MS = 30_000;
 const DEFAULT_EXEC_MAX_BUFFER = 1024 * 1024;     // 1 MB
 
@@ -137,18 +139,22 @@ function looksCatastrophic(pattern) {
  * @property {boolean} [recursive]
  * @property {number} [maxMatches]
  * @property {string} [flags]
+ * @property {number} [timeout] - Hard wall-clock ceiling in ms (default 5000). The match runs in a
+ *   worker thread; on overrun the worker is terminated and the call rejects, so a pattern that slips
+ *   past `looksCatastrophic` can no longer hang the host event loop.
  */
 
-/** @param {GrepArgs} args */
-async function grepPath({ pattern, path: rawPath, recursive = true, maxMatches, flags = 'i' }) {
+/**
+ * The actual search: walk, skip binaries, regex-test each line. Runs in a worker thread (see
+ * grep-worker.js) so a runaway regex is killable via `worker.terminate()`. JS RegExp has no
+ * execution timeout and backtracking is uninterruptible on its own thread — isolation is the
+ * only sound bound (the static `looksCatastrophic` guard is a best-effort fast-reject, not a
+ * guarantee; a grounded bypass like `(a|a|a)*` passes it yet backtracks exponentially).
+ * @param {GrepArgs} args
+ */
+async function _grepCore({ pattern, path: rawPath, recursive = true, maxMatches, flags = 'i' }) {
   const resolved = path.resolve(expandHome(rawPath));
   const cap = maxMatches || DEFAULT_GREP_MAX_MATCHES;
-  if (looksCatastrophic(pattern)) {
-    throw new Error(
-      `shell_grep: pattern rejected — nested unbounded quantifier (e.g. "(a+)+") risks catastrophic ` +
-      `backtracking that would block the process. Simplify the regex.`,
-    );
-  }
   let re;
   try {
     re = new RegExp(pattern, flags);
@@ -190,6 +196,53 @@ async function grepPath({ pattern, path: rawPath, recursive = true, maxMatches,
   return { hits, truncated, fileCount: files.length };
 }
 
+/**
+ * Public grep entry. Fast-rejects obviously catastrophic patterns without paying for a worker,
+ * then runs the search in a worker thread bounded by a hard timeout — so even a pattern that
+ * defeats the static guard degrades to a bounded rejection instead of an event-loop hang.
+ * @param {GrepArgs} args
+ */
+function grepPath(args) {
+  const { pattern, flags = 'i', timeout } = args;
+  if (looksCatastrophic(pattern)) {
+    return Promise.reject(new Error(
+      `shell_grep: pattern rejected — nested unbounded quantifier (e.g. "(a+)+") risks catastrophic ` +
+      `backtracking that would block the process. Simplify the regex.`,
+    ));
+  }
+  // Cheap up-front validation so a syntactically invalid regex fails clearly without a worker spin-up.
+  try {
+    new RegExp(pattern, flags);
+  } catch (/** @type {any} */ err) {
+    return Promise.reject(new Error(`shell_grep: invalid regex — ${err.message}`));
+  }
+
+  const budgetMs = timeout && timeout > 0 ? timeout : DEFAULT_GREP_TIMEOUT_MS;
+  return new Promise((resolve, reject) => {
+    const worker = new Worker(path.join(__dirname, 'grep-worker.js'), { workerData: args });
+    let settled = false;
+    const done = (fn, val) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      worker.terminate();
+      fn(val);
+    };
+    const timer = setTimeout(() => {
+      done(reject, new Error(
+        `shell_grep: pattern exceeded ${budgetMs}ms time budget — likely catastrophic backtracking. ` +
+        `Simplify the regex.`,
+      ));
+    }, budgetMs);
+    timer.unref?.();
+    worker.once('message', (msg) => {
+      if (msg && msg.ok) done(resolve, msg.result);
+      else done(reject, new Error((msg && msg.error) || 'shell_grep: worker failed'));
+    });
+    worker.once('error', (err) => done(reject, err));
+  });
+}
+
 /**
  * @typedef {object} RunArgvArgs
  * @property {string[]} argv
@@ -360,4 +413,4 @@ function createShellTools() {
   return { tools };
 }
 
-module.exports = { createShellTools };
+module.exports = { createShellTools, _grepCore };

package/tools/spawn.d.ts

@@ -42,9 +42,16 @@ export type SpawnChildOptions = {
      */
     cliPath?: string | undefined;
     /**
-     * - Force-kill child after this many ms.
+     * - Force-kill child after this many ms (wall-clock hard ceiling).
      */
     timeoutMs?: number | undefined;
+    /**
+     * - Force-kill child after this many ms with NO output on either
+     * stdout or stderr (heartbeat/liveness watchdog). The clock arms at spawn and resets on every JSONL
+     * line, so a child doing real work is never killed, but one that hangs silently is. Opt-in
+     * (0/undefined disables); independent of `timeoutMs`, which remains the absolute ceiling.
+     */
+    idleTimeoutMs?: number | undefined;
     /**
      * - bareagent Stream — child:stderr events get re-emitted here.
      */
@@ -56,13 +63,16 @@ export type Stream = import("../src/stream").Stream;
  *
  * @param {object} [options]
  * @param {string} [options.cliPath] - Override the bareagent CLI path (default: ./bin/cli.js relative to this file).
- * @param {number} [options.timeoutMs] - Force-kill child after this many ms (default 10 min).
+ * @param {number} [options.timeoutMs] - Force-kill child after this many ms (default 10 min, wall-clock ceiling).
+ * @param {number} [options.idleTimeoutMs] - Force-kill child after this many ms of no stdout/stderr output
+ *   (heartbeat watchdog; default off). Resets on every line, so slow-but-working children survive.
  * @param {Stream} [options.stream] - bareagent Stream instance — child:stderr events get re-emitted here.
  * @returns {{tool: import('../types').ToolDef, spawnChild: typeof spawnChild}}
  */
 export function createSpawnTool(options?: {
     cliPath?: string | undefined;
     timeoutMs?: number | undefined;
+    idleTimeoutMs?: number | undefined;
     stream?: import("../src/stream").Stream | undefined;
 }): {
     tool: import("../types").ToolDef;
@@ -86,12 +96,16 @@ export function createSpawnTool(options?: {
  * @property {string} [config] - Path to a bareagent config JSON file.
  * @property {*} [input] - Optional JSON input passed to the child on stdin.
  * @property {string} [cliPath] - Override the bareagent CLI path.
- * @property {number} [timeoutMs] - Force-kill child after this many ms.
+ * @property {number} [timeoutMs] - Force-kill child after this many ms (wall-clock hard ceiling).
+ * @property {number} [idleTimeoutMs] - Force-kill child after this many ms with NO output on either
+ *   stdout or stderr (heartbeat/liveness watchdog). The clock arms at spawn and resets on every JSONL
+ *   line, so a child doing real work is never killed, but one that hangs silently is. Opt-in
+ *   (0/undefined disables); independent of `timeoutMs`, which remains the absolute ceiling.
  * @property {Stream} [stream] - bareagent Stream — child:stderr events get re-emitted here.
  *
  * @param {SpawnChildOptions} [opts]
  */
-export function spawnChild({ config, input, cliPath, timeoutMs, stream }?: SpawnChildOptions): {
+export function spawnChild({ config, input, cliPath, timeoutMs, idleTimeoutMs, stream }?: SpawnChildOptions): {
     wait: () => Promise<{
         text: any;
         usage: any;
@@ -100,6 +114,7 @@ export function spawnChild({ config, input, cliPath, timeoutMs, stream }?: Spawn
         events: ChildEvent[];
         exitCode: any;
         signal: any;
+        idleKilled: boolean;
     }>;
     onLine: (fn: (event: ChildEvent) => void) => () => void;
     kill: (sig?: NodeJS.Signals) => void;

package/tools/spawn.js

@@ -66,12 +66,16 @@ function resolveCliPath() {
  * @property {string} [config] - Path to a bareagent config JSON file.
  * @property {*} [input] - Optional JSON input passed to the child on stdin.
  * @property {string} [cliPath] - Override the bareagent CLI path.
- * @property {number} [timeoutMs] - Force-kill child after this many ms.
+ * @property {number} [timeoutMs] - Force-kill child after this many ms (wall-clock hard ceiling).
+ * @property {number} [idleTimeoutMs] - Force-kill child after this many ms with NO output on either
+ *   stdout or stderr (heartbeat/liveness watchdog). The clock arms at spawn and resets on every JSONL
+ *   line, so a child doing real work is never killed, but one that hangs silently is. Opt-in
+ *   (0/undefined disables); independent of `timeoutMs`, which remains the absolute ceiling.
  * @property {Stream} [stream] - bareagent Stream — child:stderr events get re-emitted here.
  *
  * @param {SpawnChildOptions} [opts]
  */
-function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
+function spawnChild({ config, input, cliPath, timeoutMs, idleTimeoutMs, stream } = {}) {
   if (typeof config !== 'string' || !config) {
     throw new Error('[spawn] requires { config: <path> }');
   }
@@ -104,10 +108,29 @@ function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
     if (i >= 0) lineSubscribers.splice(i, 1);
   }; };
 
+  // Idle watchdog: kill the child after `idleTimeoutMs` of silence on BOTH stdio streams.
+  // Distinct from `timeoutMs` (wall-clock ceiling): this catches a child that is alive but stuck
+  // producing nothing — the "no activity in stderr" hang — without punishing one doing slow work,
+  // since `armIdle()` resets on every line. Armed at spawn so a child that never emits is caught too.
+  let idleTimer = null;
+  let idleKilled = false;
+  const armIdle = () => {
+    if (!idleTimeoutMs || idleTimeoutMs <= 0) return;
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      idleKilled = true;
+      try { child.kill('SIGTERM'); } catch { /* already dead */ }
+      setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* already dead */ } }, 5000).unref();
+    }, idleTimeoutMs);
+    idleTimer.unref();
+  };
+  armIdle();
+
   // stdout — JSONL events from the child loop
   const outRl = readline.createInterface({ input: child.stdout, crlfDelay: Infinity });
   outRl.on('line', (line) => {
     if (!line) return;
+    armIdle();
     let event;
     try { event = JSON.parse(line); }
     catch {
@@ -130,6 +153,7 @@ function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
   const errRl = readline.createInterface({ input: child.stderr, crlfDelay: Infinity });
   errRl.on('line', (line) => {
     if (!line) return;
+    armIdle();
     const event = { type: 'child:stderr', text: line, ts: new Date().toISOString() };
     events.push(event);
     if (stream) {
@@ -157,18 +181,20 @@ function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
   const exitPromise = new Promise((resolve) => {
     child.on('exit', async (code, signal) => {
       if (killTimer) clearTimeout(killTimer);
+      if (idleTimer) clearTimeout(idleTimer);
       // Drain stdio readlines before resolving — last line may still be in buffer.
       await Promise.all([outClosePromise, errClosePromise]);
-      resolve({ code, signal });
+      resolve({ code, signal, idleKilled });
     });
     child.on('error', (err) => {
       if (killTimer) clearTimeout(killTimer);
+      if (idleTimer) clearTimeout(idleTimer);
       resolve({ code: null, signal: null, spawnError: err });
     });
   });
 
   async function wait() {
-    const { code, signal, spawnError } = await exitPromise;
+    const { code, signal, spawnError, idleKilled: idle } = await exitPromise;
     if (spawnError) {
       return {
         text: '',
@@ -178,6 +204,7 @@ function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
         events,
         exitCode: null,
         signal: null,
+        idleKilled: false,
       };
     }
     // Pluck the final loop:done event — that's the canonical child result.
@@ -194,18 +221,21 @@ function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
         events,
         exitCode: code,
         signal,
+        idleKilled: !!idle,
       };
     }
     // No loop:done — child exited abnormally or never reached the LLM.
     const errEvent = events.find(e => e.type === 'loop:error' || e.type === 'error');
+    const idleNote = idle ? `[spawn] child killed after idle timeout (no output; signal=${signal})` : null;
     return {
       text: '',
       usage: { inputTokens: 0, outputTokens: 0 },
       cost: 0,
-      error: errEvent?.data?.error || `[spawn] child exited (code=${code}, signal=${signal}) without loop:done`,
+      error: idleNote || errEvent?.data?.error || `[spawn] child exited (code=${code}, signal=${signal}) without loop:done`,
       events,
       exitCode: code,
       signal,
+      idleKilled: !!idle,
     };
   }
 
@@ -222,7 +252,9 @@ function spawnChild({ config, input, cliPath, timeoutMs, stream } = {}) {
  *
  * @param {object} [options]
  * @param {string} [options.cliPath] - Override the bareagent CLI path (default: ./bin/cli.js relative to this file).
- * @param {number} [options.timeoutMs] - Force-kill child after this many ms (default 10 min).
+ * @param {number} [options.timeoutMs] - Force-kill child after this many ms (default 10 min, wall-clock ceiling).
+ * @param {number} [options.idleTimeoutMs] - Force-kill child after this many ms of no stdout/stderr output
+ *   (heartbeat watchdog; default off). Resets on every line, so slow-but-working children survive.
  * @param {Stream} [options.stream] - bareagent Stream instance — child:stderr events get re-emitted here.
  * @returns {{tool: import('../types').ToolDef, spawnChild: typeof spawnChild}}
  */
@@ -250,6 +282,7 @@ function createSpawnTool(options = {}) {
         input,
         cliPath: options.cliPath,
         timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        idleTimeoutMs: options.idleTimeoutMs,
         stream: options.stream,
       });
       return await handle.wait();

package/types/index.d.ts

@@ -22,6 +22,8 @@ export interface GenerateResult {
   text: string;
   toolCalls: ToolCall[];
   usage: Usage;
+  /** Model id the response was produced by; preferred over Provider.model for cost accounting. */
+  model?: string | null;
 }
 
 /** A conversation message in OpenAI chat format. */