bareloop 0.5.1 → 0.6.0

package/src/tools.js

@@ -0,0 +1,611 @@
+// The worker tool menu — the machinery a plan step's worker is built from: the
+// verb→tool map, the litectx retrieval tools, the gate's action translator, and
+// the personas/strategy lines that ship with a granted verb (F19: capability
+// without strategy is inert).
+//
+// This file WAS interpret.js, the config-v1 interpreter. That path — the
+// operator-authored steps[] chain and the drafted workflow config — was deleted
+// 2026-07-26 (PRD v1.32); what remains is the tool machinery the plan flow
+// imports, kept because it is the worker's surface, not the dead path's.
+//
+// One trap encoded here, paid for in adaptlearn: `onLlmResult` is a Loop
+// CONSTRUCTOR option — passed to run() it is silently ignored and the budget
+// axis goes blind (F3). The consumer (planrun) wires it at construction.
+
+import { createRequire } from 'node:module';
+import { join, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
+
+const require = createRequire(import.meta.url);
+
+const { createShellTools } = require('bare-agent/tools');
+// litectx's rank-tiered render — a free function, not a ctx method (its contract's
+// own recipe: the caller slices the chunk body, compress renders the signature tier)
+const { compress: compressNode } = require('litectx');
+
+import { extractArtifact, priceOf } from './text.js';
+// The isolate verbs write MODEL-AUTHORED text into `<workdir>/.litectx` — a file
+// inside the tree that outlives the step and reads back through ctx_recall. That is
+// the hard line's own sentence ("a record that captures a key captures it forever"),
+// so the scrub is IMPORTED, never injected: an injected redactor is one a future
+// caller can forget to pass, and this leak has to be inexpressible, not optional.
+// Same ONE inventory the spine channel and the close output ride through.
+import { redactSecrets } from './validate.js';
+
+/** @typedef {{body?: string|null, text?: string|null}} RecallHit litectx recall hit — body present only with `{body: true}` */
+
+const PERSONA = 'You are a senior engineer. Reply with ONLY the complete contents of the requested JavaScript file — no markdown fences, no commentary. ESM.';
+// The tool persona states the LOOP CONTRACT (F16): the worker is one attempt inside
+// `while close-red and under-cap`, not a one-shot. Without knowing that, a model does
+// the rational one-shot thing — read everything, be certain, then act — and the real
+// run spent its ENTIRE budget on 12 rounds of reading without one write, never once
+// reaching the close. Every round re-pays for every earlier tool result, so reads
+// compound: that run's context grew 2k → 121k tokens and its last round cost $0.25.
+// Telling the worker it will be re-run with the close's verdict makes an early,
+// cheap, wrong attempt the rational move — which is exactly what the loop wants.
+export const PERSONA_TOOLS = 'You are a senior engineer working in a repository through file tools. '
+  + 'ALWAYS use absolute paths — relative paths resolve against the process, not the repository, and will be denied. '
+  + 'You are ONE attempt inside an automated loop: when you finish, a test suite runs and, if it still fails, you are called again with its output. '
+  + 'So do not try to be certain before acting. Read only what you need to form your best hypothesis, make the change with the write tool, and stop. '
+  + 'A wrong cheap attempt is corrected by the next round; exhaustive reading is not — every file you read is re-sent on every later round and the run has a hard budget it can exhaust before you ever write. '
+  + 'Make the required changes with the write tool, then reply with a short summary of what you changed. Never put file contents in your reply.';
+
+// The retrieval verbs only pay if the worker reaches for them INSTEAD of paging a file.
+// F18 measured the failure they exist to fix: the worker read one 117 KB file NINE times
+// and dragged 1.37 MB of source through context to reach an 8-line function. The tool
+// descriptions carry the mechanics; the persona has to carry the STRATEGY, or a model
+// with a familiar `read` and an unfamiliar `recall` will simply keep reading.
+// (Module-level + exported since Layer 2: the plan-step worker shares the SAME
+// personas/strategies — two spellings of the loop contract would drift, F16.)
+export const RETRIEVAL_STRATEGY = '\nYou also have a repository index. To read a function, do NOT read its whole file: '
+  + 'call ctx_recall with the function name to get a pointer, then ctx_get with that pointer to read that function alone '
+  + '(it comes with its doc-comment, which states what the function is SUPPOSED to do — compare it against what the code does). '
+  + 'Reserve shell_read for whole files that are genuinely small, and for files you cannot name a symbol in yet. '
+  + 'Search only finds what you can NAME: a failing test names the symptom, not the cause, so read the failing test first, '
+  + 'see which function it calls, and recall THAT.';
+// BA-13: like retrieval, the edit verb only pays if the worker reaches for it INSTEAD
+// of a whole-file rewrite. F31 measured the default: 4 of 5 big-file whole-writes
+// broke the tree, and every one was a rewrite to change ~one line. The tool
+// description carries the mechanics; the persona carries the strategy.
+export const EDIT_STRATEGY = '\nPrefer the edit tool over whole-file writes: quote the EXACT text to change (it must match exactly once) and its replacement. '
+  + 'Rewriting a whole file to change one line is how trees get broken and budgets get burned — reserve the write tool for genuinely new files.';
+
+// ---- tool mode (2b): the spec-side grant menu mapped to the underlying tools ----
+// read/grep/write are bare-agent's shell tools; the ctx_* verbs are litectx's,
+// composed from the SAME LiteCtx the retrieval pair already uses. P (design
+// record 2026-07-28) widened this from six to the full four-component catalog —
+// every verb an EXISTING implementation (menu-is-inventory, hamr's #3), grouped:
+//   write    write · edit                                  (tree, writeScope fence)
+//   select   read · grep · recall · get · impact · related · recent   (read-only)
+//   compress compress · peek                                          (read-only)
+//   isolate  stash · remember · forget          (store-write class, own action types)
+export const TOOL_BY_VERB = Object.freeze({
+  read: 'shell_read', grep: 'shell_grep', write: 'shell_write', edit: 'shell_edit',
+  recall: 'ctx_recall', get: 'ctx_get',
+  impact: 'ctx_impact', related: 'ctx_related', recent: 'ctx_recent',
+  compress: 'ctx_compress', peek: 'ctx_peek',
+  stash: 'ctx_stash', remember: 'ctx_remember', forget: 'ctx_forget',
+});
+// L1 — the isolate verbs are the one worker surface that writes UNGATED bytes: the
+// writeScope fence judges the tree, and a store write never passes it, so without a
+// bound a worker can grow the on-disk store for as many rounds as the wallet funds.
+// 64KB (hamr's threshold) stops degenerate store-dumping, not legitimate use:
+// observed notes run hundreds of bytes to a few KB, and a >64KB "note" is a FILE —
+// files belong in the tree, behind the fence.
+// The residual, named honestly: this bounds ONE PAYLOAD, not the store. litectx
+// upserts on the same key, so re-stashing an id is idempotent — but N distinct ids
+// are N separate 64KB payloads, and the aggregate stays unbounded. An aggregate cap
+// (per-run store bytes, or a key count) is a THRESHOLD, and thresholds are hamr's
+// call — this is the known limit, not a defect to fix by picking a number here.
+export const ISOLATE_MAX_BYTES = 65536;
+export const CTX_TOOLS = Object.freeze(['ctx_recall', 'ctx_get', 'ctx_impact', 'ctx_related', 'ctx_recent', 'ctx_compress', 'ctx_peek', 'ctx_stash', 'ctx_remember', 'ctx_forget']);
+
+// F19 applied per component: a granted verb ships WITH the line that says WHEN to
+// reach for it, or the model keeps using the familiar tool. planrun composes the
+// strategies whose component has at least one granted verb.
+export const COMPONENT_STRATEGIES = Object.freeze({
+  select: '\nBefore changing a function, ask what depends on it: ctx_impact(<symbol>) names its callers and importers, '
+    + 'ctx_related(<path>) walks the import graph around a file, and ctx_recent lists recently-edited symbols. '
+    + 'A fix that type-checks but breaks a dependent you never looked at is the failure these exist to prevent.',
+  compress: '\nWhen you only need what a function IS rather than how it works, ctx_compress(<path>,<symbol>) returns its '
+    + 'signature and doc without the body — far cheaper than reading it. ctx_peek(<id>) shows the head and tail of '
+    + 'something you stashed without paying for its bytes again.',
+  isolate: '\nYour context is re-sent and re-billed every round. Park bulky intermediate results with ctx_stash(<id>,<text>) '
+    + 'and check them later with ctx_peek(<id>) instead of carrying them in conversation. Record a durable conclusion '
+    + 'with ctx_remember(<id>,<text>) so a later step can ctx_recall it; ctx_forget(<id>) retracts a note that proved wrong.',
+});
+
+// ---- F19, INVERTED: a strategy must never name a tool the grant lacks --------
+// The paragraphs above are the FULL-COMPONENT prose, and they were emitted per
+// COMPONENT: any one isolate verb lit a paragraph naming `ctx_peek` (a COMPRESS
+// verb), either retrieval verb lit the two-step `ctx_recall` → `ctx_get`
+// prescription, any one select verb named all three. So a worker granted `stash`
+// alone was told to call a tool that was not on its menu — the inversion of F19,
+// and worse than silence: the model spends rounds reaching for a menu entry that
+// does not exist. planrun states the law for the select case ("a worker granted
+// only `impact` must not be steered to tools it lacks"); `EDIT_STRATEGY`'s
+// `granted.includes('edit')` is the house pattern. This assembles the same prose
+// SENTENCE BY SENTENCE, each gated on its own verb.
+//
+// The full-menu text is unchanged BY TEST, not by comment: `strategyFor(TOOL_MENU)`
+// is asserted byte-identical to the concatenation of the paragraphs above, so a
+// partial grant can only ever see LESS, never different.
+
+/** `a`, `a, and b`, `a, b, and c` — the clause grammar the select paragraph uses. */
+const andJoin = (/** @type {string[]} */ xs) =>
+  xs.length < 2 ? (xs[0] ?? '') : `${xs.slice(0, -1).join(', ')}, and ${xs.at(-1)}`;
+
+/** the select paragraph's per-verb clauses, in the order the paragraph reads them */
+const SELECT_CLAUSES = /** @type {[string, string][]} */ ([
+  ['impact', 'ctx_impact(<symbol>) names its callers and importers'],
+  ['related', 'ctx_related(<path>) walks the import graph around a file'],
+  ['recent', 'ctx_recent lists recently-edited symbols'],
+]);
+
+/**
+ * The strategy suffix for ONE worker's grant: every sentence that survives names
+ * only tools this worker can actually call. Reproduces the exported paragraphs
+ * exactly on a full grant.
+ * @param {string[]} granted the step's granted VERBS (the menu IS the grant, 2b)
+ * @returns {string} the system-prompt suffix, '' when nothing is granted
+ */
+export function strategyFor(granted) {
+  const g = (/** @type {string} */ v) => granted.includes(v);
+  /** @type {string[]} */
+  const out = [];
+
+  if (g('edit')) out.push(EDIT_STRATEGY);
+
+  // retrieval — the two-step prescription needs BOTH verbs; each alone gets the
+  // half it can run. The `shell_read` sentence rides only with a granted `read`.
+  if (g('recall') || g('get')) {
+    const s = ['You also have a repository index.'];
+    if (g('recall') && g('get')) s.push('To read a function, do NOT read its whole file: call ctx_recall with the function name to get a pointer, then ctx_get with that pointer to read that function alone (it comes with its doc-comment, which states what the function is SUPPOSED to do — compare it against what the code does).');
+    else if (g('recall')) s.push('To find a function, do NOT page through whole files: call ctx_recall with the function name and it names the file and lines that define it.');
+    else s.push('To read a function, do NOT read its whole file: call ctx_get with its path and line range to read that function alone (it comes with its doc-comment, which states what the function is SUPPOSED to do — compare it against what the code does).');
+    if (g('read')) s.push('Reserve shell_read for whole files that are genuinely small, and for files you cannot name a symbol in yet.');
+    if (g('recall')) s.push('Search only finds what you can NAME: a failing test names the symptom, not the cause, so read the failing test first, see which function it calls, and recall THAT.');
+    out.push('\n' + s.join(' '));
+  }
+
+  // select — one clause per granted verb, joined with the paragraph's own grammar
+  const clauses = SELECT_CLAUSES.filter(([v]) => g(v)).map(([, t]) => t);
+  if (clauses.length) {
+    out.push(`\nBefore changing a function, ask what depends on it: ${andJoin(clauses)}. `
+      + 'A fix that type-checks but breaks a dependent you never looked at is the failure these exist to prevent.');
+  }
+
+  // compress — two independent sentences, one per verb
+  const cs = [];
+  if (g('compress')) cs.push('When you only need what a function IS rather than how it works, ctx_compress(<path>,<symbol>) returns its signature and doc without the body — far cheaper than reading it.');
+  if (g('peek')) cs.push('ctx_peek(<id>) shows the head and tail of something you stashed without paying for its bytes again.');
+  if (cs.length) out.push('\n' + cs.join(' '));
+
+  // isolate — the stash advice drops its ctx_peek half without `peek`, and the
+  // durable-note sentence drops its ctx_recall half without `recall` (both are
+  // OTHER components' verbs, which is exactly how the paragraph over-reached)
+  const is = [];
+  if (g('stash')) {
+    is.push(g('peek')
+      ? 'Park bulky intermediate results with ctx_stash(<id>,<text>) and check them later with ctx_peek(<id>) instead of carrying them in conversation.'
+      : 'Park bulky intermediate results with ctx_stash(<id>,<text>) instead of carrying them in conversation.');
+  }
+  const durable = [];
+  if (g('remember')) {
+    durable.push(g('recall')
+      ? 'Record a durable conclusion with ctx_remember(<id>,<text>) so a later step can ctx_recall it'
+      : 'Record a durable conclusion with ctx_remember(<id>,<text>) so a later step can find it');
+  }
+  if (g('forget')) durable.push('ctx_forget(<id>) retracts a note that proved wrong');
+  if (durable.length) is.push(durable.join('; ') + '.');
+  if (is.length) out.push('\nYour context is re-sent and re-billed every round. ' + is.join(' '));
+
+  return out.join('');
+}
+
+// L8 — ONE line space, named in the contract instead of renumbered (validated
+// 2026-07-30 against a real index, not read off the source). Every line number
+// litectx hands back is a 0-BASED index: a chunk's `startLine`/`endLine`
+// (chunker.js: "0-based, inclusive"), impact's `defs[].startLine`, and impact's
+// `callers[].line`. So a symbol whose doc-comment sits on editor line 5 prints
+// as 4 — the off-by-one a worker would hit if it cross-referenced an editor.
+// The tempting fix (render impact 1-based, since its numbers are display-only)
+// was REFUTED by measurement: impact's def range dereferences through ctx_get
+// verbatim, and ctx_recall prints the SAME number for the SAME chunk. They are
+// one interchangeable handle space, and ctx_get refuses anything that is not a
+// chunk boundary — so a 1-based impact would make two tools print two numbers
+// for one chunk and turn a clean refusal into a guessing game. Consistency is
+// the resolution; the description is where the worker learns the space.
+const LINE_SPACE = 'Line numbers here are 0-BASED index positions from the repository index — one lower than the line an editor shows. '
+  + 'Copy them between ctx_recall, ctx_get and ctx_impact as-is; never adjust them, and never quote one as an editor line.';
+
+/**
+ * The retrieval pair (F19). `shell_read` cannot seek — it starts at byte zero — so a
+ * pointer at a symbol was inert and the worker paged whole files to reach one function.
+ * `ctx_recall` hands back a POINTER (no body: a search index returns pointers, and bodies
+ * on every hit rebuild the bloat — measured, a 5-hit recall dumps ~15k tokens unbidden);
+ * `ctx_get` trades that pointer for ONE chunk. A chunk starts at its doc-comment, so the
+ * body arrives WITH the docstring that says what it was supposed to do.
+ * @param {any} lc the run's LiteCtx (rooted at workdir)
+ * @param {string} workdir
+ * @param {(type: string, data: object) => void} emit the spine — a retrieval verb whose
+ *   RESULT is invisible cannot be judged: a `ctx_get` that silently reds (stale pointer,
+ *   bad range) looks exactly like one that worked, and the worker's fallback to a
+ *   whole-file read looks like a free choice instead of a forced one.
+ */
+export function createCtxTools(lc, workdir, emit) {
+  // ctx_get's failure contract, generalised to the palette (review 2026-07-31).
+  // `emit` exists in this file because a verb whose RESULT is invisible cannot be
+  // judged — and a THROWN call is the most invisible result there is: it looks
+  // exactly like a verb that was never reached, so the worker's fall-back to a
+  // whole-file read reads as a free choice instead of a forced one (the F18
+  // blindness rule). The worker gets a refusal RESULT naming the cause, never a
+  // throw (L1: throws stay reserved for the BA-4 param-guard class), so a locked
+  // store or a corrupt index costs one round instead of the run.
+  // `fields` reads its args defensively — a field reader that throws would take
+  // the emit down with it, which is the hole this closes.
+  /** @param {string} tool @param {(args: any) => object} fields @param {(args: any) => Promise<string>} fn */
+  const guarded = (tool, fields, fn) => async (/** @type {any} */ args) => {
+    try {
+      return await fn(args);
+    } catch (e) {
+      const detail = String(/** @type {Error} */ (e)?.message || e);
+      emit('ctx-tool', { tool, ...fields(args), outcome: 'error', bytes: 0, detail });
+      return `${tool} failed: ${detail}`;
+    }
+  };
+  return [
+    {
+      name: 'ctx_recall',
+      description: 'Search the repository index for a symbol or phrase. Returns POINTERS (path, symbol, line range) — not code. '
+        + 'Pass a pointer to ctx_get to read that one function. Search finds what you can NAME: it will not find a bug from a failing '
+        + "test's output (the symptom and the cause live in different files) — read the failing test first, then recall the function it calls. "
+        + LINE_SPACE,
+      parameters: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'Symbol name or phrase, e.g. "keywords" or "stopword filter".' },
+          n: { type: 'integer', description: 'Max pointers to return (default 5, max 20).' },
+        },
+        required: ['query'],
+      },
+      execute: async (/** @type {{query: string, n?: number}} */ { query, n }) => {
+        const q = String(query);
+        const cap = Math.min(Math.max(Number(n) || 5, 1), 20);
+        const hits = await lc.recall(q, { kind: 'code', n: cap });
+        // The memory axis rides the same verb (hardening find, 2026-07-30): the
+        // isolate persona promises "remember so a later step can ctx_recall it",
+        // and a recall pinned to kind:'code' made notes write-only through the
+        // tool surface. A note's BODY comes back inline — it is a conclusion,
+        // not a pointer, and there is no worker verb that dereferences a memory
+        // id — capped per note so a bloated note cannot page the context.
+        const notes = await lc.recall(q, { kind: 'fact', n: cap, body: true });
+        const lines = hits.map((/** @type {any} */ h) => (h.chunk
+          ? `${h.path}\t${h.chunk.symbol ?? '(anonymous)'}\t${h.chunk.nodeType}\tlines ${h.chunk.startLine}-${h.chunk.endLine}`
+          : `${h.path}\t(whole file — no chunk)`));
+        for (const h of notes) {
+          const body = typeof h.body === 'string' ? h.body : '';
+          lines.push(`memory\t${h.path}\t${body.length > 400 ? `${body.slice(0, 400)}… [note truncated at 400 chars]` : body}`);
+        }
+        const out = lines.length ? lines.join('\n') : 'no hits';
+        emit('ctx-tool', { tool: 'ctx_recall', query: q, hits: hits.length, notes: notes.length, paths: [...hits, ...notes].map((/** @type {any} */ h) => h.path), bytes: Buffer.byteLength(out) });
+        return out;
+      },
+    },
+    {
+      name: 'ctx_get',
+      description: 'Read ONE function by the line range ctx_recall gave you — code plus its doc-comment, without the rest of the file. '
+        + 'The line range is a HANDLE you copy from ctx_recall, never one you compute: a range that is not a chunk boundary is refused, '
+        + 'and a file edited since it was indexed is refused (re-run ctx_recall for a fresh pointer). '
+        + LINE_SPACE,
+      parameters: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'Repository-relative path, exactly as ctx_recall printed it.' },
+          startLine: { type: 'integer', description: 'From ctx_recall.' },
+          endLine: { type: 'integer', description: 'From ctx_recall.' },
+        },
+        required: ['path', 'startLine', 'endLine'],
+      },
+      execute: async (/** @type {{path: string, startLine: number, endLine: number}} */ { path: p, startLine, endLine }) => {
+        // The path is spelled as recall printed it (repo-relative); the gate judges the
+        // resolved absolute path, exactly as toolAction resolves it. Boundary-aware
+        // prefix (workdir + sep, the line-247 pattern): bare startsWith would garble a
+        // sibling like `${workdir}-backup/x` into `ackup/x` — the gate independently
+        // denies such a path before execute() runs, so this is defense in depth only.
+        const rel = String(p).startsWith(workdir + sep) ? String(p).slice(workdir.length + 1) : String(p);
+        try {
+          const item = lc.get(rel, { startLine: Number(startLine), endLine: Number(endLine) });
+          if (!item?.text) {
+            emit('ctx-tool', { tool: 'ctx_get', path: rel, startLine, endLine, outcome: 'no-chunk', bytes: 0 });
+            return `no chunk at ${startLine}-${endLine} in "${rel}" — copy a line range from ctx_recall, do not compute one`;
+          }
+          emit('ctx-tool', { tool: 'ctx_get', path: rel, startLine, endLine, outcome: 'ok', bytes: Buffer.byteLength(item.text) });
+          return item.text;
+        } catch (e) {
+          // StalePointerError: the file changed after indexing, so these lines now describe
+          // DIFFERENT code. Its message IS the recovery instruction — hand it to the worker.
+          const detail = String(/** @type {Error} */ (e)?.message || e);
+          emit('ctx-tool', { tool: 'ctx_get', path: rel, startLine, endLine, outcome: 'stale', bytes: 0, detail });
+          return `stale pointer: ${detail}`;
+        }
+      },
+    },
+    {
+      name: 'ctx_impact',
+      description: 'Before changing a symbol, see what depends on it: callers, importers, and mention sites across the repository. '
+        + 'Returns a text readout of the blast radius — a fix that compiles but breaks an unseen dependent is what this prevents. '
+        + LINE_SPACE,
+      parameters: {
+        type: 'object',
+        properties: { symbol: { type: 'string', description: 'Function/class/identifier name, e.g. "addNums".' } },
+        required: ['symbol'],
+      },
+      execute: guarded('ctx_impact', (a) => ({ symbol: String(a?.symbol ?? '') }), async (/** @type {{symbol: string}} */ { symbol }) => {
+        const imp = await lc.impact(String(symbol));
+        if (!imp) {
+          emit('ctx-tool', { tool: 'ctx_impact', symbol: String(symbol), outcome: 'unknown-symbol', bytes: 0 });
+          return `no indexed symbol "${symbol}" — check the spelling with ctx_recall first`;
+        }
+        // The readout's real shape, checked against a live index (the POC's note said
+        // "defs/callers/callees are arrays of {path, line}" and was right for two of
+        // the three): defs are {path,startLine,endLine} and callers are {path,line,
+        // symbol} — but CALLEES are bare NAMES (litectx Impact.callees: string[]), so
+        // reading .path/.line off them printed `calls undefined:undefined` on every
+        // symbol that calls anything. Garbage a worker cannot tell from a pointer.
+        // confirmed/mentions are COUNTS; risk is the one-word summary.
+        const lines = [];
+        for (const d of imp.defs ?? []) lines.push(`defined\t${d.path}:${d.startLine}`);
+        for (const c of imp.callers ?? []) lines.push(`called by\t${c.path}:${c.line}${c.symbol ? ` (in ${c.symbol})` : ''}`);
+        for (const c of imp.callees ?? []) lines.push(`calls\t${c}`);
+        lines.push(`risk ${imp.risk} — ${imp.confirmed} confirmed caller(s), ${imp.mentions} mention(s)`);
+        // The hedges are not decoration — they are the other half of the count.
+        // litectx's impact is deliberately asymmetric (over-count safe, under-count
+        // dangerous), so "isolated / low risk" only ever ships HEDGED and `callers`
+        // may be capped; dropping the caveat leaves "risk low — 0 confirmed
+        // caller(s)" reading as a licence to change the symbol freely, which is the
+        // one dangerous act the asymmetry exists to prevent. Empty when litectx
+        // hedged nothing — a header with nothing under it is bytes the worker
+        // re-reads every call.
+        // Frozen BEFORE the caveats: `hits` means impact content (defs, callers,
+        // callees, risk) and keeps that meaning. A caveat qualifies the count, it
+        // is not more of it — reading lines.length after the loop would re-mean a
+        // shipped spine field the day a new line type ships, which is how a field
+        // stops measuring what its readers think it measures.
+        const hits = lines.length;
+        for (const h of imp.hedges ?? []) lines.push(`caveat\t${h}`);
+        const out = lines.join('\n');
+        emit('ctx-tool', { tool: 'ctx_impact', symbol: String(symbol), hits, bytes: Buffer.byteLength(out) });
+        return out;
+      }),
+    },
+    {
+      name: 'ctx_related',
+      description: 'Walk the import graph around one file: what it imports and what imports it (1 hop). '
+        + 'Use before editing a file to know its neighbourhood; use ctx_impact for a specific symbol instead.',
+      parameters: {
+        type: 'object',
+        properties: { path: { type: 'string', description: 'Repository-relative path, e.g. "src/chunker.js".' } },
+        required: ['path'],
+      },
+      execute: guarded('ctx_related', (a) => ({ path: String(a?.path ?? '') }), async (/** @type {{path: string}} */ { path: p }) => {
+        const rel = String(p).startsWith(workdir + sep) ? String(p).slice(workdir.length + 1) : String(p);
+        const r = lc.related(rel, { dir: 'both', hops: 1 });
+        if (!r || !r.items.length) {
+          emit('ctx-tool', { tool: 'ctx_related', path: rel, hits: 0, bytes: 0 });
+          return `no import edges recorded for "${rel}" — the file is isolated or the path is not indexed`;
+        }
+        const out = r.items.map((/** @type {any} */ i) => `${i.via === 'in' ? 'imported by' : 'imports'}\t${i.id}`).join('\n');
+        emit('ctx-tool', { tool: 'ctx_related', path: rel, hits: r.items.length, bytes: Buffer.byteLength(out) });
+        return out;
+      }),
+    },
+    {
+      name: 'ctx_recent',
+      description: 'List recently-edited symbols in this repository, most recent first — where the churn is.',
+      parameters: { type: 'object', properties: {} },
+      execute: guarded('ctx_recent', () => ({}), async () => {
+        const rows = lc.recentActivity() ?? [];
+        const out = rows.length
+          ? rows.map((/** @type {any} */ r) => `${r.id ?? r.symbol}\t${r.kind ?? ''}\tedits ${r.edits ?? '?'}`).join('\n')
+          : 'no recent edit activity recorded';
+        emit('ctx-tool', { tool: 'ctx_recent', hits: rows.length, bytes: Buffer.byteLength(out) });
+        return out;
+      }),
+    },
+    {
+      name: 'ctx_compress',
+      description: 'Read a function\'s SIGNATURE — declaration head plus doc-comment, implementation body elided. '
+        + 'Far cheaper than the body when you only need what it is, not how it works. Give the path and the symbol name.',
+      parameters: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'Repository-relative path.' },
+          symbol: { type: 'string', description: 'The function/class name inside that file.' },
+        },
+        required: ['path', 'symbol'],
+      },
+      execute: guarded('ctx_compress', (a) => ({ path: String(a?.path ?? ''), symbol: String(a?.symbol ?? '') }), async (/** @type {{path: string, symbol: string}} */ { path: p, symbol }) => {
+        const rel = String(p).startsWith(workdir + sep) ? String(p).slice(workdir.length + 1) : String(p);
+        // recall→chunk→slice→compress: the contract's own recipe (compress takes a
+        // body the CALLER slices; recall/nodesForPath give the range, not the text)
+        const node = lc.getNode(rel);
+        const chunk = node?.chunks.find((/** @type {any} */ c) => c.symbol === String(symbol));
+        if (!chunk) {
+          emit('ctx-tool', { tool: 'ctx_compress', path: rel, symbol: String(symbol), outcome: 'no-symbol', bytes: 0 });
+          return `no symbol "${symbol}" in "${rel}" — ctx_recall the name to find where it lives`;
+        }
+        const file = lc.get(rel);
+        if (!file?.text) {
+          emit('ctx-tool', { tool: 'ctx_compress', path: rel, symbol: String(symbol), outcome: 'no-body', bytes: 0 });
+          return `"${rel}" has no readable body in the index`;
+        }
+        const body = file.text.split('\n').slice(chunk.startLine, chunk.endLine + 1).join('\n');
+        const sig = await compressNode({ text: body, format: node.format, symbol: String(symbol) }, { level: 'signature' });
+        emit('ctx-tool', { tool: 'ctx_compress', path: rel, symbol: String(symbol), bytes: Buffer.byteLength(sig), savedBytes: Buffer.byteLength(body) - Buffer.byteLength(sig) });
+        return sig;
+      }),
+    },
+    {
+      name: 'ctx_stash',
+      description: 'Park a payload OUT of your context under a key — it is stored, not lost, and costs nothing per round while parked. '
+        + 'Use for bulky intermediate results (long outputs, gathered evidence) you may need later. Retrieve its head/tail with ctx_peek. '
+        + `A payload over ${ISOLATE_MAX_BYTES} bytes is refused unparked — that size is a file, so write it to the tree instead.`,
+      parameters: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: 'Key to park under, e.g. "step2-tsc-output".' },
+          text: { type: 'string', description: 'The payload to park.' },
+        },
+        required: ['id', 'text'],
+      },
+      execute: guarded('ctx_stash', (a) => ({ id: redactSecrets(a?.id) }), async (/** @type {{id: string, text: string}} */ { id, text }) => {
+        // Scrubbed BEFORE anything else touches it (the hard line): `.litectx` is a
+        // file inside the tree, it outlives the step that wrote it, and ctx_recall
+        // reads notes back inline — an append-only record that captures a key
+        // captures it forever. The KEY goes through the same scrub as the body, and
+        // every id-taking verb scrubs on LOOKUP too, or a stash would be unreachable
+        // by the id the worker actually spelled.
+        const key = redactSecrets(id);
+        const body = redactSecrets(text);
+        // …and the cap is measured on the SCRUBBED payload, because that is the one
+        // that enters the store: a size read off the pre-redaction text would report
+        // bytes that never landed (the F6/blind-instrument class), and the bound
+        // exists to bound the store.
+        const size = Buffer.byteLength(body);
+        // L1: over-cap is a REFUSAL RESULT, never a throw (throws stay reserved for
+        // the BA-4 param-guard class) — the worker is told the size and the limit so
+        // its retry is a DISTINCT call, and the store is left untouched.
+        if (size > ISOLATE_MAX_BYTES) {
+          emit('ctx-tool', { tool: 'ctx_stash', id: key, outcome: 'over-cap', bytes: 0, size });
+          return `ctx_stash: text is ${size} bytes — the limit is ${ISOLATE_MAX_BYTES} bytes per payload. Nothing was parked. `
+            + `Park the part you actually need later, or write the bulk to a file with the write tool and stash its path.`;
+        }
+        lc.stash(key, body);
+        const out = `parked ${size} bytes under "${key}"`;
+        emit('ctx-tool', { tool: 'ctx_stash', id: key, bytes: size });
+        return out;
+      }),
+    },
+    {
+      name: 'ctx_peek',
+      description: 'Look at the head and tail of a stashed payload WITHOUT paying for its full bytes. '
+        + 'The cheap check on something you parked with ctx_stash.',
+      parameters: {
+        type: 'object',
+        properties: { id: { type: 'string', description: 'The key it was stashed under.' } },
+        required: ['id'],
+      },
+      execute: guarded('ctx_peek', (a) => ({ id: redactSecrets(a?.id) }), async (/** @type {{id: string}} */ { id }) => {
+        // the SAME transform ctx_stash keyed with — scrubbing only on write would
+        // strand every payload whose id carried a token
+        const key = redactSecrets(id);
+        const p = lc.peek(key);
+        if (!p) {
+          emit('ctx-tool', { tool: 'ctx_peek', id: key, outcome: 'no-key', bytes: 0 });
+          return `nothing stashed under "${key}"`;
+        }
+        const out = `stash "${key}": ${p.bytes} bytes\nhead: ${p.head}\ntail: ${p.tail}`;
+        emit('ctx-tool', { tool: 'ctx_peek', id: key, bytes: Buffer.byteLength(out) });
+        return out;
+      }),
+    },
+    {
+      name: 'ctx_remember',
+      description: 'Record a durable note under a key — it survives this step and a later step can find it with ctx_recall. '
+        + 'Use for conclusions worth keeping (root causes, decisions), never for bulk data (use ctx_stash for that). '
+        + `A note over ${ISOLATE_MAX_BYTES} bytes is refused unrecorded — record the conclusion, not the evidence.`,
+      parameters: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: 'Note key, e.g. "root-cause".' },
+          text: { type: 'string', description: 'The note.' },
+        },
+        required: ['id', 'text'],
+      },
+      execute: guarded('ctx_remember', (a) => ({ id: redactSecrets(a?.id) }), async (/** @type {{id: string, text: string}} */ { id, text }) => {
+        // scrubbed at the same seam as ctx_stash, and a note needs it harder: its
+        // body rides back INLINE through ctx_recall, so a captured token would be
+        // re-read into the context of every later step that searches near it
+        const key = redactSecrets(id);
+        const body = redactSecrets(text);
+        const size = Buffer.byteLength(body);
+        // L1, same bound as ctx_stash — and a note is the one that most needs it: a
+        // note's body rides back inline through ctx_recall, so an unbounded store
+        // write is also an unbounded future context read.
+        if (size > ISOLATE_MAX_BYTES) {
+          emit('ctx-tool', { tool: 'ctx_remember', id: key, outcome: 'over-cap', bytes: 0, size });
+          return `ctx_remember: text is ${size} bytes — the limit is ${ISOLATE_MAX_BYTES} bytes per note. Nothing was recorded. `
+            + `A note is a CONCLUSION, not a file: record what you concluded and leave the evidence it came from in the tree.`;
+        }
+        await lc.remember(key, body, { kind: 'fact', by: 'agent' });
+        emit('ctx-tool', { tool: 'ctx_remember', id: key, bytes: size });
+        return `remembered "${key}"`;
+      }),
+    },
+    {
+      name: 'ctx_forget',
+      description: 'Retract a note recorded with ctx_remember — use when a conclusion proved wrong.',
+      parameters: {
+        type: 'object',
+        properties: { id: { type: 'string', description: 'The note key to retract.' } },
+        required: ['id'],
+      },
+      execute: guarded('ctx_forget', (a) => ({ id: redactSecrets(a?.id) }), async (/** @type {{id: string}} */ { id }) => {
+        // a retraction addresses the key ctx_remember actually wrote (scrubbed), not
+        // the one the worker still holds in its context — same transform, both doors
+        const key = redactSecrets(id);
+        const n = lc.forget(key);
+        emit('ctx-tool', { tool: 'ctx_forget', id: key, removed: n });
+        return `forgot ${n} note(s) under "${key}"`;
+      }),
+    },
+  ];
+}
+
+// The load-bearing containment line (2b POC, scenario B): bare-agent's built-in
+// tools are deliberately ungated and their action type is their own NAME, which
+// never trips bareguard's fs primitives — this translator maps them onto
+// write/read actions so the SAME fence text mode enforces manually governs
+// every tool call. Paths resolve exactly as the tools resolve them
+// (path.resolve(expandHome(p)), POC scenario F) so the gate judges the same
+// file the tool would touch; a relative spelling resolves against the process
+// cwd and reds at the fence, and the deny reason teaches the retry.
+/** @param {string} p */
+const expandHome = (p) => (p === '~' || p.startsWith('~/')) ? join(homedir(), p.slice(1)) : p;
+/** @param {string} name @param {any} args @param {string} [workdir] */
+export const toolAction = (name, args, workdir) => {
+  if (name === 'shell_write') return { type: 'write', path: resolve(expandHome(String(args?.path ?? ''))), args: { bytes: String(args?.content ?? '').length } };
+  // shell_edit (BA-13) is judged as bareguard's own 'edit' action type — the SAME
+  // fs.writeScope fence as write, decided upstream (bareguard FS_TYPES). `bytes` is
+  // the replacement's size so the audit can read the edit economy (a 40-byte splice
+  // vs an 8KB rewrite is the variable BA-13 exists to move — F18 blindness rule).
+  if (name === 'shell_edit') return { type: 'edit', path: resolve(expandHome(String(args?.path ?? ''))), args: { bytes: String(args?.newText ?? '').length } };
+  // `tool` rides the action so the AUDIT can tell the read tools apart. Without it every
+  // read tool collapses to {type:'read', path} and a whole-file shell_read is
+  // indistinguishable from a bounded ctx_get chunk — the ledger cannot see the one
+  // variable the retrieval arm exists to test (the F18 blindness, repeated).
+  if (name === 'shell_read' || name === 'shell_grep') return { type: 'read', path: resolve(expandHome(String(args?.path ?? ''))), args: { tool: name } };
+  // The retrieval verbs are READS and are judged as reads by the SAME fence (F14/F19):
+  // ctx_get names a file, so the gate judges that file — the deny list (gate audit,
+  // primitive smoke, the litectx store itself) applies to a chunk read exactly as it
+  // applies to shell_read, or the worker would read the arbiter's books through the
+  // other door. ctx_recall names no file: it is a read OF THE INDEX, judged against the
+  // run directory, so it is contained by readScope and cannot reach outside the repo.
+  if (name === 'ctx_get') return { type: 'read', path: resolve(String(workdir ?? ''), expandHome(String(args?.path ?? ''))), args: { tool: name } };
+  if (name === 'ctx_recall') return { type: 'read', path: resolve(String(workdir ?? '')), args: { tool: name } };
+  // P's select/compress verbs are READS like the retrieval pair: the path-naming ones
+  // are judged against the named file (the deny list applies through every door), the
+  // index-wide ones against the run directory. `tool` rides along for the audit (F18).
+  if (name === 'ctx_related' || name === 'ctx_compress') return { type: 'read', path: resolve(String(workdir ?? ''), expandHome(String(args?.path ?? ''))), args: { tool: name } };
+  if (name === 'ctx_impact' || name === 'ctx_recent' || name === 'ctx_peek') return { type: 'read', path: resolve(String(workdir ?? '')), args: { tool: name } };
+  // Isolate verbs write to the litectx STORE, never the tree — they get their OWN
+  // action types (default-allow through the gate; admission is the signed spec's
+  // tools array). Judging them as 'write' would count store parks as tree writes in
+  // the F32 workerWrites instrument and corrupt worker-crash routing; judging them
+  // as 'read' would hide a write-class act from the audit. `bytes` rides so the
+  // audit can read the isolate economy.
+  if (name === 'ctx_stash' || name === 'ctx_remember') return { type: name, args: { id: String(args?.id ?? ''), bytes: String(args?.text ?? '').length } };
+  if (name === 'ctx_forget') return { type: name, args: { id: String(args?.id ?? '') } };
+  return { type: name, args };
+};