bare-agent 0.21.1 → 0.22.0

package/README.md

@@ -154,6 +154,7 @@ const { policy, onLlmResult, onToolResult, filterTools } = wireGate(gate, {
   actionTranslator: (toolName, args, ctx) => {
     if (toolName === 'shell_exec') return { type: 'bash', args, _ctx: ctx };
     if (toolName === 'shell_read') return { type: 'read', args, _ctx: ctx };
+    if (toolName === 'shell_write') return { type: 'write', args, _ctx: ctx }; // gate by fs.writeScope
     return defaultActionTranslator(toolName, args, ctx);
   },
 });

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.21.1 | Node.js >= 18 | zero required deps (`bareguard ^0.9.0` optional peer for governance) | Apache 2.0
+> v0.22.0 | Node.js >= 18 | zero required deps (`bareguard ^0.9.0` optional peer for governance) | Apache 2.0
 >
 > Full human guide with composition examples, design philosophy, and recipes: [Usage Guide](docs/02-features/usage-guide.md)
 
@@ -62,7 +62,7 @@ Eight entry points:
 | Assess website privacy risk | createBrowsingTools + Loop (requires `npm install wearehere`) |
 | Control Android/iOS devices | createMobileTools + Loop |
 | Control mobile (token-efficient, disk-based) | `baremobile` CLI session — snapshots to `.baremobile/*.yml` |
-| Read files, list directories, run shell commands, grep | createShellTools + Loop({ policy }) |
+| Read/write files, list directories, run shell commands, grep | createShellTools (shell_read/grep/**write**/run/exec) + Loop({ policy }) — gate `shell_write` via `fs.writeScope` with an actionTranslator |
 | Auto-discover MCP servers from IDE configs | createMCPBridge |
 | Gate MCP tools with allow/deny lists | createMCPBridge + `.mcp-bridge.json` |
 | Gate every tool call with one policy hook | `wireGate(gate).policy` → `Loop({ policy })` |
@@ -384,15 +384,16 @@ Legacy `wrapTool` / `wrapTools` are retained as deprecation shims (one-shot cons
 ```javascript
 const { policy, onToolResult } = wireGate(gate, {
   actionTranslator: (toolName, args, ctx) => {
-    if (toolName === 'shell_exec') return { type: 'bash', args, _ctx: ctx };   // bareguard 0.4.1+ reads args.command
-    if (toolName === 'shell_run')  return { type: 'bash', args, _ctx: ctx };   // reads args.argv → joins to cmd
-    if (toolName === 'shell_read') return { type: 'read', args, _ctx: ctx };   // reads args.path
+    if (toolName === 'shell_exec')  return { type: 'bash', args, _ctx: ctx };   // bareguard 0.4.1+ reads args.command
+    if (toolName === 'shell_run')   return { type: 'bash', args, _ctx: ctx };   // reads args.argv → joins to cmd
+    if (toolName === 'shell_read')  return { type: 'read',  args, _ctx: ctx };  // reads args.path
+    if (toolName === 'shell_write') return { type: 'write', args, _ctx: ctx };  // gate by fs.writeScope (reads args.path)
     return { type: toolName, args, _ctx: ctx };          // fall through to defaultActionTranslator
   },
 });
 ```
 
-`onLlmResult` always uses `{type:'llm'}` regardless of the translator (so budget rules match without translator collusion). `defaultActionTranslator` is exported for composition.
+`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).
 
 **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.
 
@@ -629,6 +630,8 @@ if (out.incomplete) {
 console.log(out.receipts.spawned.length);          // RC-10 audit tree: parent→child lineage, per-node tokens/verdict
 ```
 
+> **Audit-safe by construction (since Unreleased).** You pass `provider` on `ctx`, and a wired gate records the per-run ctx VERBATIM as `action._ctx`. `recurse()` **strips the live provider** (and thus its `apiKey`) from the ctx at every governance boundary before it reaches `gate.record`/`gate.check`, so the key never lands in the audit JSONL — only the provider *name* does (identity, not secret). The provider still reaches the worker (it runs); only the audited copy is cleaned. (bareguard's own secret-redaction is opt-in and value/pattern-based, so do not rely on it to catch a key you put on `ctx` — but DO scrub any *other* secret-bearing field you thread on `ctx` yourself, or configure `gate` `secrets`.)
+
 **Control families (how the tree is shaped):**
 
 - **Family A — model-driven (default).** The worker is handed an in-process `spawn_child` tool and *decides* whether to split. `assessComplexity` is a **hint, not a gate** (only `simple → single-shot`, and the non-overridable `critical → force adversarial verify` safety floor). Nothing extra to set.

package/examples/litectx-as-store.mjs

@@ -63,16 +63,23 @@ async function main() {
   } catch {
     console.log('\n[litectx] not installed — the swap is one line:');
     console.log("    import { LiteCtx, liteCtxAsStore } from 'litectx';");
-    console.log('    const lc = new LiteCtx({ dbPath: \'./agent.db\' }); await lc.ready();');
+    console.log('    const lc = new LiteCtx({ root: \'./agent-ctx\' }); await lc.ready();');
     console.log('    const memory = new Memory({ store: liteCtxAsStore(lc) });  // ← only this line changes');
     console.log('\n  Install it (`npm install litectx`) to run the litectx half of this example.');
     return;
   }
 
-  const lc = new LiteCtx({ dbPath: join(tmpdir(), `litectx-as-store-${process.pid}.db`) });
+  // litectx >= 0.21 takes a `root` DIRECTORY (it manages its own files under it), not a `dbPath` file —
+  // passing `{ dbPath }` throws on construction. Use a fresh temp dir per run.
+  const root = mkdtempSync(join(tmpdir(), `litectx-as-store-${process.pid}-`));
+  const lc = new LiteCtx({ root });
   if (typeof lc.ready === 'function') await lc.ready();
-  await hostWorkflow(new Memory({ store: liteCtxAsStore(lc) }), 'litectx (ranked, graph-aware)');
-  if (typeof lc.close === 'function') lc.close();
+  try {
+    await hostWorkflow(new Memory({ store: liteCtxAsStore(lc) }), 'litectx (ranked, graph-aware)');
+  } finally {
+    if (typeof lc.close === 'function') lc.close();
+    rmSync(root, { recursive: true, force: true });
+  }
 }
 
 main().catch((err) => { console.error(err); process.exit(1); });

package/examples/with-bareguard.mjs

@@ -6,9 +6,12 @@
 // Run:  OPENAI_API_KEY=... node examples/with-bareguard.mjs
 //
 // What this demonstrates:
-//   - Single-gate governance: every tool call traverses gate.check; every
-//     result reaches gate.record (via wrapTools).
-//   - Budget halt: if accumulated cost exceeds maxCostUsd, gate halts the loop.
+//   - Single-gate governance: every tool call traverses gate.check (policy); every
+//     result reaches gate.record (via onToolResult + onLlmResult — wrapTools is deprecated).
+//   - Primitive enforcement: a shell→primitive actionTranslator makes bash.allow + fs.readScope
+//     actually fire (the default translator leaves them dead — relayfact F7/BA-3).
+//   - Budget halt: if accumulated cost exceeds maxCostUsd, gate halts the loop (a HaltError,
+//     caught by the Loop as a clean exit — distinct from a per-action deny; see humanChannel below).
 //   - Audit log: one JSONL line per gated event at ./bareagent-audit.jsonl.
 //   - humanChannel: required by bareguard. Here we auto-deny asks; in real use
 //     wire it to a chat platform, terminal prompt, etc.
@@ -29,16 +32,40 @@ const gate = new Gate({
   audit:  { path: './bareagent-audit.jsonl' },
   // Required by bareguard: any ask/halt event flows through here.
   // Auto-deny is the safest default for headless use; in real apps, wire to
-  // a Telegram/Slack/terminal prompt and return { decision: 'allow' | 'deny' }.
+  // a Telegram/Slack/terminal prompt and return a decision.
+  //   • { decision: 'deny' }  → denies THIS ONE action only; the loop keeps running and the
+  //     model may try something else. deny does NOT stop the loop (relayfact F11/BA-6) — under a
+  //     retry wrapper like `refine` a denied-but-not-stopped loop can keep spending.
+  //   • { decision: 'terminate' } → the clean-halt path: surfaces as a HaltError the Loop catches
+  //     and exits on. Use this (or a budget/turn cap) when you mean "stop", not "skip this action".
   humanChannel: async (event) => {
-    console.warn(`[humanChannel] ${event.kind}: ${event.rule} — auto-denying`);
+    console.warn(`[humanChannel] ${event.kind}: ${event.rule} — auto-denying (this action only)`);
     return { decision: 'deny' };
   },
 });
 await gate.init();
 
-// 2. Wire the gate into Loop's policy slot and wrap tools so gate.record fires.
-const { policy, wrapTools } = wireGate(gate);
+// 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).
+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.
+    case 'shell_read':
+    case 'shell_grep': return { type: 'read', path: 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: args?.path, args, _ctx: ctx ?? null };
+    default:           return { type: toolName, args, _ctx: ctx ?? null };
+  }
+};
+// 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 });
 
 // 3. Standard bareagent setup.
 const provider = new OpenAI({
@@ -50,16 +77,19 @@ const { tools } = createShellTools();
 const loop = new Loop({
   provider,
   policy,
+  onToolResult,  // every tool result → gate.record (with _ctx in scope)
+  onLlmResult,   // every LLM round → gate.record so budget.maxCostUsd covers token-only spend
   onError: (err, meta) => console.error(`[onError ${meta.source}]`, err.message),
 });
 
-// 4. Run.
+// 4. Run. Pass the tools as-is — gating is via policy/onToolResult, not by wrapping execute().
 const result = await loop.run(
   [{ role: 'user', content: 'List the contents of /tmp using shell_run with argv ["ls", "/tmp"].' }],
-  wrapTools(tools),
+  tools,
 );
 
 console.log('---');
 console.log('text:', result.text);
-console.log('cost:', result.cost?.toFixed(6) ?? 'n/a');
+// Loop returns the meter under result.metrics (result.cost was removed); costUsd is null when unpriced.
+console.log('cost:', result.metrics?.costUsd != null ? result.metrics.costUsd.toFixed(6) : 'n/a (unpriced)');
 console.log('audit log → ./bareagent-audit.jsonl');

package/package.json

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

package/src/recurse.d.ts

@@ -23,7 +23,12 @@ export type RecurseCtx = {
      */
     depth?: number | undefined;
     /**
-     * - Optional event stream forwarded to each worker Loop (receipts substrate).
+     * - Optional event stream forwarded to each worker Loop (receipts substrate). This
+     * is the observability channel for worker activity (relayfact F15/BA-5): recurse intentionally does NOT take
+     * `onToolCall`/`onText` Loop callbacks — instead every worker Loop emits `loop:tool_call` / `loop:tool_result`
+     * (and `loop:text`/`loop:done`) to THIS stream (loop.js), so a consumer observes worker tool calls by reading
+     * the stream, not via per-call callbacks. The full audit trail is stream + the RC-10 receipts tree + (if a
+     * gate is wired) the bareguard audit.
      */
     stream?: object;
     /**
@@ -252,7 +257,12 @@ export type Slice = {
  *   and worker tokens are all real spend (BA1: never invisible).
  * @property {number} [depth] - The current recursion depth (0 at the top). Incremented on each self-call;
  *   threaded into `policy`. Callers normally omit it (defaults to 0).
- * @property {object} [stream] - Optional event stream forwarded to each worker Loop (receipts substrate).
+ * @property {object} [stream] - Optional event stream forwarded to each worker Loop (receipts substrate). This
+ *   is the observability channel for worker activity (relayfact F15/BA-5): recurse intentionally does NOT take
+ *   `onToolCall`/`onText` Loop callbacks — instead every worker Loop emits `loop:tool_call` / `loop:tool_result`
+ *   (and `loop:text`/`loop:done`) to THIS stream (loop.js), so a consumer observes worker tool calls by reading
+ *   the stream, not via per-call callbacks. The full audit trail is stream + the RC-10 receipts tree + (if a
+ *   gate is wired) the bareguard audit.
  * @property {{recall: Function}} [litectx] - Optional litectx handle (RC-5, §10 step 7). Backs the `search`
  *   retrieval mode (`recall`). NOT used by `scan` — litectx has no exhaustive enumerate verb today; scan reads
  *   the generic array slice-source `opts.corpus` instead (the litectx-resident scan case waits on the litectx

package/src/recurse.js

@@ -111,6 +111,30 @@ function forChild(opts) {
   };
 }
 
+/**
+ * The ctx handed to a worker `Loop.run({ ctx })` or to a direct `ctx.policy(...)` checkpoint — i.e. the ctx
+ * that a wired gate records VERBATIM into the audit as `action._ctx` (see `defaultActionTranslator` in
+ * src/bareguard-adapter.js). It STRIPS the live `provider` instance, because that object carries the API key
+ * (`provider.apiKey`) and bareguard serializes `_ctx` to disk — so an un-stripped ctx writes the raw
+ * `sk-…` key into the plaintext audit log (F16/BA-1, confirmed by relayfact probe-03).
+ *
+ * Only the AUDITED copy is cleaned: the provider still rides in the recurse-internal ctx that is threaded into
+ * each child `recurse()` self-call (children need `ctx.provider` to run), and the worker Loop already receives
+ * the provider as a constructor option — `Loop.run` never reads `ctx.provider`. The provider's IDENTITY is not
+ * lost from the audit either: the meter records the provider NAME on the `{type:'llm'}` action's args.
+ *
+ * NB: this strips the provider only — the leak that was grounded. A caller that threads its OWN secret-bearing
+ * fields onto ctx is backstopped by bareguard-side redaction (BG-1), the defense-in-depth pair to this fix.
+ * @param {RecurseCtx} ctx
+ * @param {object} [overrides] - extra fields to set on the audited copy (e.g. `{ depth }`).
+ * @returns {object}
+ */
+function auditSafeCtx(ctx, overrides = {}) {
+  const safe = { ...(ctx || {}) };
+  delete (/** @type {any} */ (safe)).provider;
+  return { ...safe, ...overrides };
+}
+
 /**
  * @typedef {object} RecurseCtx
  * The per-run runtime blob — the wiring, threaded down the whole recursion tree (and forwarded to the worker
@@ -122,7 +146,12 @@ function forChild(opts) {
  *   and worker tokens are all real spend (BA1: never invisible).
  * @property {number} [depth] - The current recursion depth (0 at the top). Incremented on each self-call;
  *   threaded into `policy`. Callers normally omit it (defaults to 0).
- * @property {object} [stream] - Optional event stream forwarded to each worker Loop (receipts substrate).
+ * @property {object} [stream] - Optional event stream forwarded to each worker Loop (receipts substrate). This
+ *   is the observability channel for worker activity (relayfact F15/BA-5): recurse intentionally does NOT take
+ *   `onToolCall`/`onText` Loop callbacks — instead every worker Loop emits `loop:tool_call` / `loop:tool_result`
+ *   (and `loop:text`/`loop:done`) to THIS stream (loop.js), so a consumer observes worker tool calls by reading
+ *   the stream, not via per-call callbacks. The full audit trail is stream + the RC-10 receipts tree + (if a
+ *   gate is wired) the bareguard audit.
  * @property {{recall: Function}} [litectx] - Optional litectx handle (RC-5, §10 step 7). Backs the `search`
  *   retrieval mode (`recall`). NOT used by `scan` — litectx has no exhaustive enumerate verb today; scan reads
  *   the generic array slice-source `opts.corpus` instead (the litectx-resident scan case waits on the litectx
@@ -363,7 +392,7 @@ async function recurse(task, ctx = {}, opts = {}) {
         provider,
         window: opts.window,
         passes: opts.passes,
-        ctx: { ...ctx, depth },
+        ctx: auditSafeCtx(ctx, { depth }), // scan's Loop run ctx reaches the gate — strip provider (F16/BA-1)
         onLlmResult: ctx.onLlmResult,
         policy: ctx.policy,
       }));
@@ -394,7 +423,10 @@ async function recurse(task, ctx = {}, opts = {}) {
   const out = await loop.run(
     [{ role: 'user', content: task }],
     tools,
-    { ctx: { ...ctx, depth } },
+    // auditSafeCtx: the run ctx reaches the gate as `_ctx`; strip the key-bearing provider (F16/BA-1). The
+    // worker Loop already has `provider` as a constructor option, so stripping it from the run ctx is invisible
+    // to the worker and only cleans the audited copy.
+    { ctx: auditSafeCtx(ctx, { depth }) },
   );
 
   node.tokens = out.metrics ? out.metrics.tokens : null;
@@ -524,7 +556,7 @@ async function recurseScan(task, ctx, opts, state) {
       provider,
       window: opts.window,
       passes: opts.passes,
-      ctx: { ...ctx, depth: state.depth },
+      ctx: auditSafeCtx(ctx, { depth: state.depth }), // scan's Loop run ctx reaches the gate — strip provider (F16/BA-1)
       onLlmResult: ctx.onLlmResult,
       policy: ctx.policy,
     });
@@ -615,7 +647,7 @@ async function recursePartition(task, ctx, opts, state) {
     //     spends (bounds the burst to zero); a plain deny is advisory (allowlist-safe), same contract as fanout.
     if (typeof ctx.policy === 'function') {
       try {
-        await ctx.policy('recurse_partition', { width, size, depth }, { ...ctx, depth });
+        await ctx.policy('recurse_partition', { width, size, depth }, auditSafeCtx(ctx, { depth }));
       } catch (err) {
         if (err instanceof HaltError) throw err;
       }
@@ -731,7 +763,7 @@ async function recurseFanout(task, ctx, opts, state) {
     //    descriptor — the load-bearing budget signal is the HaltError, on bareguard's existing contract.
     if (typeof ctx.policy === 'function') {
       try {
-        await ctx.policy('recurse_fanout', { count: steps.length, depth }, { ...ctx, depth });
+        await ctx.policy('recurse_fanout', { count: steps.length, depth }, auditSafeCtx(ctx, { depth }));
       } catch (err) {
         if (err instanceof HaltError) throw err;
         // non-halt policy error/deny → advisory; proceed (per-worker policy still gates each child below)

package/tools/shell.d.ts

@@ -1,4 +1,13 @@
-export type GrepArgs = {
+declare namespace _exports {
+    export { GrepArgs, RunArgvArgs, ExecCommandArgs, ToolDef };
+}
+declare namespace _exports {
+    export { createShellTools };
+    export { _grepCore };
+    export { writeFile as _writeFile };
+}
+export = _exports;
+type GrepArgs = {
     pattern: string;
     path: string;
     recursive?: boolean | undefined;
@@ -11,28 +20,28 @@ export type GrepArgs = {
      */
     timeout?: number | undefined;
 };
-export type RunArgvArgs = {
+type RunArgvArgs = {
     argv: string[];
     cwd?: string | undefined;
     timeout?: number | undefined;
     maxBuffer?: number | undefined;
     env?: Record<string, string> | undefined;
 };
-export type ExecCommandArgs = {
+type ExecCommandArgs = {
     command: string;
     cwd?: string | undefined;
     timeout?: number | undefined;
     maxBuffer?: number | undefined;
     env?: Record<string, string> | undefined;
 };
-export type ToolDef = import("../types").ToolDef;
+type ToolDef = import("../types").ToolDef;
 /**
  * Create the three shell tools. No options — configuration is per-call via tool args,
  * gating is the caller's responsibility via `new Loop({ policy })`.
  *
  * @returns {{tools: ToolDef[]}}
  */
-export function createShellTools(): {
+declare function createShellTools(): {
     tools: ToolDef[];
 };
 /**
@@ -54,7 +63,7 @@ export function createShellTools(): {
  * 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<{
+declare function _grepCore({ pattern, path: rawPath, recursive, maxMatches, flags }: GrepArgs): Promise<{
     hits: {
         file: string;
         line: number;
@@ -63,3 +72,17 @@ export function _grepCore({ pattern, path: rawPath, recursive, maxMatches, flags
     truncated: boolean;
     fileCount: number;
 }>;
+/**
+ * Write text to a file (the BA-2 first-class write primitive — a coding agent must edit files, and routing
+ * writes through the shell is impractical: redirection is a shell metachar that an argv/bash allowlist denies).
+ * Creates parent directories. Caps size as a sanity ceiling. NO shell — so it gates cleanly through bareguard's
+ * fs primitive when the adopter translates `shell_write` → `{ type:'write', path }` (see createShellTools doc).
+ * @param {{path: string, content?: string, append?: boolean, maxBytes?: number}} args
+ * @returns {Promise<string>}
+ */
+declare function writeFile({ path: rawPath, content, append, maxBytes }: {
+    path: string;
+    content?: string;
+    append?: boolean;
+    maxBytes?: number;
+}): Promise<string>;

package/tools/shell.js

@@ -3,13 +3,30 @@
 /**
  * Pure-Node shell tools — cross-platform (linux, macOS, Windows), no external binaries.
  *
- * Three primitives:
+ * Primitives:
  *   shell_read  — read a file or list a directory
  *   shell_grep  — regex search across files (JS regex, no grep/rg/findstr)
- *   shell_exec  — run a shell command with timeout + max buffer
+ *   shell_write — write/overwrite (or append to) a file, creating parent dirs (no shell)
+ *   shell_run   — run a command via an argv array (no shell, allowlist-friendly on argv[0])
+ *   shell_exec  — run a raw shell command with timeout + max buffer
  *
- * All three run through Loop's policy hook when wired via `new Loop({ policy })`.
+ * All run through Loop's policy hook when wired via `new Loop({ policy })`.
  * Library ships zero baked-in allowlist — gating is the agent author's responsibility.
+ *
+ * GATING WITH bareguard's fs/bash PRIMITIVES: these tools carry tool-named actions by default
+ * (`{ type:'shell_write' }`), which match `tools.allowlist`/`tools.denylist` but do NOT activate the
+ * `fs`/`bash` primitives — those need `action.type ∈ {read,write,edit,bash}` with `action.path`/`action.cmd`.
+ * To gate `shell_write` by `fs.writeScope` (so a write outside the allowed root is denied BEFORE it touches
+ * disk), translate it at the gate — see `examples/with-bareguard.mjs` for the `wireGate(gate, { actionTranslator })`
+ * mapping (`shell_write` → `{ type:'write', path }`, `shell_read`/`shell_grep` → `{ type:'read', path }`,
+ * `shell_run`/`shell_exec` → `{ type:'bash', cmd }`). A write tool alone is NOT auto-gated — validated by
+ * poc/ba2-write-tool-gate.mjs (without the translator the out-of-scope write leaks).
+ *
+ * CAVEAT (applies to read AND write scopes): bareguard's `fs` primitive matches paths LEXICALLY (no
+ * `realpath`/symlink resolution), so a symlink that lives INSIDE the allowed scope but points OUTSIDE it is
+ * not caught — a `shell_write` through such a link can escape the scope. If untrusted input can create
+ * symlinks under your scope, canonicalize (`fs.realpath`) before the gate, or keep the scope on a root with
+ * no attacker-writable symlinks. This is bareguard's documented lexical-match contract, not specific to this tool.
  */
 
 /** @typedef {import('../types').ToolDef} ToolDef */
@@ -20,6 +37,7 @@ const { exec, execFile } = require('node:child_process');
 const { Worker } = require('node:worker_threads');
 
 const DEFAULT_READ_MAX_BYTES = 256 * 1024;       // 256 KB
+const DEFAULT_WRITE_MAX_BYTES = 5 * 1024 * 1024; // 5 MB — a sanity ceiling on a single write (LLM-authored)
 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;
@@ -67,6 +85,31 @@ async function readEntry(rawPath, maxBytes) {
   return fs.readFile(resolved, 'utf8');
 }
 
+/**
+ * Write text to a file (the BA-2 first-class write primitive — a coding agent must edit files, and routing
+ * writes through the shell is impractical: redirection is a shell metachar that an argv/bash allowlist denies).
+ * Creates parent directories. Caps size as a sanity ceiling. NO shell — so it gates cleanly through bareguard's
+ * fs primitive when the adopter translates `shell_write` → `{ type:'write', path }` (see createShellTools doc).
+ * @param {{path: string, content?: string, append?: boolean, maxBytes?: number}} args
+ * @returns {Promise<string>}
+ */
+async function writeFile({ path: rawPath, content = '', append = false, maxBytes }) {
+  if (typeof rawPath !== 'string' || rawPath.length === 0) {
+    throw new Error('shell_write requires a non-empty "path" string');
+  }
+  const text = content == null ? '' : String(content);
+  const cap = maxBytes || DEFAULT_WRITE_MAX_BYTES;
+  const bytes = Buffer.byteLength(text, 'utf8');
+  if (bytes > cap) {
+    throw new Error(`shell_write content is ${bytes} bytes, over the ${cap}-byte cap (pass maxBytes to raise it)`);
+  }
+  const resolved = path.resolve(expandHome(rawPath));
+  await fs.mkdir(path.dirname(resolved), { recursive: true });
+  if (append) await fs.appendFile(resolved, text, 'utf8');
+  else await fs.writeFile(resolved, text, 'utf8');
+  return `${append ? 'appended' : 'wrote'} ${bytes} bytes to ${resolved}`;
+}
+
 // Probe the first 1KB for NUL bytes to skip binary files in grep walks.
 /** @param {string} filePath */
 async function isProbablyText(filePath) {
@@ -373,6 +416,23 @@ function createShellTools() {
       },
       execute: async (/** @type {GrepArgs} */ args) => grepPath(args),
     },
+    {
+      name: 'shell_write',
+      description: 'Write text to a file (overwriting it), creating parent directories as needed. No shell — so an ' +
+        'fs.writeScope policy can gate it by path (translate to {type:"write"}). Use append:true to add to the end ' +
+        'instead of overwriting. Returns a "wrote N bytes to <path>" summary. Max 5MB per write by default.',
+      parameters: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'Target file path. ~ expands to home. Parent dirs are created.' },
+          content: { type: 'string', description: 'The full text to write (UTF-8).' },
+          append: { type: 'boolean', description: 'Append to the file instead of overwriting it (default false).' },
+          maxBytes: { type: 'integer', description: 'Reject a write larger than this many bytes (default 5242880).' },
+        },
+        required: ['path', 'content'],
+      },
+      execute: async (/** @type {{path: string, content?: string, append?: boolean, maxBytes?: number}} */ args) => writeFile(args),
+    },
     {
       name: 'shell_run',
       description: 'Run a command with an argv array (no shell, no interpolation) and return {stdout, stderr, code, timedOut}. Use this when a policy allowlist needs to match on argv[0] — no shell metacharacter injection is possible. Default timeout 30s, max output 1MB.',
@@ -413,4 +473,4 @@ function createShellTools() {
   return { tools };
 }
 
-module.exports = { createShellTools, _grepCore };
+module.exports = { createShellTools, _grepCore, _writeFile: writeFile };