bare-agent 0.47.0 → 0.48.0

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.43.0 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.16.0` optional peer for governance) | Apache 2.0
+> v0.43.0 | Node.js >= 18 | zero required deps (`bareguard >=0.19.0 <1.0.0` optional peer for governance) | Apache 2.0
 >
 > Full human guide with composition examples, design philosophy, and recipes: [Usage Guide](docs/archive/usage-guide.md)
 
@@ -509,7 +509,18 @@ The blocks now ride the transcript on `Message.providerBlocks` (`{provider, mode
 
 Legacy `wrapTool` / `wrapTools` are retained as deprecation shims (one-shot console warning, removal in 1.0). Migration: replace `wrapTools(tools)` at `loop.run()` with `filterTools(tools)` once upfront + `onLlmResult` / `onToolResult` on `new Loop({...})` to pick up LLM-cost recording and `_ctx` threading.
 
-**`actionTranslator` for bash/fs primitive activation (v0.10.1+).** Bareguard's `bashCheck` / `fsCheck` / `netCheck` only fire when `action.type === 'bash'` / `'read'` / `'write'` / `'fetch'`. The default action shape is `{type: toolName, args, _ctx}` which matches `tools.denylist` / `tools.allowlist` but does NOT activate those primitives. Adopters who want both pass `wireGate(gate, { actionTranslator })`. Since bareguard 0.4.1+, the primitives read fields from either flat (`action.cmd`) or nested (`action.args.cmd` / `.command`) shapes, so you can pass args through verbatim:
+**`actionTranslator` for bash/fs primitive activation — DEFAULT since bareguard >=0.19.0 (the "C2" fix).** Bareguard's `bashCheck` / `fsCheck` only fire when `action.type === 'bash'` / `'read'` / `'write'` / `'edit'`. Through 0.15, `wireGate`'s default action shape was `{type: toolName, args, _ctx}` — this matched `tools.denylist` / `tools.allowlist` but never activated `fs`/`bash`, so every adopter had to hand-write the translator below. **As of bareagent's current peerDependency floor (bareguard >=0.19.0), the DEFAULT translator does this mapping for you** — no custom `actionTranslator` needed for the six `createShellTools` primitives:
+
+- `shell_read` / `shell_grep` → `{type:'read', tool, path: resolveToolPath(args.path), args, _ctx}`
+- `shell_write` → `{type:'write', tool, path: resolveToolPath(args.path), args, _ctx}`
+- `shell_edit` → `{type:'edit', tool, path: resolveToolPath(args.path), args, _ctx}`
+- `shell_run` → `{type:'bash', tool, cmd: args.argv.join(' '), args, _ctx}`
+- `shell_exec` → `{type:'bash', tool, cmd: args.command, args, _ctx}`
+- every other tool → `{type: toolName, tool: toolName, args, _ctx}`
+
+`tool` carries the literal bareagent tool name on **every** branch — bareguard 0.19's action identity for `tools.allowlist`/`tools.denylist` is `action.tool ?? action.type`, so a tool-name allowlist (`tools.allowlist: ['shell_read']`) keeps matching even though `type` is now `'read'`/`'write'`/`'bash'`, not the tool name. **`filterTools` deliberately does NOT use this translator** — it probes tool IDENTITY ONLY (`{type: name, tool: name}`). No real `args` exist at discovery time, so probing the translated shape would mean `path: undefined`; measured on a real 0.19 Gate, a path-less `read`/`write`/`edit` action SKIPS the fs scope check entirely (not a deny), which would silently OFFER a shell file tool with NO scope configured at all — and bareguard has flagged that behavior may tighten to a deny in a future release, which would instead silently HIDE a properly-scoped tool. Neither reading is safe to build `filterTools` on, so it only reflects `tools.allowlist`/`tools.denylist`; scope enforcement stays entirely at `policy`, on the real call, where it denies loudly. `onLlmResult` still always uses `{type:'llm'}` regardless of the translator (so budget rules match without translator collusion). `resolveToolPath` canonicalizes `~`/relative paths before the gate sees them, exactly as the manual translator below used to; a malformed or missing path is handled so the translator **never crashes and never silently allows** — see `src/bareguard-adapter.js`'s `safeToolPath` for the exact contract: ANY missing or unresolvable path — absent `path` key, non-string, empty, or an unresolvable `~` — normalizes to `''` (bareguard denies via `fs.invalidPath` regardless of scope config). A real call is never silently allowed.
+
+**Requires bareguard >=0.19.0.** 0.15 and earlier ignore `action.tool` entirely, so this exact shape combined with a tool-name allowlist would deny every shell file action — that's WHY the peerDependency floor moved, not a runtime version check. Override with `wireGate(gate, { actionTranslator })` if you need a different shape or are pinned to an older bareguard:
 
 ```javascript
 const { policy, onToolResult } = wireGate(gate, {
@@ -524,9 +535,9 @@ const { policy, onToolResult } = wireGate(gate, {
 });
 ```
 
-`onLlmResult` always uses `{type:'llm'}` regardless of the translator (so budget rules match without translator collusion). `defaultActionTranslator` is exported for composition. **A tool is NOT auto-gated by the fs/bash primitives without this translator** — e.g. `shell_write` runs the write but `fs.writeScope` only enforces once `shell_write` → `{type:'write', path}`; the default `{type:'shell_write'}` matches `tools.allow/denylist` only. Verified live: with the translator, `gate.check` ALLOWs `shell_run ["ls","/tmp"]` and DENYs `shell_read /etc/passwd` (`[deny: fs.readScope]`), and an out-of-scope `shell_write` is denied **before** `execute` (nothing touches disk).
+Verified live against a real 0.19 Gate: `gate.check` ALLOWs `shell_run ["ls","/tmp"]` and DENYs `shell_read /etc/passwd` (`[deny: fs.readScope]`), and an out-of-scope `shell_write` is denied **before** `execute` (nothing touches disk) — with zero custom translator. `defaultActionTranslator` is exported for composition.
 
-> **Canonicalize the path before the gate sees it.** bareguard's `fs` primitive checks the path you hand it WITHOUT canonicalizing it — a `~`-prefixed or relative `args.path` reads `fs.readScope`/`fs.writeScope` differently than the absolute path the tool actually opens. Call `resolveToolPath` (exported from `bare-agent/tools` alongside `createShellTools`) on `args.path` in the translator — either put the result in an explicit `path` field (as the snippet above's sibling example, `examples/with-bareguard.mjs`, does) or, if relying on bareguard reading `args.path` directly, replace `args.path` with the canonicalized value before returning. Same string in, same string opened.
+> **fs.readScope/writeScope now deny by default when unset (bareguard 0.19).** Before, an unconfigured `fs` primitive that never activated was silently a no-op; now that the default translator activates it, a Gate with NO `fs.readScope` configured denies every `shell_read`/`shell_grep` (`fs.readScope.unset`), and likewise `fs.writeScope.unset` for `shell_write`/`shell_edit`. If you want the shell file tools usable at all, set both scopes explicitly — see `examples/with-bareguard.mjs`. Note this denial is a `policy`-time fact only: `filterTools` (identity-only, see above) still OFFERS the shell file tools to the model even with no scope configured — the deny happens loudly on the real call, not by hiding the tool at discovery time.
 
 **Bounding tool rounds — use `limits.maxToolRounds` (bareguard 0.4.2+), not doubled `maxTurns`.** `limits.maxTurns` ticks on every `gate.record` (LLM + tool), so an "N LLM-tool round" cap is `maxTurns: N*2`. `limits.maxToolRounds: N` ticks only on non-`llm` records and gives the natural semantic — pairs cleanly with our split `onLlmResult` / `onToolResult` (the LLM side writes `{type:'llm'}` records which the counter skips). Halt severity, same shape as `maxTurns`, rebuilt from audit on cold-start.
 

package/examples/with-bareguard.mjs

@@ -18,16 +18,30 @@
 
 import { Gate } from 'bareguard';
 import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 const require = createRequire(import.meta.url);
 const { Loop, wireGate } = require('bare-agent');
 const { OpenAI } = require('bare-agent/providers');
-const { createShellTools, resolveToolPath } = require('bare-agent/tools');
+const { createShellTools } = require('bare-agent/tools');
 
 // 1. Build the gate. Every primitive is optional with sensible defaults.
+//    fs.readScope/fs.writeScope are both set: on bareguard >=0.19 (bareagent's peerDependency
+//    floor), a shell file action denies by default when its scope is unset (fs.readScope.unset /
+//    fs.writeScope.unset) — leaving writeScope out here would silently deny every shell_write /
+//    shell_edit call, not leave the primitive dead like on older bareguard.
+//    readScope is deliberately WIDER than writeScope here — read is fine anywhere under /tmp,
+//    but writes are narrowed to one demo subdir, to show the two scopes are independent (a
+//    folder listed only in readScope is NOT writable, and vice versa). The demo dir is created
+//    below since fs.writeScope doesn't need the path to pre-exist, but the example's own
+//    shell_write call does.
+const writeDir = path.join(os.tmpdir(), 'bare-agent-demo');
+fs.mkdirSync(writeDir, { recursive: true });
 const gate = new Gate({
   budget: { maxCostUsd: 0.10 },           // hard USD cap
   limits: { maxTurns: 20 },                // safety net on think/act cycles
-  fs:     { readScope: ['/tmp', '~/'] },   // shell_read / shell_grep allowed roots
+  fs:     { readScope: ['/tmp'], writeScope: [writeDir] },  // read: anywhere under /tmp; write: one narrower demo dir
   bash:   { allow: ['ls', 'cat', 'echo', 'pwd'] },  // argv[0] allowlist for shell_run
   audit:  { path: './bareagent-audit.jsonl' },
   // Required by bareguard: any ask/halt event flows through here.
@@ -45,36 +59,16 @@ const gate = new Gate({
 });
 await gate.init();
 
-// 2. Wire the gate. The DEFAULT translator emits `{ type: <toolName> }` — which matches bareguard's
-//    `tools.allowlist`/`tools.denylist` (they read `action.type`) but does NOT activate the `bash`/`fs`/`net`
-//    primitives: those fire only on `action.type ∈ {bash, read, write, edit}` and read `action.cmd`/`action.path`.
-//    So to make the `bash.allow` + `fs.readScope` config above actually enforce, we MUST translate the shell
-//    tools into those primitive shapes — otherwise the caps are silently dead (relayfact F7/BA-3).
-//
-//    `path` below is `resolveToolPath(args.path)`, not the raw arg: bareguard's fs primitive checks the
-//    path you hand it WITHOUT canonicalizing it, so a `~`-prefixed or relative path would be judged
-//    against `fs.readScope`/`fs.writeScope` in a different form than the one the tool actually opens —
-//    gate string and opened string must be the SAME string. `resolveToolPath` is the one canonicalizer
-//    (expand `~` via os.homedir(), then path.resolve) every shell file tool already applies internally
-//    before opening; calling it here too means the gate sees exactly what gets opened.
-const actionTranslator = (toolName, args, ctx) => {
-  switch (toolName) {
-    // shell_run is argv (no shell); bareguard's bash.allow matches `cmd.startsWith(prefix)`, so join argv[0..].
-    case 'shell_run':  return { type: 'bash', cmd: (args?.argv || []).join(' '), args, _ctx: ctx ?? null };
-    case 'shell_exec': return { type: 'bash', cmd: args?.command, args, _ctx: ctx ?? null };
-    // shell_read / shell_grep are reads — gate them through fs.readScope, on the canonicalized path.
-    case 'shell_read':
-    case 'shell_grep': return { type: 'read', path: resolveToolPath(args?.path), args, _ctx: ctx ?? null };
-    // shell_write is a write — gate it through fs.writeScope (add writeScope to the Gate config to enforce).
-    case 'shell_write': return { type: 'write', path: resolveToolPath(args?.path), args, _ctx: ctx ?? null };
-    // shell_edit is an anchored edit — bareguard gates {type:'edit'} by the SAME fs.writeScope as write.
-    case 'shell_edit':  return { type: 'edit',  path: resolveToolPath(args?.path), args, _ctx: ctx ?? null };
-    default:           return { type: toolName, args, _ctx: ctx ?? null };
-  }
-};
+// 2. Wire the gate. As of bareguard >=0.19 (bareagent's peerDependency floor), the DEFAULT
+//    actionTranslator already maps the six `createShellTools` primitives into bareguard's `fs`/`bash`
+//    shapes (shell_read/shell_grep → {type:'read',...}, shell_write → {type:'write',...}, shell_edit →
+//    {type:'edit',...}, shell_run/shell_exec → {type:'bash',...}), canonicalizing the path with
+//    `resolveToolPath` itself — so the `bash.allow` + `fs.readScope`/`fs.writeScope` config above just
+//    works with no custom actionTranslator (this used to be a required hand-written override — the "C2"
+//    gap, relayfact F7/BA-3 — see src/bareguard-adapter.js for the exact shape and bareguard-version note).
 // onToolResult + onLlmResult are the current wiring (wrapTools is deprecated — it loses _ctx and never sees
 // LLM cost, so the budget cap can't cover token-only rounds). policy gates pre-call; the result hooks record.
-const { policy, onToolResult, onLlmResult } = wireGate(gate, { actionTranslator });
+const { policy, onToolResult, onLlmResult } = wireGate(gate);
 
 // 3. Standard bareagent setup.
 const provider = new OpenAI({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "files": [
     "index.js",
     "index.d.ts",
@@ -83,7 +83,7 @@
     "cron-parser": "^4.9.0"
   },
   "peerDependencies": {
-    "bareguard": ">=0.9.0 <1.0.0",
+    "bareguard": ">=0.19.0 <1.0.0",
     "better-sqlite3": ">=9.0.0"
   },
   "peerDependenciesMeta": {
@@ -107,7 +107,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.19.19",
-    "bareguard": ">=0.9.0 <1.0.0",
+    "bareguard": ">=0.19.0 <1.0.0",
     "litectx": "^0.26.0",
     "typescript": "^5.7.0"
   }

package/src/bareguard-adapter.d.ts

@@ -89,7 +89,15 @@ export type Annotation = {
  *   - `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. Bulk-only:
+ *                       so the LLM never sees them. No audit, no record. Judges tool
+ *                       IDENTITY ONLY (`{type: name, tool: name}`) — never the
+ *                       `actionTranslator`'s real per-type shape (an `fs`/`bash` primitive
+ *                       needs a real path/cmd that doesn't exist yet at discovery time; a
+ *                       path-less probe's meaning is version-fragile — see the function doc
+ *                       below). So filterTools reflects ONLY `tools.allowlist`/`tools.denylist`;
+ *                       per-call scope (`fs.readScope`/`writeScope`, `bash.allow`) is enforced
+ *                       by `policy` on every real call — an unset scope denies loudly there,
+ *                       never silently hidden or silently offered at filter time. Bulk-only:
  *                       when MCP tools are exposed via `mcp_discover`+`mcp_invoke`
  *                       meta-tools, filterTools cannot drop the inner names (they
  *                       are not in the tool list). Gate those via bareguard's
@@ -111,13 +119,17 @@ export type Annotation = {
  *   "[deny: <rule>] <toolName> denied" when bareguard omits a 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.
+ *   Builds the action object passed to `gate.check` and `gate.record`. Default (requires
+ *   bareguard >=0.19.0): the six `createShellTools` primitives map to bareguard's `fs`/`bash`
+ *   shapes — `shell_read`/`shell_grep` → `{type:'read', tool, path: resolveToolPath(args.path), args, _ctx}`,
+ *   `shell_write` → `{type:'write', ...}`, `shell_edit` → `{type:'edit', ...}`, `shell_run` →
+ *   `{type:'bash', tool, cmd: args.argv.join(' '), args, _ctx}`, `shell_exec` → `{type:'bash', tool,
+ *   cmd: args.command, args, _ctx}`; every other tool → `{type: toolName, tool: toolName, args, _ctx}`.
+ *   `tool` always carries the literal bareagent tool name — bareguard's action identity for
+ *   `tools.allowlist`/`tools.denylist` is `action.tool ?? action.type`, so a tool-name allowlist
+ *   (`tools.allowlist:['shell_read']`) keeps matching even though `type` is now `'read'`. This
+ *   activates `fs`/`bash` scoping automatically (`fs.readScope`/`fs.writeScope` deny by default
+ *   when unset — see CHANGELOG) — override when a different shape is needed.
  * @returns {{policy: Function, onLlmResult: Function, onToolResult: Function, filterTools: Function, wrapTool: Function, wrapTools: Function}}
  * @when you have a bareguard Gate and want to wire it into a Loop as the policy + metering chokepoint in one line
  * @fails never throws; a gate halt surfaces as a HaltError the Loop catches and exits cleanly, and a deny is an advisory string fed back to the model.
@@ -156,9 +168,22 @@ export function wireGate(gate: Gate, options?: {
  * @param {Ctx} ctx
  */
 export function defaultActionTranslator(toolName: string, args: any, ctx: Ctx): {
+    tool: string;
+    args: any;
+    _ctx: any;
+    type: string;
+    path: string;
+} | {
+    tool: string;
+    args: any;
+    _ctx: any;
     type: string;
+    cmd: any;
+} | {
+    tool: string;
     args: any;
     _ctx: any;
+    type: string;
 };
 /**
  * @typedef {object} AnnotationLimits

package/src/bareguard-adapter.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { HaltError } = require('./errors');
+const { resolveToolPath } = require('../tools/shell');
 
 /** @typedef {import('../types').Ctx} Ctx */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -56,7 +57,15 @@ let warnedWrap = false;
  *   - `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. Bulk-only:
+ *                       so the LLM never sees them. No audit, no record. Judges tool
+ *                       IDENTITY ONLY (`{type: name, tool: name}`) — never the
+ *                       `actionTranslator`'s real per-type shape (an `fs`/`bash` primitive
+ *                       needs a real path/cmd that doesn't exist yet at discovery time; a
+ *                       path-less probe's meaning is version-fragile — see the function doc
+ *                       below). So filterTools reflects ONLY `tools.allowlist`/`tools.denylist`;
+ *                       per-call scope (`fs.readScope`/`writeScope`, `bash.allow`) is enforced
+ *                       by `policy` on every real call — an unset scope denies loudly there,
+ *                       never silently hidden or silently offered at filter time. Bulk-only:
  *                       when MCP tools are exposed via `mcp_discover`+`mcp_invoke`
  *                       meta-tools, filterTools cannot drop the inner names (they
  *                       are not in the tool list). Gate those via bareguard's
@@ -78,13 +87,17 @@ let warnedWrap = false;
  *   "[deny: <rule>] <toolName> denied" when bareguard omits a 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.
+ *   Builds the action object passed to `gate.check` and `gate.record`. Default (requires
+ *   bareguard >=0.19.0): the six `createShellTools` primitives map to bareguard's `fs`/`bash`
+ *   shapes — `shell_read`/`shell_grep` → `{type:'read', tool, path: resolveToolPath(args.path), args, _ctx}`,
+ *   `shell_write` → `{type:'write', ...}`, `shell_edit` → `{type:'edit', ...}`, `shell_run` →
+ *   `{type:'bash', tool, cmd: args.argv.join(' '), args, _ctx}`, `shell_exec` → `{type:'bash', tool,
+ *   cmd: args.command, args, _ctx}`; every other tool → `{type: toolName, tool: toolName, args, _ctx}`.
+ *   `tool` always carries the literal bareagent tool name — bareguard's action identity for
+ *   `tools.allowlist`/`tools.denylist` is `action.tool ?? action.type`, so a tool-name allowlist
+ *   (`tools.allowlist:['shell_read']`) keeps matching even though `type` is now `'read'`. This
+ *   activates `fs`/`bash` scoping automatically (`fs.readScope`/`fs.writeScope` deny by default
+ *   when unset — see CHANGELOG) — override when a different shape is needed.
  * @returns {{policy: Function, onLlmResult: Function, onToolResult: Function, filterTools: Function, wrapTool: Function, wrapTools: Function}}
  * @when you have a bareguard Gate and want to wire it into a Loop as the policy + metering chokepoint in one line
  * @fails never throws; a gate halt surfaces as a HaltError the Loop catches and exits cleanly, and a deny is an advisory string fed back to the model.
@@ -214,10 +227,33 @@ function wireGate(gate, options = {}) {
     // Bind to the Gate so `this` stays correct (bareguard's allows reads
     // this._initialized) — extracting the method unbound would crash.
     const allows = gate.allows.bind(gate);
+    // DELIBERATELY NOT `translate(t.name, undefined, undefined)`. No real `args` exist
+    // yet at discovery time, so a path/cmd-bearing actionTranslator (e.g. the default,
+    // which maps shell_read/write/edit to `fs` primitive shapes) would probe with
+    // `path:undefined` — and what that means is a bareguard-VERSION-DEPENDENT fact, not
+    // a stable contract: measured on bareguard 0.19.0, a path-less `read`/`write`/`edit`
+    // action SKIPS the fs scope check entirely ("not a file action", not "scope unset"),
+    // so `allows()` returns true even with NO fs.readScope/writeScope configured at all —
+    // silently OFFERING a tool that every real call to it would then be denied by `policy`
+    // (fs.readScope.unset/fs.writeScope.unset). bareguard has flagged this as likely to
+    // tighten in a future release (a path-less file action denying instead of skipping),
+    // which would flip the failure mode to silently HIDING the tool even when scope IS
+    // configured. Neither reading is something this adapter should guess at, and there is
+    // no bareguard API to ask "is fs.readScope configured" directly — so filterTools probes
+    // IDENTITY ONLY (`{type: name, tool: name}`, never the translated per-type shape). That
+    // only reflects `tools.allowlist`/`tools.denylist` (bareguard's identity for both is
+    // `action.tool ?? action.type` — see `defaultActionTranslator`'s header comment), which
+    // is exactly the class of rule filterTools can safely pre-evaluate with no real args.
+    // Scope enforcement (`fs.readScope`/`writeScope`, `bash.allow`) stays where it has real
+    // data to judge: `policy`, on every actual call, denying loudly when scope is unset —
+    // never silently hidden at discovery time. See test/integration-bareguard-real.test.js
+    // for the live-0.19 verification of both allowlist/denylist filtering and the
+    // no-fs-config "still offered, denied on the real call" behavior.
+    //
     // Parallel: gate.allows is config-driven and pure, so concurrent calls are
     // safe. Matters for large MCP catalogs (50+ tools) where sequential awaits
     // were noticeable overhead on every startup.
-    const verdicts = await Promise.all(tools.map(t => allows(t.name)));
+    const verdicts = await Promise.all(tools.map(t => allows({ type: t.name, tool: t.name })));
     return tools.filter((_, i) => verdicts[i]);
   };
 
@@ -284,18 +320,65 @@ function defaultFormatDeny(decision, toolName) {
   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 })`.
+// Requires bareguard >=0.19.0 (bareagent's own peerDependency floor). Maps the six
+// `createShellTools` primitives (tools/shell.js) to bareguard's `fs`/`bash` action
+// shapes, so `fs.readScope`/`fs.writeScope`/`bash.allow` activate WITHOUT a caller
+// writing their own translator (the "C2" fix — this used to be a documented gap
+// every adopter had to close by hand, see examples/with-bareguard.mjs). Every other
+// tool still gets the pre-0.19 tool-named shape. `tool` is set on every branch —
+// bareguard 0.19's action identity for `tools.allowlist`/`tools.denylist` is
+// `action.tool ?? action.type` (tool exclusive when present), so a tool-name
+// allowlist keeps matching even though `type` is now `'read'`/`'write'`/`'bash'`.
+// Override via `wireGate(gate, { actionTranslator })` when a different shape is needed
+// (e.g. pre-0.19 bareguard, which ignores `action.tool` entirely and would deny every
+// shell file action under this shape — hence the peerDependency floor, not a runtime check).
 /**
  * @param {string} toolName
  * @param {any} args
  * @param {Ctx} ctx
  */
 function defaultActionTranslator(toolName, args, ctx) {
-  return { type: toolName, args, _ctx: ctx ?? null };
+  const tagged = { tool: toolName, args, _ctx: ctx ?? null };
+  if (toolName === 'shell_read' || toolName === 'shell_grep') {
+    return { type: 'read', path: safeToolPath(args), ...tagged };
+  }
+  if (toolName === 'shell_write') {
+    return { type: 'write', path: safeToolPath(args), ...tagged };
+  }
+  if (toolName === 'shell_edit') {
+    return { type: 'edit', path: safeToolPath(args), ...tagged };
+  }
+  if (toolName === 'shell_run') {
+    return { type: 'bash', cmd: Array.isArray(args?.argv) ? args.argv.join(' ') : undefined, ...tagged };
+  }
+  if (toolName === 'shell_exec') {
+    return { type: 'bash', cmd: args?.command, ...tagged };
+  }
+  return { type: toolName, ...tagged };
+}
+
+// Canonicalize a shell file tool's `path` arg for bareguard's fs primitive, without
+// ever letting a bad or missing path crash the translator or launder into a silent
+// allow. `filterTools` no longer probes this translator at all (it judges tool
+// IDENTITY ONLY — see filterTools above), so there is no remaining "discovery-time,
+// no real args yet" case to special-case here: every call into this function is a
+// REAL per-call translation, and `args` missing entirely, missing the `path` key,
+// or carrying a non-string/empty/unresolvable-`~` path are ALL malformed-or-absent
+// paths that must deny, never skip-then-allow. `resolveToolPath` itself throws on
+// anything that isn't a non-empty string (missing `args`/`args.path` reads as
+// `undefined`, which fails that same check) — so a single try/catch covers every
+// case uniformly, always normalizing to `''`, which `fs.invalidPath` reliably denies
+// on a real bareguard 0.19 Gate whether or not `fs.*Scope` is configured. (Previously
+// this returned `undefined` — not `''` — for a missing `path` key, which hit
+// bareguard's fs primitive's "not a file action, skip scope entirely" branch and
+// silently ALLOWED a real call with no path at all; closed here.)
+/** @param {any} args */
+function safeToolPath(args) {
+  try {
+    return resolveToolPath(args?.path);
+  } catch {
+    return '';
+  }
 }
 
 // ── judge → gate.annotate mapping (BA-20) ─────────────────────────────────────

package/src/loop.d.ts

@@ -167,7 +167,7 @@ export class Loop {
      *   thunk is re-evaluated each round (D4/eval-assist F2) so a tool set that grows mid-run — e.g. a skill
      *   unlocking its tools — is offered on the next round; a static array is resolved once at wire time.
      * @param {Record<string, any>} [options={}] - Per-run overrides (system, temperature, ctx, etc.).
-     * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: {name: string|undefined, error: string}, temperatureDropped?: boolean}>}
+     * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: {name: string|undefined, error: string, rawArguments?: string, rawTruncated?: true}, temperatureDropped?: boolean}>}
      *   On halt the returned `error` is `halt:<rule>` (or `halt:unknown` if the
      *   thrown HaltError carried no `rule`), and `msgs` is sanitized so any
      *   dangling assistant `tool_calls` from the halted round are paired with
@@ -208,6 +208,8 @@ export class Loop {
         malformedToolCall?: {
             name: string | undefined;
             error: string;
+            rawArguments?: string;
+            rawTruncated?: true;
         };
         temperatureDropped?: boolean;
     }>;
@@ -238,7 +240,7 @@ export class Loop {
      * @param {string} text - User message.
      * @param {ToolDef[]} [tools=[]] - Tool definitions.
      * @param {Record<string, any>} [options={}] - Per-run overrides.
-     * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: {name: string|undefined, error: string}, temperatureDropped?: boolean}>}
+     * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: {name: string|undefined, error: string, rawArguments?: string, rawTruncated?: true}, temperatureDropped?: boolean}>}
      */
     chat(text: string, tools?: ToolDef[], options?: Record<string, any>): Promise<{
         text: string;
@@ -253,6 +255,8 @@ export class Loop {
         malformedToolCall?: {
             name: string | undefined;
             error: string;
+            rawArguments?: string;
+            rawTruncated?: true;
         };
         temperatureDropped?: boolean;
     }>;

package/src/loop.js

@@ -455,7 +455,7 @@ class Loop {
    *   thunk is re-evaluated each round (D4/eval-assist F2) so a tool set that grows mid-run — e.g. a skill
    *   unlocking its tools — is offered on the next round; a static array is resolved once at wire time.
    * @param {Record<string, any>} [options={}] - Per-run overrides (system, temperature, ctx, etc.).
-   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: {name: string|undefined, error: string}, temperatureDropped?: boolean}>}
+   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: {name: string|undefined, error: string, rawArguments?: string, rawTruncated?: true}, temperatureDropped?: boolean}>}
    *   On halt the returned `error` is `halt:<rule>` (or `halt:unknown` if the
    *   thrown HaltError carried no `rule`), and `msgs` is sanitized so any
    *   dangling assistant `tool_calls` from the halted round are paired with
@@ -1328,7 +1328,7 @@ class Loop {
    * @param {string} text - User message.
    * @param {ToolDef[]} [tools=[]] - Tool definitions.
    * @param {Record<string, any>} [options={}] - Per-run overrides.
-   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: {name: string|undefined, error: string}, temperatureDropped?: boolean}>}
+   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, model: string|null, msgs: Message[], metrics: RunMetrics, malformedToolCall?: {name: string|undefined, error: string, rawArguments?: string, rawTruncated?: true}, temperatureDropped?: boolean}>}
    */
   async chat(text, tools = [], options = {}) {
     this._history.push({ role: 'user', content: text });

package/src/provider-ollama.d.ts

@@ -13,6 +13,13 @@ export type OllamaOptions = {
      * - BA-19: TOTAL call-duration deadline in ms, beside `timeoutMs`. The idle bound resets on any socket activity, so a response that trickles a byte forever never trips it and hangs for hours. This is an absolute, non-resetting ceiling; on trip, `generate()` rejects with a TERMINAL `TimeoutError` (`code: 'EDEADLINE'`, `context.bound: 'deadline'`, `retryable: false`). DISABLED by default; `0`/`Infinity` disable. Overridable per call via `generate(..., { deadlineMs })`. (A cold large-model load is a legitimate long single call — leave this disabled or set it generously for such models.)
      */
     deadlineMs?: number | undefined;
+    /**
+     * - BA-27 follow-up: when a tool call's string-shaped
+     * `function.arguments` JSON fails to parse, also attach the raw string (verbatim, capped at 500
+     * chars, `rawTruncated:true` when longer) to `malformedToolCall.rawArguments`. Off by default,
+     * independent of `exposeErrorBody`. See `src/provider-toolcalls.js`.
+     */
+    exposeMalformedArgs?: boolean | undefined;
 };
 /** @typedef {import('../types').Message} Message */
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -24,6 +31,10 @@ export type OllamaOptions = {
  * @property {boolean} [exposeErrorBody=false]
  * @property {number} [timeoutMs=600000] - BA-18: request/idle timeout in ms. Bounds a silent or never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`, `context.bound: 'idle'`) instead of hanging until the OS TCP timeout. `0`/`Infinity` disables it. Overridable per call via `generate(..., { timeoutMs })`. (A local Ollama that is loading a large model cold can be slow to first byte — raise this or disable it for very large local models.)
  * @property {number} [deadlineMs=0] - BA-19: TOTAL call-duration deadline in ms, beside `timeoutMs`. The idle bound resets on any socket activity, so a response that trickles a byte forever never trips it and hangs for hours. This is an absolute, non-resetting ceiling; on trip, `generate()` rejects with a TERMINAL `TimeoutError` (`code: 'EDEADLINE'`, `context.bound: 'deadline'`, `retryable: false`). DISABLED by default; `0`/`Infinity` disable. Overridable per call via `generate(..., { deadlineMs })`. (A cold large-model load is a legitimate long single call — leave this disabled or set it generously for such models.)
+ * @property {boolean} [exposeMalformedArgs=false] - BA-27 follow-up: when a tool call's string-shaped
+ *   `function.arguments` JSON fails to parse, also attach the raw string (verbatim, capped at 500
+ *   chars, `rawTruncated:true` when longer) to `malformedToolCall.rawArguments`. Off by default,
+ *   independent of `exposeErrorBody`. See `src/provider-toolcalls.js`.
  */
 export class OllamaProvider {
     /**
@@ -39,6 +50,7 @@ export class OllamaProvider {
     exposeErrorBody: boolean;
     timeoutMs: number | undefined;
     deadlineMs: number | undefined;
+    exposeMalformedArgs: boolean;
     /**
      * Generate a response from a local Ollama instance.
      * @param {Message[]} messages - Conversation messages.

package/src/provider-ollama.js

@@ -22,6 +22,10 @@ const OLLAMA_USAGE_KEYS = ['prompt_eval_count', 'eval_count'];
  * @property {boolean} [exposeErrorBody=false]
  * @property {number} [timeoutMs=600000] - BA-18: request/idle timeout in ms. Bounds a silent or never-answering socket on inactivity so `generate()` rejects with a retryable `TimeoutError` (`code: 'ETIMEDOUT'`, `context.bound: 'idle'`) instead of hanging until the OS TCP timeout. `0`/`Infinity` disables it. Overridable per call via `generate(..., { timeoutMs })`. (A local Ollama that is loading a large model cold can be slow to first byte — raise this or disable it for very large local models.)
  * @property {number} [deadlineMs=0] - BA-19: TOTAL call-duration deadline in ms, beside `timeoutMs`. The idle bound resets on any socket activity, so a response that trickles a byte forever never trips it and hangs for hours. This is an absolute, non-resetting ceiling; on trip, `generate()` rejects with a TERMINAL `TimeoutError` (`code: 'EDEADLINE'`, `context.bound: 'deadline'`, `retryable: false`). DISABLED by default; `0`/`Infinity` disable. Overridable per call via `generate(..., { deadlineMs })`. (A cold large-model load is a legitimate long single call — leave this disabled or set it generously for such models.)
+ * @property {boolean} [exposeMalformedArgs=false] - BA-27 follow-up: when a tool call's string-shaped
+ *   `function.arguments` JSON fails to parse, also attach the raw string (verbatim, capped at 500
+ *   chars, `rawTruncated:true` when longer) to `malformedToolCall.rawArguments`. Off by default,
+ *   independent of `exposeErrorBody`. See `src/provider-toolcalls.js`.
  */
 
 class OllamaProvider {
@@ -41,6 +45,8 @@ class OllamaProvider {
     this.timeoutMs = options.timeoutMs;
     // BA-19: total call-duration deadline (ms). Resolved at call time (default 0 = disabled).
     this.deadlineMs = options.deadlineMs;
+    // BA-27 follow-up: expose the raw malformed tool-call arguments string. Off by default.
+    this.exposeMalformedArgs = options.exposeMalformedArgs === true;
   }
 
   /**
@@ -100,7 +106,7 @@ class OllamaProvider {
       arguments: typeof tc.function.arguments === 'string'
         ? JSON.parse(tc.function.arguments)
         : tc.function.arguments,
-    }));
+    }), { exposeMalformedArgs: this.exposeMalformedArgs });
 
     return {
       text: msg.content || '',

package/src/provider-openai.d.ts

@@ -38,6 +38,14 @@ export type OpenAIOptions = {
      * self-hosted / proxy endpoints). No model-name sniffing — the caller declares the dialect.
      */
     legacyMaxTokens?: boolean | undefined;
+    /**
+     * - BA-27 follow-up: when a tool call's `function.arguments`
+     * JSON fails to parse, also attach the raw string (verbatim, capped at 500 chars, `rawTruncated:true`
+     * when longer) to `malformedToolCall.rawArguments`. Off by default, independent of `exposeErrorBody` —
+     * the raw blob is model-generated, not an upstream error body, but the same "don't leak an unbounded
+     * unexpected string into logs by default" reasoning applies. See `src/provider-toolcalls.js`.
+     */
+    exposeMalformedArgs?: boolean | undefined;
 };
 /**
  * @typedef {object} OpenAIOptions
@@ -64,6 +72,11 @@ export type OpenAIOptions = {
  *   OpenAI GPT-5 models 400 on `max_tokens` ("Unsupported parameter … Use 'max_completion_tokens'").
  *   Set `true` for an OpenAI-compatible server that only understands the legacy key (e.g. some
  *   self-hosted / proxy endpoints). No model-name sniffing — the caller declares the dialect.
+ * @property {boolean} [exposeMalformedArgs=false] - BA-27 follow-up: when a tool call's `function.arguments`
+ *   JSON fails to parse, also attach the raw string (verbatim, capped at 500 chars, `rawTruncated:true`
+ *   when longer) to `malformedToolCall.rawArguments`. Off by default, independent of `exposeErrorBody` —
+ *   the raw blob is model-generated, not an upstream error body, but the same "don't leak an unbounded
+ *   unexpected string into logs by default" reasoning applies. See `src/provider-toolcalls.js`.
  */
 export class OpenAIProvider {
     /**
@@ -81,6 +94,7 @@ export class OpenAIProvider {
     timeoutMs: number | undefined;
     deadlineMs: number | undefined;
     legacyMaxTokens: boolean;
+    exposeMalformedArgs: boolean;
     /**
      * Generate a response from the OpenAI API.
      * @param {Message[]} messages - Conversation messages.

package/src/provider-openai.js

@@ -72,6 +72,11 @@ function isLoopbackHost(hostname) {
  *   OpenAI GPT-5 models 400 on `max_tokens` ("Unsupported parameter … Use 'max_completion_tokens'").
  *   Set `true` for an OpenAI-compatible server that only understands the legacy key (e.g. some
  *   self-hosted / proxy endpoints). No model-name sniffing — the caller declares the dialect.
+ * @property {boolean} [exposeMalformedArgs=false] - BA-27 follow-up: when a tool call's `function.arguments`
+ *   JSON fails to parse, also attach the raw string (verbatim, capped at 500 chars, `rawTruncated:true`
+ *   when longer) to `malformedToolCall.rawArguments`. Off by default, independent of `exposeErrorBody` —
+ *   the raw blob is model-generated, not an upstream error body, but the same "don't leak an unbounded
+ *   unexpected string into logs by default" reasoning applies. See `src/provider-toolcalls.js`.
  */
 
 class OpenAIProvider {
@@ -93,6 +98,8 @@ class OpenAIProvider {
     this.deadlineMs = options.deadlineMs;
     // BA-24 (fwdloop): use the legacy `max_tokens` key. Default false ⇒ `max_completion_tokens` (GPT-5-safe).
     this.legacyMaxTokens = options.legacyMaxTokens === true;
+    // BA-27 follow-up: expose the raw malformed tool-call arguments string. Off by default.
+    this.exposeMalformedArgs = options.exposeMalformedArgs === true;
   }
 
   /**
@@ -161,7 +168,7 @@ class OpenAIProvider {
       id: tc.id,
       name: tc.function.name,
       arguments: JSON.parse(tc.function.arguments),
-    }));
+    }), { exposeMalformedArgs: this.exposeMalformedArgs });
 
     return {
       text: msg.content || '',

package/src/provider-toolcalls.d.ts

@@ -1,5 +1,4 @@
 export type ToolCall = import("../types").ToolCall;
-/** @typedef {import('../types').ToolCall} ToolCall */
 /**
  * BA-27 — parse a round's raw tool calls into the neutral {@link ToolCall} shape WITHOUT throwing on
  * malformed arguments.
@@ -16,14 +15,27 @@ export type ToolCall = import("../types").ToolCall;
  * All-or-nothing (mirrors BA-4's refusal to execute a truncated round's calls): a partial set risks
  * running half a decomposed intent, so one bad call voids the whole round's calls.
  *
+ * `opts.exposeMalformedArgs` (default off, mirrors `exposeErrorBody`): when on, the marker also
+ * carries `rawArguments` — the raw `function.arguments` VERBATIM, capped at 500 chars (`rawTruncated:
+ * true` added only when it was longer). Non-string raw arguments (e.g. Ollama's well-formed object
+ * case reaching this catch some other way) are never exposed — only a string is a model-generated
+ * blob worth surfacing for debugging; an object was already structurally valid before whatever else
+ * threw. Off by default for the same reason as `exposeErrorBody`: an arbitrary model-generated string
+ * landing in a log/audit row unbounded is its own leak surface.
+ *
  * @param {any[]} rawToolCalls - provider-native tool-call entries (may be undefined/empty)
  * @param {(tc: any) => ToolCall} mapOne - maps one raw entry to a ToolCall; MAY throw on bad arguments
- * @returns {{ toolCalls: ToolCall[], malformedToolCall?: { name: string|undefined, error: string } }}
+ * @param {{ exposeMalformedArgs?: boolean }} [opts]
+ * @returns {{ toolCalls: ToolCall[], malformedToolCall?: { name: string|undefined, error: string, rawArguments?: string, rawTruncated?: true } }}
  */
-export function parseToolCalls(rawToolCalls: any[], mapOne: (tc: any) => ToolCall): {
+export function parseToolCalls(rawToolCalls: any[], mapOne: (tc: any) => ToolCall, opts?: {
+    exposeMalformedArgs?: boolean;
+}): {
     toolCalls: ToolCall[];
     malformedToolCall?: {
         name: string | undefined;
         error: string;
+        rawArguments?: string;
+        rawTruncated?: true;
     };
 };

package/src/provider-toolcalls.js

@@ -2,6 +2,11 @@
 
 /** @typedef {import('../types').ToolCall} ToolCall */
 
+// Raw-arguments exposure cap. Matches the sibling opt-in error-body exposure pattern
+// (`exposeErrorBody`) elsewhere in the providers: off by default, and even when on, bounded —
+// an arbitrarily long model-generated string reaching a log/receipt unbounded is its own risk.
+const RAW_ARGUMENTS_MAX_CHARS = 500;
+
 /**
  * BA-27 — parse a round's raw tool calls into the neutral {@link ToolCall} shape WITHOUT throwing on
  * malformed arguments.
@@ -18,11 +23,20 @@
  * All-or-nothing (mirrors BA-4's refusal to execute a truncated round's calls): a partial set risks
  * running half a decomposed intent, so one bad call voids the whole round's calls.
  *
+ * `opts.exposeMalformedArgs` (default off, mirrors `exposeErrorBody`): when on, the marker also
+ * carries `rawArguments` — the raw `function.arguments` VERBATIM, capped at 500 chars (`rawTruncated:
+ * true` added only when it was longer). Non-string raw arguments (e.g. Ollama's well-formed object
+ * case reaching this catch some other way) are never exposed — only a string is a model-generated
+ * blob worth surfacing for debugging; an object was already structurally valid before whatever else
+ * threw. Off by default for the same reason as `exposeErrorBody`: an arbitrary model-generated string
+ * landing in a log/audit row unbounded is its own leak surface.
+ *
  * @param {any[]} rawToolCalls - provider-native tool-call entries (may be undefined/empty)
  * @param {(tc: any) => ToolCall} mapOne - maps one raw entry to a ToolCall; MAY throw on bad arguments
- * @returns {{ toolCalls: ToolCall[], malformedToolCall?: { name: string|undefined, error: string } }}
+ * @param {{ exposeMalformedArgs?: boolean }} [opts]
+ * @returns {{ toolCalls: ToolCall[], malformedToolCall?: { name: string|undefined, error: string, rawArguments?: string, rawTruncated?: true } }}
  */
-function parseToolCalls(rawToolCalls, mapOne) {
+function parseToolCalls(rawToolCalls, mapOne, opts = {}) {
   const raw = rawToolCalls || [];
   /** @type {ToolCall[]} */
   const toolCalls = [];
@@ -30,13 +44,19 @@ function parseToolCalls(rawToolCalls, mapOne) {
     try {
       toolCalls.push(mapOne(tc));
     } catch (e) {
-      return {
-        toolCalls: [],
-        malformedToolCall: {
-          name: tc && tc.function ? tc.function.name : undefined,
-          error: e instanceof Error ? e.message : String(e),
-        },
+      /** @type {{ name: string|undefined, error: string, rawArguments?: string, rawTruncated?: true }} */
+      const malformedToolCall = {
+        name: tc && tc.function ? tc.function.name : undefined,
+        error: e instanceof Error ? e.message : String(e),
       };
+      if (opts.exposeMalformedArgs) {
+        const rawArgs = tc && tc.function ? tc.function.arguments : undefined;
+        if (typeof rawArgs === 'string') {
+          malformedToolCall.rawArguments = rawArgs.slice(0, RAW_ARGUMENTS_MAX_CHARS);
+          if (rawArgs.length > RAW_ARGUMENTS_MAX_CHARS) malformedToolCall.rawTruncated = true;
+        }
+      }
+      return { toolCalls: [], malformedToolCall };
     }
   }
   return { toolCalls };

package/types/index.d.ts

@@ -142,8 +142,13 @@ export interface GenerateResult {
    * tool call" and retries; `usage`/`model` still flow so the round is metered. The JSON is NEVER
    * repaired. Absent on a clean round. OpenAI-compatible + Ollama string-arguments only; Anthropic
    * arrives pre-parsed and cannot hit this.
+   *
+   * `rawArguments`/`rawTruncated` (BA-27 follow-up) are present only when the provider was
+   * constructed with `exposeMalformedArgs: true` (default off, mirrors `exposeErrorBody`) AND the
+   * raw `function.arguments` was a string: the raw value verbatim, capped at 500 chars, with
+   * `rawTruncated: true` added only when it was longer.
    */
-  malformedToolCall?: { name: string | undefined; error: string };
+  malformedToolCall?: { name: string | undefined; error: string; rawArguments?: string; rawTruncated?: true };
   /**
    * BA-7 — provider-native content blocks the normalized `{text, toolCalls}` shape cannot express
    * (Anthropic `thinking` / `redacted_thinking`), captured opaquely so the Loop can put them on the