@cspeach/cli 1.1.27 → 1.1.28

package/dist/projects/plan-sources.js

@@ -0,0 +1,199 @@
+// Plan sources — the files a plan was made from, carried by the plan itself.
+//
+// 2026-10-04 (live run, FI Document Aging, CLI 1.1.27): phase c1.design said
+// "the spec-gap answers file is not in the project folder, so I can't read
+// gap-003/004/006/010/013/016". The file WAS in `.cspeach/`, and the plan
+// envelope even held a snapshot of every gap item (`promotedFrom`). But the
+// resume prompt carried only `content` (+ statuses): the phase got gap ids in
+// `manifest.reads` and nothing behind them, then hunted with glob (which never
+// walks `.cspeach/`) and gave up.
+//
+// The fix is one reusable mechanism, CLI-owned end to end:
+//   1. At creation the plan records WHERE its spec-gap lives:
+//      `content.from.specGap = { path, sha256 }` (specGapRefForSave, imposed by
+//      extractPlan — never model-authored, like `from.lane`).
+//   2. Every phase run resolves the plan's sources (resolvePlanSources: the
+//      live spec-gap file when it is still there and is the same envelope,
+//      else the snapshot the plan took at creation) and the phase prompt gets a
+//      <plan_sources> block with the gap items it reads, in full
+//      (renderPlanSourcesBlock). Phases never have to search for a file.
+//
+// Anything that runs a plan phase (today's per-phase resume, a future
+// continuous run) calls resolvePlanSources + renderPlanSourcesBlock.
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { readProjectFile } from './status.js';
+import { buildPromotedFromSnapshot } from './promote.js';
+import { assertRealPathContained } from '../tools/_filesystem-shared.js';
+import { laneRootFor, workspaceFolderFor } from '../lane/roots.js';
+/** A spec-gap envelope file name (`...spec-gap-<4hex>-v<N>[-n].cspeach.json`). */
+const SPEC_GAP_FILE_RE = /-spec-gap-[0-9a-f]{4}-v\d+(?:-\d+)?\.cspeach\.json$/i;
+/** Path relative to `root` ('/'-separated) when inside it, else absolute. */
+function relOrAbs(root, abs) {
+    const rel = path.relative(root, abs);
+    if (rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel))
+        return rel.split(path.sep).join('/');
+    return abs;
+}
+/**
+ * The `from.specGap` ref a plan SAVE records, from the CLI's promotion state
+ * (the resolved `--from` file + its promotedFrom snapshot). Undefined unless
+ * the plan really was promoted from a spec-gap file. The path is stored
+ * relative to the project folder (the folder holding `.cspeach`, the same root
+ * `from.lane.path` uses) so a team-shared folder stays portable.
+ */
+export async function specGapRefForSave(cwd, promotedFrom, sourcePath) {
+    if (!promotedFrom || promotedFrom.artefactType !== 'spec-gap' || !sourcePath)
+        return undefined;
+    if (!/^[0-9a-f]{64}$/.test(promotedFrom.sha256))
+        return undefined;
+    const abs = path.resolve(cwd, sourcePath);
+    const root = await laneRootFor(cwd).catch(() => path.resolve(cwd));
+    return { path: relOrAbs(root, abs), sha256: promotedFrom.sha256 };
+}
+async function containedIn(abs, root) {
+    if (!root)
+        return false;
+    try {
+        await assertRealPathContained(abs, await fs.realpath(root));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Find and read the plan's spec-gap file. Candidates: `from.specGap.path`,
+ * then the lane decision's `specGap.path`; each resolved against the project
+ * folder and cwd. A candidate is used only when it is a spec-gap file name,
+ * sits (real path) inside cwd or the workspace folder, parses as a spec-gap
+ * envelope, and — when the plan holds a promotedFrom snapshot — is the SAME
+ * envelope (id match). Returns undefined when none qualifies.
+ */
+async function readLiveSpecGap(cwd, content, promotedFrom, laneRecord) {
+    const recorded = [content.from.specGap?.path, laneRecord?.specGap?.path]
+        .filter((p) => typeof p === 'string' && p.trim() !== '');
+    if (recorded.length === 0)
+        return undefined;
+    const root = await laneRootFor(cwd).catch(() => path.resolve(cwd));
+    const ws = await workspaceFolderFor(cwd).catch(() => undefined);
+    for (const rec of recorded) {
+        if (!SPEC_GAP_FILE_RE.test(path.basename(rec)))
+            continue;
+        for (const base of [root, path.resolve(cwd)]) {
+            const abs = path.resolve(base, rec);
+            if (!(await containedIn(abs, cwd)) && !(await containedIn(abs, ws)) && !(await containedIn(abs, root)))
+                continue;
+            let env;
+            try {
+                env = readProjectFile(abs);
+            }
+            catch {
+                continue;
+            }
+            if (env.artefactType !== 'spec-gap')
+                continue;
+            if (promotedFrom && promotedFrom.id !== env.id)
+                continue;
+            return { env, shownPath: relOrAbs(root, abs) };
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve the sources a plan was made from. Prefers the live spec-gap file
+ * (answers given after the plan was made reach the phase), falls back to the
+ * plan's own creation snapshot (`promotedFrom`). Never throws.
+ */
+export async function resolvePlanSources(args) {
+    const pf = args.envelope.promotedFrom && args.envelope.promotedFrom.artefactType === 'spec-gap'
+        ? args.envelope.promotedFrom : null;
+    try {
+        const live = await readLiveSpecGap(args.cwd, args.content, pf, args.laneRecord);
+        if (live) {
+            const snap = await buildPromotedFromSnapshot(live.env);
+            const createdSha = args.content.from.specGap?.sha256 ?? pf?.sha256;
+            const sourceDocument = live.env.artefactType === 'spec-gap' ? live.env.content.sourceDocument : undefined;
+            return {
+                specGap: {
+                    path: live.shownPath,
+                    title: live.env.title,
+                    version: live.env.version,
+                    origin: 'file',
+                    changedSinceCreate: createdSha !== undefined && createdSha !== snap.sha256,
+                    ...(sourceDocument ? { sourceDocument } : {}),
+                    items: snap.snapshot.items,
+                },
+            };
+        }
+    }
+    catch {
+        // fall through to the snapshot — a read problem must never cost the phase its gaps
+    }
+    if (pf) {
+        const recordedPath = args.content.from.specGap?.path ?? args.laneRecord?.specGap?.path;
+        return {
+            specGap: {
+                ...(recordedPath ? { path: recordedPath } : {}),
+                title: pf.title,
+                version: pf.version,
+                origin: 'snapshot',
+                changedSinceCreate: false,
+                ...(args.laneRecord?.spec.path ? { sourceDocument: args.laneRecord.spec.path } : {}),
+                items: pf.snapshot.items,
+            },
+        };
+    }
+    return {};
+}
+const oneLine = (s) => s.replace(/\s+/g, ' ').trim();
+function renderItem(it) {
+    const sev = it.severity ? ` [${it.severity}]` : '';
+    const state = it.answer
+        ? `ANSWERED: "${oneLine(it.answer)}"`
+        : it.status === 'open' ? 'OPEN (no answer yet)' : it.status.toUpperCase();
+    return `- ${it.id}${sev} ${state} — ${oneLine(it.text)}`;
+}
+/**
+ * The <plan_sources> block for one phase prompt: the gap items the phase's
+ * `manifest.reads` names, in full; every other ANSWERED item as a short line
+ * (an answer is a decision — it must never be lost to a narrow reads list).
+ * Returns [] when the plan has no spec-gap source (block omitted entirely, so
+ * goal-only plans keep a byte-identical prompt).
+ */
+export function renderPlanSourcesBlock(sources, phase) {
+    const sg = sources.specGap;
+    if (!sg || sg.items.length === 0)
+        return [];
+    const reads = new Set(phase.manifest.reads);
+    const read = sg.items.filter((it) => reads.has(it.id));
+    const otherAnswered = sg.items.filter((it) => !reads.has(it.id) && it.answer);
+    const openOthers = sg.items.filter((it) => !reads.has(it.id) && !it.answer).length;
+    const where = sg.path ? ` (${sg.path})` : '';
+    const lines = [
+        '<plan_sources>',
+        `Spec-gap file this plan was made from: "${sg.title}" v${sg.version}${where}.`,
+        sg.origin === 'file'
+            ? 'CSPeach read it for this phase. The items below ARE its content: use them, do not search the folder for the file.'
+            : 'The file could not be read now, so these are the items as they were when the plan was made. Use them, do not search the folder for the file.',
+    ];
+    if (sg.changedSinceCreate) {
+        lines.push('Note: the spec-gap answers changed after the plan was made. The answers below are the current ones.');
+    }
+    if (sg.sourceDocument)
+        lines.push(`Spec document: ${sg.sourceDocument}`);
+    if (read.length > 0) {
+        lines.push('', `Gap items this phase reads (manifest.reads):`, ...read.map(renderItem));
+    }
+    if (otherAnswered.length > 0) {
+        lines.push('', 'Other answered gap items (decisions already made):', ...otherAnswered.map(renderItem));
+    }
+    if (openOthers > 0)
+        lines.push('', `${openOthers} other gap item${openOthers === 1 ? ' is' : 's are'} still open and not read by this phase.`);
+    const openRead = read.filter((it) => !it.answer).map((it) => it.id);
+    if (openRead.length > 0) {
+        lines.push('', `Still open among this phase's items: ${openRead.join(', ')}. Decide them from the spec, ask the developer where a choice matters, and record each decision in work.notes.`);
+    }
+    lines.push('</plan_sources>');
+    return lines;
+}

package/dist/projects/promote-command.js

@@ -131,5 +131,5 @@ export async function runPromoteCommand(args) {
     if (env.artefactType === 'spec-gap' && env.content.sourceDocument) {
         extendedSkillInput = `${extendedSkillInput}\n\nSource spec document: ${env.content.sourceDocument}`;
     }
-    return { promotedFrom, extendedSkillInput };
+    return { promotedFrom, extendedSkillInput, sourcePath: resolvedPath };
 }

package/dist/projects/save-command.js

@@ -14,11 +14,12 @@ import { parsePlanContent } from './plan-schema.js';
 import { validateEnvelope } from './validate.js';
 import { readProjectFile } from './status.js';
 import { saveProject } from './save.js';
-import { renderEmailTemplate } from './email-template.js';
+import { formatSavedLines } from './saved-lines.js';
 import { writePlanHandover } from './handover-md.js';
 import { ensureWorkspace, resolveWorkspacePath } from './workspace.js';
 import { askYesNo, isYes } from './yes-no.js';
 import { checkLaneConsistency, checkRequiredDeploy, LANE_CHANGED_AT_CREATE, readPlanLane } from './plan-lane.js';
+import { specGapRefForSave } from './plan-sources.js';
 const SKILL_REGISTRY = {
     'abap-spec-gap': {
         artefactType: 'spec-gap',
@@ -282,7 +283,11 @@ export async function runSaveCommand(args) {
     let planExtract = null;
     try {
         if (spec.artefactType === 'plan') {
-            planExtract = extractPlan(args.skillOutput, priorContent, args.lane ? { lane: { path: args.lane.path, sha256: args.lane.sha256 } } : {});
+            const specGap = await specGapRefForSave(args.cwd, args.promotedFrom, args.promotedFromPath);
+            planExtract = extractPlan(args.skillOutput, priorContent, {
+                ...(args.lane ? { lane: { path: args.lane.path, sha256: args.lane.sha256 } } : {}),
+                ...(specGap ? { specGap } : {}),
+            });
             extract = planExtract;
         }
         else {
@@ -421,7 +426,9 @@ export async function runSaveCommand(args) {
     // Best-effort by design (writePlanHandover logs one dim line on failure).
     if (spec.artefactType === 'plan')
         writePlanHandover(path, args.log);
-    args.log(`Saved: ${path}`);
+    // 1.1.28 — two plain lines; the old suggested-email block is gone (saved-lines.ts).
+    const [savedLine, reviewLine] = formatSavedLines(path, args.cwd);
+    args.log(savedLine);
     // Project Register (2026-09-18): when this laptop has joined a project, a
     // decision / fix record is written to the LOCAL outbox as a by-product of the
     // save. No project joined → `activeProject()` is one missing-file read and
@@ -445,15 +452,6 @@ export async function runSaveCommand(args) {
     if (planExtract && prior) {
         args.log(`(revision v${env.version} of the existing plan — version chain preserved, no new id)`);
     }
-    args.log(`Share at: https://cspeach.dev/edit`);
-    args.log('');
-    args.log(renderEmailTemplate({
-        title: env.title,
-        artefactType: spec.artefactType,
-        filename: path.split(/[\\\/]/).pop(),
-        itemCount: env.interaction.items.length,
-        itemNoun: spec.itemNoun,
-        author: args.author.name,
-    }));
+    args.log(reviewLine);
     return path;
 }

package/dist/projects/saved-lines.js

@@ -0,0 +1,36 @@
+/**
+ * The two lines printed after a project file is saved (every artefact type).
+ *
+ * 1.1.28 (owner decision): replaces the old "Suggested email — copy from
+ * below the line" block (subject, body, review steps, sign-off). It looked
+ * cluttered and signed itself with the OS account name ("Admin"). Now:
+ *
+ *   Saved: <file name> (in this project's .cspeach folder)
+ *   To review or share: open cspeach.dev/edit and drop the file in.
+ *
+ * Never prints a user name.
+ */
+import { basename, dirname, join, resolve } from 'node:path';
+function editorLabel() {
+    const url = process.env.CSPEACH_EDITOR_URL?.trim();
+    return url ? url : 'cspeach.dev/edit';
+}
+function sameDir(a, b) {
+    const norm = (p) => {
+        const r = resolve(p);
+        return process.platform === 'win32' ? r.toLowerCase() : r;
+    };
+    return norm(a) === norm(b);
+}
+/** `<file name> (in this project's .cspeach folder)` — or the folder, when elsewhere. */
+export function savedLocation(savedPath, cwd) {
+    const dir = dirname(savedPath);
+    const where = sameDir(dir, join(cwd, '.cspeach')) ? "this project's .cspeach folder" : dir;
+    return `${basename(savedPath)} (in ${where})`;
+}
+export function formatSavedLines(savedPath, cwd) {
+    return [
+        `Saved: ${savedLocation(savedPath, cwd)}`,
+        `To review or share: open ${editorLabel()} and drop the file in.`,
+    ];
+}

package/dist/renderer/checklist-format.js

@@ -78,7 +78,7 @@ function renderRow(r, width) {
     }
 }
 /**
- * The checklist as display lines: `Plan · N of M` header, then rows.
+ * The checklist as display lines: `Tasks · N of M` header, then rows.
  * - maxRows: cap on ITEM rows (header excluded). Not expanded → also capped
  *   at CHECKLIST_MAX_ROWS; expanded → only maxRows (the §2 height cap) applies.
  * - foldedToOne: exactly one line (used while a card is open).
@@ -92,7 +92,7 @@ export function formatChecklist(list, o) {
     const todos = list.map((t) => ({ ...t, text: sanitizeControlChars(t.text) }));
     const width = Math.max(1, Math.floor(o.width));
     const cur = currentTodoIndex(todos);
-    const count = `Plan · ${countLabel(doneCount(todos), todos.length)}`;
+    const count = `Tasks · ${countLabel(doneCount(todos), todos.length)}`;
     if (o.foldedToOne) {
         const tail = cur >= 0 ? ` · ${getGlyphs().current} ${todos[cur].text}` : '';
         return [chalk.bold(truncateToWidth(count + tail, width))];
@@ -103,15 +103,15 @@ export function formatChecklist(list, o) {
 }
 /**
  * The one line a turn leaves in scrollback when its plan changed (spec §4):
- * `✓ Plan · M of M done` (ok) when finished, else `Plan · N of M done` (dim).
+ * `✓ Tasks · M of M done` (ok) when finished, else `Tasks · N of M done` (dim).
  */
 export function formatPlanClose(todos) {
     const done = doneCount(todos);
     const total = todos.length;
     if (total > 0 && done === total) {
-        return paint('ok', `${getGlyphs().done} Plan · ${countLabel(done, total)} done`);
+        return paint('ok', `${getGlyphs().done} Tasks · ${countLabel(done, total)} done`);
     }
-    return paint('dim', `Plan · ${countLabel(done, total)} done`);
+    return paint('dim', `Tasks · ${countLabel(done, total)} done`);
 }
 let modeOverride;
 /** Test seam — force a mode; `undefined` restores detection. */

package/dist/renderer/machine-blocks.js

@@ -0,0 +1,141 @@
+// src/renderer/machine-blocks.ts
+//
+// 1.1.28 — machine-readable blocks the skills emit for the CLI
+// (`<!-- cspeach:plan-manifest {...} -->`, the legacy `<!-- csforge:... -->`
+// prefix, and the cca / upgrade / modernize / test-coverage manifests) are
+// parsed from the RAW assistant content (extract-plan.ts, plan-continue.ts,
+// loop.ts onPlanManifest — untouched by this file) but must never reach the
+// screen: a plan manifest is a multi-KB JSON blob.
+//
+// This is a streaming filter that sits in front of renderChunk (loop.ts), so
+// it covers the Ink and classic renderers and one-shot stdout alike. It only
+// changes what is DISPLAYED; the assistant content, the session file and the
+// turn stream log keep the block byte-for-byte.
+//
+// Rule: a block starts with `<!--`, optional blanks, `cspeach:` or `csforge:`
+// at the START of a line. It ends at a `-->` on the opener's own line, or
+// else at a `-->` that starts a later line (one newline straight after it is
+// dropped too). An inline mention mid-line is prose and stays.
+// A chunk boundary can fall anywhere: a line that could still become an
+// opener is held until it can be decided; inside a block a tail that could
+// still become the closing `-->` is held the same way.
+export function initialMachineBlockState() {
+    return { held: '', inBlock: false, firstLine: false, eatNewline: false, lineStart: true };
+}
+// A leading `\n` marks a line start (the probe prepends one when the text
+// begins at a line start) — no `^`, which would match a mid-line chunk start.
+const OPENER_RE = /\n[ \t]*<!--[ \t]*(?:cspeach|csforge):/;
+const PREFIXES = ['cspeach:', 'csforge:'];
+const CLOSER_RE = /\n[ \t]*-->/;
+const PARTIAL_CLOSER_RE = /^\n[ \t]*-{0,2}$/;
+/** Could `frag` (one incomplete line) still grow into a block opener? */
+function couldBeOpener(frag) {
+    const s = frag.replace(/^[ \t]*/, '');
+    if (s.length <= 4)
+        return '<!--'.startsWith(s);
+    if (!s.startsWith('<!--'))
+        return false;
+    const r = s.slice(4).replace(/^[ \t]*/, '');
+    return PREFIXES.some((p) => p.startsWith(r));
+}
+export function filterMachineBlocks(chunk, prev) {
+    const st = { ...prev };
+    let work = st.held + chunk;
+    st.held = '';
+    let output = '';
+    for (;;) {
+        if (st.eatNewline) {
+            if (work === '')
+                break;
+            if (work.startsWith('\r\n')) {
+                work = work.slice(2);
+                st.lineStart = true;
+            }
+            else if (work === '\r') {
+                st.held = work;
+                work = '';
+                break;
+            }
+            else if (work[0] === '\n') {
+                work = work.slice(1);
+                st.lineStart = true;
+            }
+            else
+                st.lineStart = false;
+            st.eatNewline = false;
+        }
+        if (st.inBlock && st.firstLine) {
+            // Still on the opener line: any `-->` closes (`<!-- cspeach:x -->`).
+            const close = work.indexOf('-->');
+            const nl = work.indexOf('\n');
+            if (close >= 0 && (nl < 0 || close < nl)) {
+                work = work.slice(close + 3);
+                st.inBlock = false;
+                st.eatNewline = true;
+                continue;
+            }
+            if (nl < 0) {
+                st.held = work.slice(-2);
+                break;
+            }
+            st.firstLine = false;
+            work = work.slice(nl); // keep the newline: it marks the next line start
+            continue;
+        }
+        if (st.inBlock) {
+            // Body lines: only a `-->` at the start of a line closes, the same rule
+            // as the extractors (`\n\s*-->`), so a note like "A --> B" inside the
+            // JSON does not end the block early.
+            const m = CLOSER_RE.exec(work);
+            if (!m) {
+                const lastNl = work.lastIndexOf('\n');
+                const tail = lastNl >= 0 ? work.slice(lastNl) : '';
+                st.held = PARTIAL_CLOSER_RE.test(tail) ? tail : '';
+                break;
+            }
+            work = work.slice(m.index + m[0].length);
+            st.inBlock = false;
+            st.eatNewline = true;
+            continue;
+        }
+        const probe = (st.lineStart ? '\n' : '') + work;
+        const m = OPENER_RE.exec(probe);
+        if (m) {
+            const offset = st.lineStart ? 1 : 0;
+            const lineBegin = m.index + 1 - offset; // index in `work`, just after the newline
+            output += work.slice(0, lineBegin);
+            work = work.slice(m.index + m[0].length - offset);
+            st.inBlock = true;
+            st.firstLine = true;
+            continue;
+        }
+        // No opener yet: hold the last incomplete line if it could become one.
+        const lastNl = work.lastIndexOf('\n');
+        const fragStart = lastNl >= 0 ? lastNl + 1 : st.lineStart ? 0 : -1;
+        if (fragStart >= 0 && fragStart < work.length && couldBeOpener(work.slice(fragStart))) {
+            output += work.slice(0, fragStart);
+            st.held = work.slice(fragStart);
+            st.lineStart = true;
+        }
+        else {
+            output += work;
+            if (work.length > 0)
+                st.lineStart = work.endsWith('\n');
+        }
+        break;
+    }
+    return { output, state: st };
+}
+/** End of stream: release held prose; an unterminated block shows nothing. */
+export function flushMachineBlocks(state) {
+    if (state.inBlock)
+        return '';
+    if (state.eatNewline)
+        return state.held === '\r' ? '' : state.held;
+    return state.held;
+}
+/** Whole-text form (same rule) for output that is not streamed. */
+export function stripMachineBlocks(text) {
+    const r = filterMachineBlocks(text, initialMachineBlockState());
+    return r.output + flushMachineBlocks(r.state);
+}

package/dist/renderer/tool-labels.js

@@ -122,6 +122,8 @@ const RULES = {
         const incName = inc !== undefined ? (Object.hasOwn(INCLUDE_NAMES, inc) ? INCLUDE_NAMES[inc] : inc) : '';
         return { verb: 'Wrote', object: shortRight(`${str(a['className']) ?? ''} ${incName}`.trim()) };
     },
+    sap_get_text_elements: (a) => ({ verb: 'Read texts of', object: shortRight(`${str(a['name']) ?? ''} ${str(a['kind']) ?? ''}`.trim()) }),
+    sap_set_text_elements: (a) => ({ verb: 'Wrote texts', object: shortRight(`${str(a['name']) ?? ''} ${str(a['kind']) ?? ''}`.trim()) }),
     sap_search_object: (a, r) => {
         // "*AGING*" · PROG — the type filter tells otherwise identical searches apart.
         const type = str(a['type']);
@@ -263,6 +265,7 @@ const PRESENT = {
     Preview: 'Preview', 'Searched samples': 'Searching samples', 'Read sample': 'Reading sample',
     'Audited metadata': 'Auditing metadata', 'Extended model': 'Extending model',
     'Checked capability': 'Checking capability',
+    'Read texts of': 'Reading texts of', 'Wrote texts': 'Writing texts',
 };
 export function toolActivityLabel(name, args) {
     const l = toolLabel(name, args);

package/dist/repl/plan-hop.js

@@ -0,0 +1,22 @@
+// src/repl/plan-hop.ts
+//
+// Task 13 fix round (2026-10-04) — an "in-run hop" is a plan-resume the plan
+// chain ITSELF queued (runPostPhaseChain / runReauditPass /
+// runContinuationChain: the next step, the re-run after a failed check).
+// Marked at the source, never inferred from the command shape: the first step
+// of an /abap-app run (lane/app-chain.ts) and a typed resume are NOT hops, so
+// they show the board and the guarded notice once.
+export function createPlanHopTracker(slot) {
+    let chainQueued = null;
+    return {
+        queue(cmd) {
+            chainQueued = cmd;
+            slot.set(cmd);
+        },
+        take(cmd) {
+            const hop = chainQueued !== null && chainQueued === cmd;
+            chainQueued = null;
+            return hop;
+        },
+    };
+}

package/dist/repl/rule8-detector.js

@@ -26,6 +26,19 @@ let planGateApprovedThisTurn = false;
 export function recordWriteOp(tool, args) {
     writeOpsThisTurn.push({ tool, args, ts: new Date().toISOString() });
 }
+let batchApprovedProvider = null;
+export function setRule8BatchApprovedProvider(fn) {
+    batchApprovedProvider = fn;
+}
+/**
+ * True for a tool that cannot run without an approval id from request_approval
+ * (its schema requires `approval_id`): each such call is already approved one
+ * by one. Shell, file and other tools without an id are never in this set.
+ */
+export function toolSpendsApprovalId(tool) {
+    const req = tool.input_schema?.required;
+    return Array.isArray(req) && req.includes('approval_id');
+}
 /**
  * Returns true on the 2nd (and later) mutating call of the turn — the gate
  * fires here. The 1st mutating call proceeds without the prompt; only its
@@ -38,9 +51,11 @@ export function recordWriteOp(tool, args) {
  * batches the model issues OUTSIDE the approval flow (rare but possible —
  * e.g. recovery paths, ad-hoc tool calls), so the safety net stays.
  */
-export function shouldGateRule8() {
+export function shouldGateRule8(tool) {
     if (planGateApprovedThisTurn)
         return false;
+    if (tool && batchApprovedProvider?.(tool))
+        return false;
     return writeOpsThisTurn.length >= 1;
 }
 /**