bare-agent 0.27.0 → 0.29.0

package/README.md

@@ -123,7 +123,7 @@ console.log(result.count, result.matchedIds);   // a code-derived count + the id
 
 **Providers:** OpenAI-compatible (OpenAI, OpenRouter, Groq, vLLM, LM Studio), Anthropic, Gemini (native), Ollama, CLIPipe, Fallback — or bring your own (one `generate` method). All return the same shape; swap freely. Usage including prompt-cache tiers is normalized, so `result.metrics` reports honest cumulative tokens + cost — and `null`, never a silent `0`, for a model it couldn't price. A model that rejects a non-default `temperature` (e.g. `claude-sonnet-5`, OpenAI o1/gpt-5-class return a `400`) is handled gracefully — the provider drops the param and retries once rather than failing the call, surfacing `temperatureDropped` so a caller can report the effective value.
 
-**The run tells you the truth about what happened on the wire.** Every provider reports **why** generation ended (`stopReason`, normalized across all of them), so a round the API **cut off at the token cap** can no longer masquerade as a finished answer: it returns `error: 'truncated:max_tokens'` with the partial text preserved, instead of a silent `error: null` (BA-6). Its tool calls are **refused, never executed** — a *complete* tool call always arrives tagged `tool_use`, so one riding a truncated round was cut off mid-generation with arguments missing, which is exactly how a truncated `shell_write` can zero a file. `error` is the sole success signal; a bound firing preserves the model's work rather than discarding it (BA-5).
+**The run tells you the truth about what happened on the wire.** Every provider reports **why** generation ended (`stopReason`, normalized across all of them and surfaced on **every** `Loop.run()` return), so a round the API **cut off at the token cap** can no longer masquerade as a finished answer: it returns `error: 'truncated:max_tokens'` with the partial text preserved, instead of a silent `error: null` (BA-6). Its tool calls are **refused, never executed** — a *complete* tool call always arrives tagged `tool_use`, so one riding a truncated round was cut off mid-generation with arguments missing, which is exactly how a truncated `shell_write` can zero a file. The same honesty now covers **every** non-clean terminal signal (BA-13): a safety `refusal` returns `error: 'refusal'` and a blown context window returns `error: 'context_exceeded'` (both were previously laundered into an empty success), while a resumable `pause_turn` makes the loop resume rather than terminate. `error` is the sole success signal; a bound firing preserves the model's work rather than discarding it (BA-5).
 
 **Thinking blocks survive the round-trip.** `claude-sonnet-5` and Opus 4.7+ run adaptive thinking **by default** — they return `thinking` blocks whether or not you ask — and Anthropic's contract is that those blocks come back **unchanged, signature included**, when a tool-use conversation continues. bare-agent used to drop every one, silently (the API returns 200 either way). They now ride the transcript on `Message.providerBlocks` and are replayed verbatim, with no flag to set. `new Anthropic({ thinking })` is a separate opt-in for pinning the mode or reaching `display`/`effort` — it does *not* enable thinking, which is already on. **This is a protocol/data-loss fix, not a capability one: a head-to-head with thinking fully preserved produced no better outcomes, and we say so rather than sell it (BA-7).**
 
@@ -161,6 +161,7 @@ const { policy, onLlmResult, onToolResult, filterTools } = wireGate(gate, {
     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
+    if (toolName === 'shell_edit')  return { type: 'edit',  args, _ctx: ctx }; // same fs.writeScope as write
     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.27.0 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.13.0` optional peer for governance) | Apache 2.0
+> v0.29.0 | Node.js >= 18 | zero required deps (`bareguard >=0.9.0 <0.13.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)
 
@@ -65,7 +65,8 @@ 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/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 |
+| Read/write files, list directories, run shell commands, grep | createShellTools (shell_read/grep/**write**/**edit**/run/exec) + Loop({ policy }) — gate `shell_write`/`shell_edit` via `fs.writeScope` with an actionTranslator |
+| Change one span of a big file without re-emitting the whole thing | `shell_edit({path, oldText, newText})` — anchored exact-once replace; the surgical alternative to whole-file `shell_write` (BA-13). Gate it as `{type:'edit'}` |
 | 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 })` |
@@ -388,7 +389,15 @@ Halt-severity decisions exit the loop cleanly via a typed `HaltError` — full m
 
 **A TRUNCATED round is reported, never laundered into a finish (BA-6, v0.27+).** Every provider now surfaces `GenerateResult.stopReason` — normalized across all five to one neutral vocabulary (`end_turn`, `max_tokens`, `tool_use`, `stop_sequence`, `refusal`, `pause_turn`, `context_exceeded`; `null` when the provider doesn't report one, e.g. CLIPipe). Before this, **no** provider read its finish-reason field, so a round the API **cut off at the output cap** hit the Loop's *"no tool calls ⇒ final answer"* rule and came back as a **clean finish with `error: null`** — a truncation indistinguishable from a model that chose to stop. It now returns **`result.error === 'truncated:max_tokens'`** with the partial text preserved (BA-5). Check `result.error === null` for success, as always. Note the **default `maxTokens` is 4096** and is deliberately unchanged: raising it silently lifts every adopter's ceiling and bill, which is the same class of sin as the silent truncation. If you run a reasoning model on hard tasks, **raise it yourself** — `loop.run(msgs, tools, { maxTokens: 16000 })` (it's a `run()` option, forwarded to the provider), and now you'll get a loud error instead of a quiet empty answer when you don't.
 
-**A truncated round's tool calls are REFUSED, and this is load-bearing.** A **complete** tool call always arrives tagged `tool_use`, **never** `max_tokens` (measured on the real API). So a tool call riding a truncated round was **cut off mid-generation with arguments missing** — which is exactly how a `shell_write` whose `content` never arrived emptied a 1789-line file (BA-4). The Loop therefore never executes the tool calls of a `max_tokens` round: it returns `truncated:max_tokens` instead. Refusing discards nothing legitimate, and it closes that data-loss path for **every** tool you grant, not just `shell_write`. `pause_turn` (a *resumable* server-tool state), `refusal` and `context_exceeded` are surfaced but deliberately **not** treated as truncations.
+**A truncated round's tool calls are REFUSED, and this is load-bearing.** A **complete** tool call always arrives tagged `tool_use`, **never** `max_tokens` (measured on the real API). So a tool call riding a truncated round was **cut off mid-generation with arguments missing** — which is exactly how a `shell_write` whose `content` never arrived emptied a 1789-line file (BA-4). The Loop therefore never executes the tool calls of a `max_tokens` round: it returns `truncated:max_tokens` instead. Refusing discards nothing legitimate, and it closes that data-loss path for **every** tool you grant, not just `shell_write`.
+
+**Every non-clean terminal stop reason is error-tagged, and `stopReason` rides every return (BA-13, v0.28+).** BA-6 fixed exactly one stop reason (`max_tokens`); the others still laundered a non-finish into a clean `error: null`. They no longer do:
+- `refusal` → **`result.error === 'refusal'`** (partial text preserved). A safety refusal is **not** an empty success. `RECITATION` fires on entirely benign prompts, so this is reachable on ordinary runs.
+- `context_exceeded` → **`result.error === 'context_exceeded'`** (ran out of context window — a spend/limit story, distinct from the output cap).
+- `pause_turn` → the Loop **resumes** the turn (a resumable server-tool pause is neither terminal nor an error). Resuming appends the paused assistant turn (its partial text + provider-native server-tool blocks) and re-requests — the documented Anthropic pause_turn protocol, so the server continues where it left off rather than restarting. A pause that never progresses is caught by the same `HARD_ROUND_LIMIT` / gate `maxTurns` bounds as any non-advancing loop.
+- The tool calls of a `refusal` / `context_exceeded` round are **refused, not executed** — the same BA-4 closure as `max_tokens`.
+
+And **`result.stopReason`** (the neutral value, or `null`) is now present on **every** `Loop.run()` return, not only the clean-finish path — branch on it when you need *why* a run ended, not just *whether* it succeeded. **`error` stays the sole success signal** (`result.error === null`), and this is deliberately error-tagged rather than "surface `stopReason` only": `recurse` and any consumer following that invariant branch on `error`, so a refused worker now propagates an honest `{ incomplete }` up the tree with **zero recurse changes**. **Behavior change to note:** a refused round that previously returned `error: null` + empty text now returns `error: 'refusal'` — the point of the fix, but branch on `error`, not emptiness.
 
 **Deny-spin short-circuit (`maxConsecutiveDenials`, default 3, v0.25+).** A *non-halt* deny (a `policy` verdict that isn't `true` — e.g. a `humanChannel: deny`, an allowlist miss, a `content`/`fs.writeScope` block) is **advisory**: it's fed back to the model as a tool result so the model can pivot to a different allowed tool. But a model that keeps retrying the *same* denied action would otherwise spin every round until your `budget.maxCostUsd` finally halts it — burning the whole cap with no progress (this bit a coding agent whose write kept tripping `content.askPatterns`). The Loop now counts **consecutive** denials (any allowed call resets the streak, preserving the pivot) and short-circuits at `maxConsecutiveDenials` with `result.error === 'denied:<tool>'` (a clean return, transcript sealed — never a throw). Check `result.error?.startsWith('denied:')` to distinguish a governance block from a completed run; set `maxConsecutiveDenials: 0` (or `Infinity`) on `new Loop({...})` to restore the pure-advisory behavior. Under `recurse`, a short-circuited worker returns a **labeled** `{ incomplete: true, blocker: 'governance-deny' }` (and `receipts.blocker`) so you can widen scope / re-gate / escalate rather than read it as a model failure.
 
@@ -415,6 +424,7 @@ const { policy, onToolResult } = wireGate(gate, {
     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)
+    if (toolName === 'shell_edit')  return { type: 'edit',  args, _ctx: ctx };  // same fs.writeScope as write (reads args.path)
     return { type: toolName, args, _ctx: ctx };          // fall through to defaultActionTranslator
   },
 });
@@ -1239,6 +1249,7 @@ Mobile tools follow the observe-act pattern: action tools auto-return a fresh sn
 |---|---|
 | `shell_read` | Read a file (utf8, 256KB cap) or list a directory (tab-separated). `~` expands to home. |
 | `shell_write` | Write (or `append:true`) UTF-8 text to a file, creating parent dirs. 5MB cap. No shell, so it gates cleanly through `fs.writeScope` once translated to `{type:'write'}`. **`content` is REQUIRED** — see the truncation guard below. |
+| `shell_edit` | Anchored exact-string replace — the **surgical** alternative to whole-file `shell_write` (BA-13). `{path, oldText, newText}`: `oldText` must occur **exactly once** (quote surrounding lines to be unique); `newText` is spliced in **verbatim** (`""` deletes). Returns a compact `edited <path>: 1 replacement` receipt, never the body. 0 or 2+ matches → a refusal **returned as the tool result** (the model re-anchors; file untouched). Gates through `fs.writeScope` translated to `{type:'edit'}` — see the note below. |
 | `shell_grep` | JavaScript regex search across files. Walks directories, skips binary files, returns `{hits: [{file, line, text}], truncated, fileCount}`. |
 | `shell_run` | Run a command with an **argv array** via `child_process.execFile` (no shell, no metacharacter interpretation). Returns `{stdout, stderr, code, timedOut}`. **Use this when you need a policy allowlist.** |
 | `shell_exec` | Run a raw shell command string via `/bin/sh -c` (or `cmd.exe`). Returns the same shape. **Shell metacharacters are interpreted — naive allowlists are bypassable.** Use only when you genuinely need shell features (pipes, redirects, globs). |
@@ -1247,6 +1258,8 @@ Mobile tools follow the observe-act pattern: action tools auto-return a fresh sn
 
 > **⚠️ `shell_write` requires `content` — and a gate cannot cover for it (v0.27+).** `content` used to default to `''`, so a tool call that OMITTED it silently overwrote the target with **zero bytes** and returned `"wrote 0 bytes to <path>"` as success. That is the ordinary shape of a model hitting its **output-token cap** mid-generation on a long file — observed live emptying a 1789-line source file. **No policy can catch it:** a 0-byte write is a *legal* write, and bareguard's `fs` primitive judges `{type:'write', path}` without inspecting the body (the gate correctly `allow`s it). `shell_write` now **rejects** an absent, `null`, or non-string `content` and leaves the file byte-identical; the error tells the model to retry with the full content. An explicit `content: ""` still empties the file — that one is deliberate.
 
+> **`shell_edit` — the surgical write (BA-13).** Changing one line of an 800-line file with `shell_write` forces the model to re-emit **all 800 lines** as tool-call JSON: an output-token tax ∝ file size (output is the expensive token class), paid on every revision, and the maximal broken-tree surface (a truncated rewrite mangles the lines it never meant to touch — the BA-4/BA-6 class). `shell_edit({path, oldText, newText})` emits only the anchor + replacement. Semantics worth knowing: `oldText` must match **exactly once** (a 0/2+ match is a refusal *returned as the tool result*, so the loop continues and the model widens the anchor — not a throw, so a repeated-identical miss is bounded by maxTurns/budget, not the spin guard); missing/empty `oldText` or missing/non-string `newText` **throw** (BA-4 guards; `newText:""` is a legal deletion); the write is **atomic** (sibling temp + rename, mode preserved) so an fs failure never leaves a partial file; and `newText` is a **literal splice** (a `$&`/`$1` in it lands verbatim, unlike `String.replace`). Gate it exactly like `shell_write` but as `{type:'edit'}` — **bareguard gates `edit` by the same `fs.writeScope` as `write` with zero config** (its FS primitive's `FS_TYPES` already includes `edit`).
+
 > **⚠️ `shell_exec` injection caveat.** `"ls"` passes a base-command allowlist like `args.command.split(/\s+/)[0]`, but so does `"ls;rm -rf /tmp/x"` — the shell runs both. **A base-command allowlist is NOT safe for `shell_exec`.** For policy-gated use, prefer `shell_run({argv})` and allow-list on `args.argv[0]` — there is no shell in that path, so metacharacters are just literal argument bytes. Use `shell_exec` only when the agent needs pipes/redirects/globs, and gate it at a higher level (human approval, narrow intent).
 
 ```javascript

package/examples/with-bareguard.mjs

@@ -60,6 +60,8 @@ const actionTranslator = (toolName, args, ctx) => {
     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 };
+    // shell_edit is an anchored edit — bareguard gates {type:'edit'} by the SAME fs.writeScope as write.
+    case 'shell_edit':  return { type: 'edit',  path: args?.path, args, _ctx: ctx ?? null };
     default:           return { type: toolName, args, _ctx: ctx ?? null };
   }
 };

package/package.json

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

package/src/loop.d.ts

@@ -136,7 +136,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, msgs: Message[], metrics: RunMetrics, temperatureDropped?: boolean}>}
+     * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, msgs: Message[], metrics: RunMetrics, 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
@@ -153,6 +153,13 @@ export class Loop {
      *
      *   A caller-initiated `stop()` returns `error: null` — a deliberate stop is not a fault. (It previously
      *   fell through to the hard-round-limit return and reported that safety warning as its `error`.)
+     *
+     *   BA-13 — `stopReason` (the round's NEUTRAL stop reason) is surfaced on EVERY return, and non-clean
+     *   terminal rounds are error-tagged instead of laundered into `error: null`: a safety `refusal` returns
+     *   `error: 'refusal'` and a `context_exceeded` returns `error: 'context_exceeded'`, both with partial
+     *   text preserved (BA-5). BEHAVIOR CHANGE: a refused round that previously returned `error: null` with
+     *   empty text now returns `error: 'refusal'` — the point of the fix. `pause_turn` is NOT terminal: the
+     *   loop resumes (bounded by the hard round limit / gate). `error` stays the sole success signal.
      * @throws {Error} `[Loop] Tool is missing a name` — when a tool has no name or a non-string name.
      * @throws {Error} `[Loop] Tool "X" is missing an execute() function` — when execute is not a function.
      * @throws {Error} `[Loop] Tool "X" has invalid parameters` — when parameters is not an object.
@@ -163,6 +170,7 @@ export class Loop {
         usage: Usage;
         cost: number;
         error: string | null;
+        stopReason: string | null;
         msgs: Message[];
         metrics: RunMetrics;
         temperatureDropped?: boolean;
@@ -193,7 +201,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, msgs: Message[], metrics: RunMetrics, temperatureDropped?: boolean}>}
+     * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, msgs: Message[], metrics: RunMetrics, temperatureDropped?: boolean}>}
      */
     chat(text: string, tools?: ToolDef[], options?: Record<string, any>): Promise<{
         text: string;
@@ -201,6 +209,7 @@ export class Loop {
         usage: Usage;
         cost: number;
         error: string | null;
+        stopReason: string | null;
         msgs: Message[];
         metrics: RunMetrics;
         temperatureDropped?: boolean;

package/src/loop.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const { ToolError, HaltError } = require('./errors');
-const { isTruncated } = require('./provider-stop-reason');
+const { classifyStopReason } = require('./provider-stop-reason');
 
 /** @typedef {import('../types').Provider} Provider */
 /** @typedef {import('../types').Message} Message */
@@ -346,7 +346,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, msgs: Message[], metrics: RunMetrics, temperatureDropped?: boolean}>}
+   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, msgs: Message[], metrics: RunMetrics, 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
@@ -363,6 +363,13 @@ class Loop {
    *
    *   A caller-initiated `stop()` returns `error: null` — a deliberate stop is not a fault. (It previously
    *   fell through to the hard-round-limit return and reported that safety warning as its `error`.)
+   *
+   *   BA-13 — `stopReason` (the round's NEUTRAL stop reason) is surfaced on EVERY return, and non-clean
+   *   terminal rounds are error-tagged instead of laundered into `error: null`: a safety `refusal` returns
+   *   `error: 'refusal'` and a `context_exceeded` returns `error: 'context_exceeded'`, both with partial
+   *   text preserved (BA-5). BEHAVIOR CHANGE: a refused round that previously returned `error: null` with
+   *   empty text now returns `error: 'refusal'` — the point of the fix. `pause_turn` is NOT terminal: the
+   *   loop resumes (bounded by the hard round limit / gate). `error` stays the sole success signal.
    * @throws {Error} `[Loop] Tool is missing a name` — when a tool has no name or a non-string name.
    * @throws {Error} `[Loop] Tool "X" is missing an execute() function` — when execute is not a function.
    * @throws {Error} `[Loop] Tool "X" has invalid parameters` — when parameters is not an object.
@@ -427,6 +434,12 @@ class Loop {
     // The caller decides what a partial result is worth; the library must not decide it is worth nothing.
     // Stays '' when the model never produced text (nothing to preserve — we never invent a placeholder).
     let lastText = '';
+    // BA-13: the NEUTRAL stop reason of the most recent completed round (post-provider-normalization).
+    // Surfaced on EVERY return so a caller can branch on WHY a run ended, not just its `error` tag — the
+    // load-bearing companion to the classifier (a terminal `error` says "not a clean finish"; `stopReason`
+    // says which kind). Stays null until the first round completes, and across a provider error / a
+    // pre-round stop() it holds the last round's value (or null if none ran).
+    let lastStopReason = null;
     // BA-10: sticky across rounds — true if ANY round's `temperature` was dropped by the model (400,
     // unsupported/deprecated) and retried without it. Surfaced on the result so an upstream receipt
     // (recurse's refineLeaf) can report the EFFECTIVE temperature rather than the ignored request.
@@ -463,7 +476,7 @@ class Loop {
         sealDanglingToolCalls(msgs, `[halted:${stuckTag}]`);
         this._reportError('stuck', new Error(`tool "${tc.name}" failed ${identicalErrors} times with identical arguments`), { rule: stuckTag, attempts: identicalErrors });
         this._safeEmit({ type: 'loop:done', data: { text: lastText, stuck: true, rule: stuckTag, cost: totalCost } });
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: stuckTag, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: stuckTag, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
       }
       return null;
     };
@@ -691,7 +704,7 @@ class Loop {
         this._reportError('provider', err, { round });
         if (this.throwOnError) throw err;
         // BA-5: a mid-run provider failure must not erase the work of the rounds that succeeded.
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: err.message, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: err.message, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
       }
 
       lastUsage = result.usage || lastUsage;
@@ -700,6 +713,9 @@ class Loop {
       // is the text most worth keeping). A tool-call-only round carries no text, so hold the last non-empty
       // one rather than letting a silent round erase an earlier account.
       if (typeof result.text === 'string' && result.text.trim() !== '') lastText = result.text;
+      // BA-13: capture this round's neutral stop reason for surfacing on the run's return (every exit
+      // path reads lastStopReason). Non-string / absent ⇒ null (the provider's pre-BA-6 degrade).
+      lastStopReason = typeof result.stopReason === 'string' ? result.stopReason : null;
       if (result.temperatureDropped) temperatureDropped = true;
       // Publish the latest measured usage to ctx (non-enumerable, fail-open) so a transcript-bound seam —
       // e.g. F2 stash auto-compaction — can read EXACT provider-counted `inputTokens` to gauge context
@@ -745,21 +761,48 @@ class Loop {
         }
       }
 
-      // BA-6: the API CUT THIS ROUND OFF at the output cap. It is NOT a finished turn, and it must not
-      // reach the "no tool calls ⇒ final answer" rule below — that rule is what laundered a truncation
-      // into a clean `error: null` completion, indistinguishable from a model that chose to stop.
-      //
-      // Placed AFTER metering (the tokens were really spent — the gate must see them) and BEFORE tool
-      // execution, which is the load-bearing half: a truncated round's tool calls were cut off
-      // mid-generation, so their arguments are missing keys. Executing one is exactly how BA-4 emptied a
-      // 1789-line file (`shell_write` reached the fs with no `content`). A COMPLETE call always arrives
-      // tagged 'tool_use', never 'max_tokens' (measured on the real API, poc/ba6-stop-reason-mapping.mjs),
-      // so refusing here discards nothing legitimate and closes the data-loss path for EVERY tool.
+      // BA-13: classify this round's terminal signal against the neutral stop-reason vocabulary. BA-6
+      // short-circuited exactly one non-clean reason (max_tokens); this gate is the general form. It sits
+      // AFTER metering (the tokens were really spent — the gate must see them) and BEFORE tool execution,
+      // which is the load-bearing half: a non-final round's tool calls were cut off mid-generation, so
+      // their arguments are missing keys. Executing one is exactly how BA-4 emptied a 1789-line file
+      // (`shell_write` reached the fs with no `content`). A COMPLETE call always arrives tagged 'tool_use',
+      // never a truncation/refusal (measured on the real API, poc/ba6-stop-reason-mapping.mjs), so refusing
+      // the tool calls of ANY non-clean terminal round discards nothing legitimate and closes the data-loss
+      // path for EVERY tool — the BA-4 protocol-layer closure applied uniformly (see classifyStopReason).
       //
-      // We report; the caller decides. No auto-retry at a bigger cap: that doubles spend against a budget
-      // the gate is enforcing, and the right recovery (raise the cap? split the task? shorten it?) is the
-      // caller's call, not the library's. `lastText` (BA-5) preserves the partial work either way.
-      if (isTruncated(result.stopReason)) {
+      // We report; the caller decides. No auto-retry: that doubles spend against the gate's budget, and the
+      // right recovery (raise the cap? re-gate the refusal? shorten the context?) is the caller's, not the
+      // library's. `lastText` (BA-5) preserves the partial work on every terminal leg.
+      const terminal = classifyStopReason(result.stopReason);
+      if (terminal === 'resume') {
+        // BA-13: `pause_turn` — a RESUMABLE server-side tool pause (the API's server-tool loop hit its
+        // per-turn iteration cap mid-turn). NOT a finish, NOT an error. Resuming REQUIRES re-sending the
+        // paused assistant turn: the provider detects the trailing server-tool block and continues where
+        // it left off (the documented Anthropic pause_turn protocol — "re-send the user message and
+        // assistant response"). A bare `continue` WITHOUT appending re-sends byte-identical input, so the
+        // server restarts the turn from scratch and pauses again, spinning to HARD_ROUND_LIMIT (100 paid
+        // calls) instead of resuming. So append the assistant turn — its partial text plus the
+        // provider-native server-tool/thinking blocks (which the Anthropic provider replays via
+        // providerBlocks) — BEFORE continuing, exactly as the tool-execution path pushes its assistant
+        // turn. Only push when there is something to carry: an empty assistant turn (no text, no blocks)
+        // is wire-invalid, and a pause with no partial output cannot be advanced anyway — HARD_ROUND_LIMIT
+        // (or the gate) bounds that pathological case. No client tool_calls are pushed: a server pause
+        // does not carry an unpaired client call, and pushing one would orphan it (wire-invalid) — the
+        // same BA-4 refusal principle as the other non-clean terminal legs.
+        const hasText = typeof result.text === 'string' && result.text.trim() !== '';
+        if (hasText || result.providerBlocks) {
+          msgs.push({ role: 'assistant', content: result.text || null, ...(result.providerBlocks && { providerBlocks: result.providerBlocks }) });
+        }
+        this._safeEmit({ type: 'loop:resume', data: { round, stopReason: lastStopReason } });
+        continue;
+      }
+      if (terminal) {
+        // terminal ∈ {'truncated','refusal','context_exceeded'} — a non-clean terminal round. Error-tag it
+        // (NOT just surface stopReason): `recurse`'s worker path and the bareloop adopter both branch on
+        // `error`, and 0.27.0's "error is the sole success signal" invariant must stay true — an
+        // `error:null` + `stopReason:'refusal'` would re-breed BA-6 for these legs.
+        const errorTag = terminal === 'truncated' ? 'truncated:max_tokens' : terminal;
         const dropped = (result.toolCalls || []).length;
         // Seal the transcript with the partial text only. Deliberately NOT the tool_calls: pushing a call
         // we refuse to execute would orphan it (a tool_call with no tool_result is a wire-invalid
@@ -767,8 +810,8 @@ class Loop {
         if (typeof result.text === 'string' && result.text.trim() !== '') {
           msgs.push({ role: 'assistant', content: result.text });
         }
-        this._safeEmit({ type: 'loop:done', data: { text: lastText, truncated: true, droppedToolCalls: dropped, cost: totalCost } });
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: 'truncated:max_tokens', msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        this._safeEmit({ type: 'loop:done', data: { text: lastText, ...(terminal === 'truncated' && { truncated: true }), terminal, stopReason: lastStopReason, droppedToolCalls: dropped, cost: totalCost } });
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: errorTag, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
       }
 
       // No tool calls — LLM gave a final text response
@@ -788,7 +831,7 @@ class Loop {
           try { await flush(msgs, ctx); }
           catch (err) { if (err instanceof HaltError) throw err; this._reportError('trim-flush', err, { round }); }
         }
-        return { text: result.text, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: result.text, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
       }
 
       // Execute tool calls
@@ -897,7 +940,7 @@ class Loop {
               sealDanglingToolCalls(msgs, `[halted:${denyTag}]`);
               this._reportError('denied', new Error(`policy denied ${consecutiveDenials} consecutive tool calls (${tc.name})`), { rule: denyTag, denials: consecutiveDenials });
               this._safeEmit({ type: 'loop:done', data: { text: lastText, denied: true, rule: denyTag, cost: totalCost } });
-              return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: denyTag, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+              return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: denyTag, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
             }
             continue;
           }
@@ -971,7 +1014,7 @@ class Loop {
         // BA-5: the rule tag survives on `error`; so does the work. A halt is how a bounded attempt is
         // SUPPOSED to end — the caller reads `error` to know it was bounded and `text` to learn from it.
         this._safeEmit({ type: 'loop:done', data: { text: lastText, halted: true, rule, cost: totalCost } });
-        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+        return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
       }
       throw err;
     }
@@ -1001,20 +1044,20 @@ class Loop {
             const rule = err.rule || 'unknown';
             this._reportError('halt', err, { rule, reason: err.decision?.reason ?? null });
             this._safeEmit({ type: 'loop:done', data: { text: lastText, halted: true, rule, cost: totalCost } });
-            return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+            return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: `halt:${rule}`, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
           }
           this._reportError('trim-flush', err, { phase: 'stop' });
         }
       }
       this._safeEmit({ type: 'loop:done', data: { text: lastText, stopped: true, cost: totalCost } });
-      return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+      return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: null, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
     }
 
     // Hard safety limit — should never fire under normal usage; bareguard's
     // limits.maxTurns (or the LLM's natural completion) ends the loop first.
     const warning = `[Loop] hit internal safety limit of ${HARD_ROUND_LIMIT} rounds. Wire bareguard for proper governance — see bare-agent/bareguard.`;
     this._safeEmit({ type: 'loop:done', data: { text: lastText, warning, cost: totalCost } });
-    return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: warning, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
+    return { text: lastText, toolCalls: [], usage: lastUsage, cost: totalCost, error: warning, stopReason: lastStopReason, msgs, metrics: finalizeMetrics(), ...(temperatureDropped && { temperatureDropped: true }) };
   }
 
   /**
@@ -1087,7 +1130,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, msgs: Message[], metrics: RunMetrics, temperatureDropped?: boolean}>}
+   * @returns {Promise<{text: string, toolCalls: ToolCall[], usage: Usage, cost: number, error: string|null, stopReason: string|null, msgs: Message[], metrics: RunMetrics, temperatureDropped?: boolean}>}
    */
   async chat(text, tools = [], options = {}) {
     this._history.push({ role: 'user', content: text });

package/src/provider-stop-reason.d.ts

@@ -20,7 +20,15 @@ export function normalizeStopReason(raw: string | null | undefined, provider: "a
  * folded in here — `pause_turn` in particular is a RESUMABLE state, and erroring on it would break
  * server-side tool flows that are working exactly as designed.
  *
+ * Retained for back-compat (it was the Loop's original BA-6 gate). The Loop now routes through
+ * {@link classifyStopReason} instead — `isTruncated(x)` is exactly `classifyStopReason(x) === 'truncated'`.
+ *
  * @param {string|null|undefined} stopReason - a NEUTRAL value (post-{@link normalizeStopReason}).
  * @returns {boolean}
  */
 export function isTruncated(stopReason: string | null | undefined): boolean;
+/**
+ * @param {string|null|undefined} stopReason - a NEUTRAL value (post-{@link normalizeStopReason}).
+ * @returns {'truncated'|'refusal'|'context_exceeded'|'resume'|null}
+ */
+export function classifyStopReason(stopReason: string | null | undefined): "truncated" | "refusal" | "context_exceeded" | "resume" | null;

package/src/provider-stop-reason.js

@@ -111,7 +111,10 @@ function normalizeStopReason(raw, provider, ctx = {}) {
   if (!table) return raw;
   // An unrecognized-but-present value passes through: the caller can still SEE it, and the Loop only
   // acts on the known vocabulary — so a new upstream value can never be mistaken for a truncation.
-  const mapped = table[raw] || raw;
+  // Own-property only (mirror of classifyStopReason): `raw` is a provider/proxy-supplied field, so a
+  // value like 'toString'/'constructor' would otherwise resolve `table[raw]` to an inherited
+  // Object.prototype function (truthy) and be returned in place of the verbatim string.
+  const mapped = Object.prototype.hasOwnProperty.call(table, raw) ? table[raw] : raw;
 
   // GEMINI AND OLLAMA HAVE NO `tool_use` FINISH REASON (both measured live: Gemini returns
   // `finishReason: STOP` and Ollama `done_reason: 'stop'` on a round that emitted a complete function
@@ -138,6 +141,9 @@ function normalizeStopReason(raw, provider, ctx = {}) {
  * folded in here — `pause_turn` in particular is a RESUMABLE state, and erroring on it would break
  * server-side tool flows that are working exactly as designed.
  *
+ * Retained for back-compat (it was the Loop's original BA-6 gate). The Loop now routes through
+ * {@link classifyStopReason} instead — `isTruncated(x)` is exactly `classifyStopReason(x) === 'truncated'`.
+ *
  * @param {string|null|undefined} stopReason - a NEUTRAL value (post-{@link normalizeStopReason}).
  * @returns {boolean}
  */
@@ -145,4 +151,50 @@ function isTruncated(stopReason) {
   return stopReason === 'max_tokens';
 }
 
-module.exports = { normalizeStopReason, isTruncated };
+/**
+ * BA-13 — classify a round's NEUTRAL stop reason into the terminal ACTION the Loop must take.
+ *
+ * BA-6 short-circuited exactly one non-clean stop reason (`max_tokens`). Every OTHER non-clean reason
+ * — `refusal`, `context_exceeded`, `pause_turn` — fell through the Loop's "no tool calls ⇒ final
+ * answer" rule and was laundered into a clean `error: null` empty success (the BA-4/5/6/7 bug class:
+ * an under-modeled boundary round rounding optimistically toward "done"). A `RECITATION` refusal fires
+ * on entirely BENIGN prompts, so this was reachable on ordinary runs, and it propagated up `recurse`'s
+ * agent tree as a converged sub-task.
+ *
+ * One table with an EXPLICIT pass-through default replaces the single `if (isTruncated)` — the BA-7
+ * lesson ("don't parse-key on a closed set") applied to termination: BA-6 added one leg, BA-13 adds
+ * two terminals plus one resume, and the NEXT new stop reason degrades to pass-through (status quo)
+ * rather than re-breeding the bug.
+ *
+ *   'truncated'         `max_tokens` — cut off at the output cap (BA-6). Loop returns `error:'truncated:max_tokens'`.
+ *   'refusal'           declined on safety grounds. Loop returns `error:'refusal'` + partial text.
+ *   'context_exceeded'  ran out of context window. Loop returns `error:'context_exceeded'` + partial text.
+ *   'resume'            `pause_turn` — a RESUMABLE server-tool pause. NOT terminal, NOT an error: the
+ *                       Loop CONTINUES the round loop (bounded by HARD_ROUND_LIMIT / the gate's maxTurns).
+ *   null                pass-through: `end_turn` / `stop_sequence` / `tool_use` / an unrecognized value /
+ *                       absent. The Loop's existing tool-exec / final-answer logic runs unchanged.
+ *
+ * NB: `tool_use` is already derived by {@link normalizeStopReason} from what the round carried, so it
+ * needs no row here — a round that stopped to call a complete tool passes through to tool execution.
+ */
+const TERMINAL_ACTIONS = /** @type {Record<string, 'truncated'|'refusal'|'context_exceeded'|'resume'>} */ ({
+  max_tokens: 'truncated',
+  refusal: 'refusal',
+  context_exceeded: 'context_exceeded',
+  pause_turn: 'resume',
+});
+/**
+ * @param {string|null|undefined} stopReason - a NEUTRAL value (post-{@link normalizeStopReason}).
+ * @returns {'truncated'|'refusal'|'context_exceeded'|'resume'|null}
+ */
+function classifyStopReason(stopReason) {
+  if (typeof stopReason !== 'string') return null;
+  // Own-property only: `normalizeStopReason` passes an unrecognized value through verbatim, so a
+  // provider/proxy emitting stop_reason:'toString'/'constructor'/etc. would otherwise resolve to an
+  // inherited Object.prototype function (truthy) and be mistaken for a terminal action.
+  return Object.prototype.hasOwnProperty.call(TERMINAL_ACTIONS, stopReason)
+    ? TERMINAL_ACTIONS[stopReason]
+    : null;
+}
+
+module.exports = { normalizeStopReason, isTruncated, classifyStopReason };

package/src/recurse-retrieval.d.ts

@@ -143,7 +143,7 @@ export function buildScanTool(corpus: Slice[] | (() => Promise<Slice[]>), opts:
 /**
  * Build a SCAN slice-source backed by a litectx-RESIDENT corpus (facts/episodes the agent already accrued) —
  * the §10-step-7 deferral un-blocked by litectx 0.26's `enumerate` verb (spec:
- * docs/01-product/litectx-enumerate-spec.md). Returns the generic async slice-source recurse's scan reads: a
+ * docs/01-product/prd.md). Returns the generic async slice-source recurse's scan reads: a
  * `() => Promise<Slice[]>` that pages through EVERY row of `kind` via `enumerate` (exhaustive — the rank-free
  * read `recall` structurally cannot do) and maps each to `{id: item.path, text: item.body}`. recurse stays
  * litectx-agnostic: it depends on this source SHAPE, never on litectx (same stance as `remember`'s Store

package/src/recurse-retrieval.js

@@ -16,7 +16,7 @@
 //
 // THE CORPUS FOR SCAN IS A GENERIC ARRAY SLICE-SOURCE (`opts.corpus`), NOT litectx: litectx has no exhaustive,
 // rank-free enumerate verb today (every read is FTS-gated). The "corpus that already LIVES in litectx" case
-// waits on the litectx `enumerate` verb (docs/01-product/litectx-enumerate-spec.md) and drops in behind this
+// waits on the litectx `enumerate` verb (docs/01-product/prd.md) and drops in behind this
 // same slice-source socket with ZERO recurse changes — the same backend-agnostic stance as `remember`'s Store
 // socket. Composes AROUND a Loop; NEVER imported by loop.js.
 
@@ -326,7 +326,7 @@ const ENUM_PAGE = 200;
 /**
  * Build a SCAN slice-source backed by a litectx-RESIDENT corpus (facts/episodes the agent already accrued) —
  * the §10-step-7 deferral un-blocked by litectx 0.26's `enumerate` verb (spec:
- * docs/01-product/litectx-enumerate-spec.md). Returns the generic async slice-source recurse's scan reads: a
+ * docs/01-product/prd.md). Returns the generic async slice-source recurse's scan reads: a
  * `() => Promise<Slice[]>` that pages through EVERY row of `kind` via `enumerate` (exhaustive — the rank-free
  * read `recall` structurally cannot do) and maps each to `{id: item.path, text: item.body}`. recurse stays
  * litectx-agnostic: it depends on this source SHAPE, never on litectx (same stance as `remember`'s Store

package/src/recurse.js

@@ -708,7 +708,7 @@ async function recurseRefineLeaf(task, ctx, opts, state) {
  * never folded into the count as a zero; a governance HaltError mid-scan → clean incomplete.
  *
  * The corpus is the generic array slice-source `opts.corpus`. Absent it, scan has nothing to read — litectx's
- * resident-corpus enumerate path is deferred (docs/01-product/litectx-enumerate-spec.md) — so we return an
+ * resident-corpus enumerate path is deferred (docs/01-product/prd.md) — so we return an
  * honest incomplete, never a fabricated zero.
  * @param {string} task
  * @param {RecurseCtx} ctx

package/tools/shell.d.ts

@@ -5,6 +5,7 @@ declare namespace _exports {
     export { createShellTools };
     export { _grepCore };
     export { writeFile as _writeFile };
+    export { editFile as _editFile };
 }
 export = _exports;
 type GrepArgs = {
@@ -97,3 +98,41 @@ declare function writeFile({ path: rawPath, content, append, maxBytes }: {
     append?: boolean;
     maxBytes?: number;
 }): Promise<string>;
+/**
+ * Anchored exact-string replace (BA-13) — the surgical counterpart to the whole-file `shell_write`.
+ * Changing one line of an 800-line file with `shell_write` forces the model to EMIT all 800 lines as
+ * tool-call JSON: an output-token tax ∝ file size (output is the expensive token class), paid on every
+ * revision, and the maximal broken-tree surface (a truncated rewrite mangles the 799 lines it never meant
+ * to touch — the BA-4/BA-6 truncation class). `shell_edit` emits only the anchor and its replacement.
+ *
+ * TWO error classes, deliberately split:
+ *   - ANCHOR failures (`oldText` matches 0 or 2+ times) RETURN a refusal string as a normal tool RESULT —
+ *     the loop continues and the model re-anchors, and the refusal names the count so the retry is a DISTINCT
+ *     call. (Tradeoff, chosen with eyes open: a result does NOT feed the Loop's `maxIdenticalToolErrors` spin
+ *     guard, so a model that repeats the byte-identical wrong anchor is bounded only by maxTurns/budget, not
+ *     short-circuited. A widened anchor is a different call and recovers naturally; the exact-repeat spin is
+ *     the rare degenerate case. This matches the ask's "refusal, not a throw" contract.)
+ *   - fs-layer errors (missing file, a directory) and BA-4 param-guard violations THROW at the tool boundary.
+ *
+ * BA-4 param guards (guarded from birth this time — cf. `shell_write` zeroing files on an absent arg):
+ * `oldText` a required NON-EMPTY string, `newText` a required string — both THROW when absent/wrong-type (an
+ * absent param is the truncated-call signature, never a silent default). Explicit `newText:""` is a legal
+ * deletion; an absent `newText` is not.
+ *
+ * ATOMIC: read → splice in memory → write a sibling temp (same filesystem, so `rename` is atomic) carrying
+ * the original's mode → rename over the original. Any throw before the rename leaves the original
+ * byte-identical and cleans the temp up, so a reader never sees a partial file, and an edit can't silently
+ * drop the executable bit.
+ *
+ * LITERAL splice, NOT `String.replace`: `.replace(oldText, newText)` interprets `$&`/`$1`/`` $` `` patterns in
+ * `newText` and would corrupt any edit whose replacement contains a `$`. We index + slice, so every byte of
+ * `newText` lands verbatim.
+ * @param {{path: string, oldText: string, newText: string, maxBytes?: number}} args
+ * @returns {Promise<string>}
+ */
+declare function editFile({ path: rawPath, oldText, newText, maxBytes }: {
+    path: string;
+    oldText: string;
+    newText: string;
+    maxBytes?: number;
+}): Promise<string>;

package/tools/shell.js

@@ -7,6 +7,7 @@
  *   shell_read  — read a file or list a directory
  *   shell_grep  — regex search across files (JS regex, no grep/rg/findstr)
  *   shell_write — write/overwrite (or append to) a file, creating parent dirs (no shell)
+ *   shell_edit  — anchored exact-string replace: change one span without rewriting the whole file
  *   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
  *
@@ -16,11 +17,13 @@
  * 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).
+ * To gate `shell_write`/`shell_edit` 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_edit` → `{ type:'edit', path }`, `shell_read`/`shell_grep`
+ * → `{ type:'read', path }`, `shell_run`/`shell_exec` → `{ type:'bash', cmd }`). bareguard gates `edit` by
+ * `fs.writeScope` identically to `write` (its FS primitive's `FS_TYPES` includes `edit`), so a consumer that
+ * fences `write` gets `edit` fenced by the same scope with ZERO extra config. A write/edit 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
@@ -33,6 +36,7 @@
 
 const fs = require('node:fs/promises');
 const path = require('node:path');
+const crypto = require('node:crypto');
 const { exec, execFile } = require('node:child_process');
 const { Worker } = require('node:worker_threads');
 
@@ -127,6 +131,101 @@ async function writeFile({ path: rawPath, content, append = false, maxBytes }) {
   return `${append ? 'appended' : 'wrote'} ${bytes} bytes to ${resolved}`;
 }
 
+/**
+ * Anchored exact-string replace (BA-13) — the surgical counterpart to the whole-file `shell_write`.
+ * Changing one line of an 800-line file with `shell_write` forces the model to EMIT all 800 lines as
+ * tool-call JSON: an output-token tax ∝ file size (output is the expensive token class), paid on every
+ * revision, and the maximal broken-tree surface (a truncated rewrite mangles the 799 lines it never meant
+ * to touch — the BA-4/BA-6 truncation class). `shell_edit` emits only the anchor and its replacement.
+ *
+ * TWO error classes, deliberately split:
+ *   - ANCHOR failures (`oldText` matches 0 or 2+ times) RETURN a refusal string as a normal tool RESULT —
+ *     the loop continues and the model re-anchors, and the refusal names the count so the retry is a DISTINCT
+ *     call. (Tradeoff, chosen with eyes open: a result does NOT feed the Loop's `maxIdenticalToolErrors` spin
+ *     guard, so a model that repeats the byte-identical wrong anchor is bounded only by maxTurns/budget, not
+ *     short-circuited. A widened anchor is a different call and recovers naturally; the exact-repeat spin is
+ *     the rare degenerate case. This matches the ask's "refusal, not a throw" contract.)
+ *   - fs-layer errors (missing file, a directory) and BA-4 param-guard violations THROW at the tool boundary.
+ *
+ * BA-4 param guards (guarded from birth this time — cf. `shell_write` zeroing files on an absent arg):
+ * `oldText` a required NON-EMPTY string, `newText` a required string — both THROW when absent/wrong-type (an
+ * absent param is the truncated-call signature, never a silent default). Explicit `newText:""` is a legal
+ * deletion; an absent `newText` is not.
+ *
+ * ATOMIC: read → splice in memory → write a sibling temp (same filesystem, so `rename` is atomic) carrying
+ * the original's mode → rename over the original. Any throw before the rename leaves the original
+ * byte-identical and cleans the temp up, so a reader never sees a partial file, and an edit can't silently
+ * drop the executable bit.
+ *
+ * LITERAL splice, NOT `String.replace`: `.replace(oldText, newText)` interprets `$&`/`$1`/`` $` `` patterns in
+ * `newText` and would corrupt any edit whose replacement contains a `$`. We index + slice, so every byte of
+ * `newText` lands verbatim.
+ * @param {{path: string, oldText: string, newText: string, maxBytes?: number}} args
+ * @returns {Promise<string>}
+ */
+async function editFile({ path: rawPath, oldText, newText, maxBytes }) {
+  if (typeof rawPath !== 'string' || rawPath.length === 0) {
+    throw new Error('shell_edit requires a non-empty "path" string');
+  }
+  if (typeof oldText !== 'string' || oldText.length === 0) {
+    throw new Error(
+      'shell_edit requires a non-empty "oldText" string to anchor the edit — refusing to edit, the file is unchanged. '
+      + `Got ${oldText === undefined ? 'no oldText argument' : oldText === '' ? 'an empty string' : `oldText of type ${oldText === null ? 'null' : typeof oldText}`}.`,
+    );
+  }
+  if (typeof newText !== 'string') {
+    throw new Error(
+      'shell_edit requires a "newText" string (pass newText:"" to delete the anchored text) — refusing to edit, the file is unchanged. '
+      + `Got ${newText === undefined ? 'no newText argument' : `newText of type ${newText === null ? 'null' : typeof newText}`}`
+      + '. If your output was cut short, retry with the full newText.',
+    );
+  }
+
+  const resolved = path.resolve(expandHome(rawPath));
+  // fs-layer errors (ENOENT for a missing file, EISDIR for a directory) throw — same surface as shell_read.
+  const content = await fs.readFile(resolved, 'utf8');
+
+  // Literal, non-overlapping occurrence count (split on a string does no regex interpretation).
+  const occurrences = content.split(oldText).length - 1;
+  if (occurrences === 0) {
+    return `shell_edit: oldText not found in ${resolved} — no change made. Quote the exact text to replace `
+      + `(check whitespace and indentation), or read the file to re-anchor.`;
+  }
+  if (occurrences > 1) {
+    return `shell_edit: oldText occurs ${occurrences}× in ${resolved} — the anchor must match exactly once. `
+      + `Widen it with surrounding lines so it is unique. No change made.`;
+  }
+
+  const idx = content.indexOf(oldText);
+  const patched = content.slice(0, idx) + newText + content.slice(idx + oldText.length);
+
+  const cap = maxBytes || DEFAULT_WRITE_MAX_BYTES;
+  const bytes = Buffer.byteLength(patched, 'utf8');
+  if (bytes > cap) {
+    throw new Error(`shell_edit result is ${bytes} bytes, over the ${cap}-byte cap (pass maxBytes to raise it)`);
+  }
+
+  // Atomic replace: a sibling temp (same dir → same filesystem → rename is atomic) with the original's mode.
+  const stat = await fs.stat(resolved);
+  const tmp = `${resolved}.shell_edit-${crypto.randomBytes(9).toString('hex')}.tmp`;
+  try {
+    // flag 'wx' (O_CREAT|O_EXCL) — never follow or clobber a pre-planted file/symlink at the temp path; a
+    // colliding name fails the write instead. Create owner-only (0o600) so the patched body — which may hold
+    // a secret from a sensitive source file — is never briefly world-readable in the window before chmod sets
+    // the original's real mode. (This temp pattern is new to shell_edit, so it carries its own hardening.)
+    await fs.writeFile(tmp, patched, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+    await fs.chmod(tmp, stat.mode & 0o777);
+    await fs.rename(tmp, resolved);
+  } catch (err) {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    throw err;
+  }
+
+  const removed = oldText.split('\n').length - 1;
+  const added = newText.split('\n').length - 1;
+  return `edited ${resolved}: 1 replacement (-${removed}/+${added} lines)`;
+}
+
 // Probe the first 1KB for NUL bytes to skip binary files in grep walks.
 /** @param {string} filePath */
 async function isProbablyText(filePath) {
@@ -453,6 +552,30 @@ function createShellTools() {
       execute: async (/** @type {{path: string, content?: string, append?: boolean, maxBytes?: number}} */ args) =>
         writeFile(/** @type {any} */ (args)),
     },
+    {
+      name: 'shell_edit',
+      description: 'Replace an exact, unique text span in a file — the surgical alternative to shell_write, which ' +
+        'rewrites the ENTIRE file. Give oldText (the exact text to replace — it must occur EXACTLY ONCE, so quote ' +
+        'enough surrounding lines to be unique) and newText (its replacement; pass "" to delete). Matched literally ' +
+        '(no regex; whitespace and indentation are significant). Returns a compact "edited <path>: 1 replacement" ' +
+        'receipt, never the file body. If oldText matches 0 or 2+ times the file is left unchanged and the reason is ' +
+        'returned so you can re-anchor. The file must already exist. No shell — gate by path with an fs.writeScope ' +
+        'policy (translate to {type:"edit"}).',
+      parameters: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'File to edit. ~ expands to home. The file must already exist.' },
+          oldText: { type: 'string', description: 'Exact text to find — must occur exactly once. Quote surrounding lines to disambiguate. Matched literally (no regex); whitespace and indentation are significant.' },
+          newText: { type: 'string', description: 'Replacement text, inserted verbatim (a literal splice — $ is not special). Pass "" to delete the anchored text. Required — a call without it is REJECTED, not treated as a deletion.' },
+          maxBytes: { type: 'integer', description: 'Reject if the resulting file would exceed this many bytes (default 5242880).' },
+        },
+        required: ['path', 'oldText', 'newText'],
+      },
+      // The args are model-authored and UNTRUSTED — oldText/newText may be absent (an output-token-capped
+      // generation), so the boundary type stays loose and editFile enforces the BA-4 contract at runtime.
+      execute: async (/** @type {{path: string, oldText?: string, newText?: string, maxBytes?: number}} */ args) =>
+        editFile(/** @type {any} */ (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.',
@@ -493,4 +616,4 @@ function createShellTools() {
   return { tools };
 }
 
-module.exports = { createShellTools, _grepCore, _writeFile: writeFile };
+module.exports = { createShellTools, _grepCore, _writeFile: writeFile, _editFile: editFile };