@cspeach/cli 1.1.19 → 1.1.20

package/dist/tools/result-spill.js

@@ -0,0 +1,238 @@
+/**
+ * Task 17 (model control, 2026-09-27, spec D12) — large tool results go to a
+ * file; the history keeps a preview and a path.
+ *
+ * Claude Code's "output too large, saved to file" pattern. Above
+ * SPILL_THRESHOLD_CHARS the full text is written to
+ * ~/.cspeach/streams/<sessionId>/tool-<toolUseId>.txt and the tool_result
+ * carries the first 60 lines (plus the last 20 for source, SQL, shell and file windows),
+ * then one pointer line naming tool_output_read.
+ *
+ * Sizing happens ONCE, when the tool_result is created (the handler's return
+ * value) — never afterwards, so it is not a history edit and the cached
+ * prefix / preserved thinking stay append-only.
+ *
+ * The spill file holds exactly the text the tool would have returned — no
+ * more (no secrets beyond what the tool already produced), and it lives in the
+ * per-session area under ~/.cspeach, never in the user's project.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { streamsRoot } from '../agent/turn-stream.js';
+import { rememberSpillLabel } from '../lib/spill-labels.js';
+export const SPILL_THRESHOLD_CHARS = 8_000;
+export const PREVIEW_HEAD_LINES = 60;
+export const PREVIEW_TAIL_LINES = 20;
+/** One preview line never carries more than this (a minified JSON line must not defeat the preview). */
+export const PREVIEW_LINE_MAX_CHARS = 500;
+/** Character budgets for the head and tail blocks of the preview. */
+export const PREVIEW_HEAD_BUDGET_CHARS = 6_000;
+export const PREVIEW_TAIL_BUDGET_CHARS = 2_000;
+/**
+ * Kinds whose preview also keeps the last lines (the end matters: totals,
+ * exit code, ENDCLASS; for file_read the window's last line). Only search
+ * hits and reports are head-only.
+ */
+const TAIL_KINDS = new Set(['source', 'sql', 'shell', 'file']);
+/** Session ids / tool_use ids become file names: keep them path-inert. */
+function safeSegment(s) {
+    const cleaned = s.replace(/[^A-Za-z0-9_-]/g, '_');
+    return cleaned.length > 0 ? cleaned : '_';
+}
+/** The directory that holds one session's spill files. */
+export function spillDirFor(sessionId) {
+    return path.join(streamsRoot(), safeSegment(sessionId));
+}
+/**
+ * Session id as the tools see it, or undefined when the ctx carries none
+ * (some tests and non-loop call paths). Without a session there is no
+ * private spill dir, so nothing is spilled and tool_output_read refuses —
+ * never a shared fallback directory (fix round 1, minor 3).
+ */
+export function sessionIdOf(ctx) {
+    const id = ctx.session?.id;
+    return typeof id === 'string' && id.length > 0 ? id : undefined;
+}
+/**
+ * Spill file names: `tool-<id>.txt`, or `tool-<id>.n.txt` for text that is
+ * already line-numbered (file_read windows keep the FILE's line numbers, so
+ * tool_output_read shows those lines as they are instead of numbering again —
+ * one numbering space). tool_output_read accepts only these shapes.
+ */
+export const SPILL_FILE_RE = /^tool-[A-Za-z0-9_-]+(\.n)?\.txt$/;
+export const NUMBERED_SPILL_RE = /\.n\.txt$/;
+/** Spill files older than this are deleted at REPL start (like the notice logs). */
+export const SPILL_MAX_AGE_DAYS = 14;
+function clipLine(line) {
+    if (line.length <= PREVIEW_LINE_MAX_CHARS)
+        return line;
+    return `${line.slice(0, PREVIEW_LINE_MAX_CHARS)}… [+${line.length - PREVIEW_LINE_MAX_CHARS} chars]`;
+}
+export function pointerLine(lines, chars, filePath) {
+    return `[${lines} lines / ${chars} chars — full output saved to ${filePath}; read slices with tool_output_read(path, offset, limit)]`;
+}
+/**
+ * Build the preview text for `text` (already known to be large). Pure. Line
+ * numbers in the omitted marker are the spill file's own (1-based, =
+ * tool_output_read offset + 1); for an already-numbered spill the marker names
+ * the offset instead, since the visible numbers belong to the source file.
+ */
+export function buildPreview(text, kind, filePath, opts = {}) {
+    const lines = text.split('\n');
+    const total = lines.length;
+    const head = [];
+    let used = 0;
+    for (let i = 0; i < total && head.length < PREVIEW_HEAD_LINES; i++) {
+        const l = clipLine(lines[i]);
+        if (head.length > 0 && used + l.length + 1 > PREVIEW_HEAD_BUDGET_CHARS)
+            break;
+        head.push(l);
+        used += l.length + 1;
+    }
+    const tail = [];
+    if (TAIL_KINDS.has(kind)) {
+        let tailUsed = 0;
+        for (let i = total - 1; i >= head.length && tail.length < PREVIEW_TAIL_LINES; i--) {
+            const l = clipLine(lines[i]);
+            if (tail.length > 0 && tailUsed + l.length + 1 > PREVIEW_TAIL_BUDGET_CHARS)
+                break;
+            tail.unshift(l);
+            tailUsed += l.length + 1;
+        }
+    }
+    const out = [...head];
+    const omittedFrom = head.length + 1; // 1-based first omitted line
+    const omittedTo = total - tail.length; // 1-based last omitted line
+    if (omittedTo >= omittedFrom) {
+        out.push(opts.numbered
+            ? `[… ${omittedTo - omittedFrom + 1} lines omitted — tool_output_read offset=${omittedFrom - 1} …]`
+            : `[… lines ${omittedFrom}–${omittedTo} omitted …]`);
+    }
+    out.push(...tail);
+    out.push(pointerLine(total, text.length, filePath));
+    return out.join('\n');
+}
+/**
+ * Size a tool result at ingestion. At or below the threshold → unchanged.
+ * Above it → the full text goes to the session spill file and a preview comes
+ * back. A write failure fails OPEN (full text returned, nothing lost).
+ *
+ * `header` (sap_get_source's version line) counts toward the threshold and
+ * leads the preview, but is NOT written to the file: the file is the body
+ * alone, so tool_output_read line k is body line k (fix round 1, I1), and the
+ * pointer's counts describe the body.
+ */
+export function spillIfLarge(i) {
+    const whole = i.header !== undefined ? `${i.header}\n${i.text}` : i.text;
+    if (whole.length <= (i.threshold ?? SPILL_THRESHOLD_CHARS))
+        return { spilled: false, text: whole };
+    const dir = spillDirFor(i.sessionId);
+    const id = safeSegment(i.toolUseId && i.toolUseId.length > 0 ? i.toolUseId : crypto.randomUUID());
+    const filePath = path.join(dir, `tool-${id}${i.numbered ? '.n' : ''}.txt`);
+    try {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(filePath, i.text, { encoding: 'utf-8', mode: 0o600 });
+    }
+    catch {
+        return { spilled: false, text: whole };
+    }
+    const preview = buildPreview(i.text, i.kind, filePath, { numbered: i.numbered });
+    return { spilled: true, text: i.header !== undefined ? `${i.header}\n${preview}` : preview, path: filePath };
+}
+/**
+ * Convenience for handlers: size `result.content` with the ctx's session and
+ * tool_use id. With a header, `result.content` is the body and the returned
+ * content is `header\n…`. No session id → never spilled.
+ */
+export function spillToolResult(result, ctx, kind, opts = {}) {
+    const sessionId = sessionIdOf(ctx);
+    const whole = opts.header !== undefined ? `${opts.header}\n${result.content}` : result.content;
+    if (sessionId === undefined)
+        return whole === result.content ? result : { ...result, content: whole };
+    const { label, ...spillOpts } = opts;
+    const s = spillIfLarge({ text: result.content, sessionId, toolUseId: ctx.toolUseId, kind, ...spillOpts });
+    if (s.spilled && s.path && label)
+        rememberSpillLabel(s.path, label);
+    return s.text === result.content ? result : { ...result, content: s.text };
+}
+/**
+ * Delete spill files (tool-*.txt in every session dir under the spill root)
+ * last modified more than SPILL_MAX_AGE_DAYS ago, then any session dir left
+ * empty. Other files (the turn mirrors) are left alone; symlinks and
+ * junctions (root, dirs, files) are never followed. Best effort: never
+ * throws. Returns how many files were deleted.
+ */
+export function pruneSpillFiles(now = Date.now()) {
+    const cutoff = now - SPILL_MAX_AGE_DAYS * 24 * 60 * 60 * 1000;
+    let removed = 0;
+    let dirs;
+    try {
+        // Final review tools-I1 — never follow links: a symlinked / junctioned
+        // root, session dir or file is skipped (lstat), so the prune can never
+        // delete outside the CLI's own area.
+        if (!fs.lstatSync(streamsRoot()).isDirectory())
+            return 0;
+        dirs = fs.readdirSync(streamsRoot());
+    }
+    catch {
+        return 0;
+    }
+    for (const d of dirs) {
+        const dir = path.join(streamsRoot(), d);
+        let names;
+        try {
+            const st = fs.lstatSync(dir);
+            if (st.isSymbolicLink() || !st.isDirectory())
+                continue;
+            names = fs.readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (!SPILL_FILE_RE.test(name))
+                continue;
+            const p = path.join(dir, name);
+            try {
+                const st = fs.lstatSync(p);
+                if (st.isSymbolicLink() || !st.isFile())
+                    continue;
+                if (st.mtimeMs < cutoff) {
+                    fs.unlinkSync(p);
+                    removed++;
+                }
+            }
+            catch {
+                /* best effort */
+            }
+        }
+        try {
+            if (fs.readdirSync(dir).length === 0)
+                fs.rmdirSync(dir);
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    return removed;
+}
+/** True when `child` lies strictly inside `dir`. */
+export function isInside(dir, child) {
+    const rel = path.relative(dir, child);
+    return rel.length > 0 && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+/** `p` and, when it exists, its realpath (8.3 names, /var → /private/var). */
+export function withRealpath(p) {
+    try {
+        const real = fs.realpathSync.native(p);
+        return real === p ? [p] : [p, real];
+    }
+    catch {
+        return [p];
+    }
+}
+/** True when `absPath` (already a realpath) lies under the spill root (any session). */
+export function isUnderSpillRoot(absPath) {
+    return withRealpath(streamsRoot()).some((root) => isInside(root, absPath));
+}

package/dist/tools/sap-read.js

@@ -24,6 +24,48 @@
 import { registerTool } from './index.js';
 import { normaliseSyntaxResult, checkSyntax } from './verify.js';
 import { recordSyntaxCheck } from './syntax-state.js';
+import { spillToolResult } from './result-spill.js';
+// -----------------------------------------------------------------------
+// Task 17 (spec D12, ruling F18) — model-facing formats.
+// -----------------------------------------------------------------------
+/**
+ * sap_get_source's one-line header: `[version: active]`,
+ * `[version: inactive | <warning>]` (any version may carry the split-state
+ * warning), or `[version: unknown]`. Plan-audit evidence reads the first
+ * 200 chars of the result, so the version leads it.
+ */
+export function formatSourceHeader(version, warning) {
+    return warning ? `[version: ${version} | ${warning.replace(/\s*\n\s*/g, ' ')}]` : `[version: ${version}]`;
+}
+/** Inverse of formatSourceHeader: the version (and warning) back from a result. */
+export function parseSourceHeader(text) {
+    const first = text.split('\n', 1)[0] ?? '';
+    const m = /^\[version: ([a-z]+)(?: \| (.*))?\]$/.exec(first);
+    if (!m)
+        return { version: 'unknown' };
+    return m[2] !== undefined ? { version: m[1], warning: m[2] } : { version: m[1] };
+}
+/** One TSV cell: tabs / newlines inside a value cannot break the grid. */
+const tsvCell = (v) => (v === null || v === undefined ? '' : String(v)).replace(/[\t\r\n]+/g, ' ');
+export function formatSqlTsv(result) {
+    const cols = result.columns ?? [];
+    const rows = result.rows ?? [];
+    const lines = [cols.map(tsvCell).join('\t'), ...rows.map((r) => cols.map((c) => tsvCell(r[c])).join('\t'))];
+    const n = rows.length;
+    const total = typeof result.totalRows === 'number' && result.totalRows > n ? ` of ${result.totalRows}` : '';
+    lines.push(`(${n} ${n === 1 ? 'row' : 'rows'}${total})`);
+    return lines.join('\n');
+}
+/** Search hits, one per line: NAME  TYPE  PACKAGE  DESCRIPTION  URI ("-" for an empty field). */
+export function formatSearchHits(hits) {
+    if (hits.length === 0)
+        return '(no hits)';
+    const f = (v) => {
+        const t = typeof v === 'string' ? v.replace(/\s+/g, ' ').trim() : '';
+        return t.length > 0 ? t : '-';
+    };
+    return hits.map((h) => [h.name, h.type, h.packageName ?? h.package, h.description, h.uri].map(f).join('  ')).join('\n');
+}
 // -----------------------------------------------------------------------
 // 1. sap_get_source
 // -----------------------------------------------------------------------
@@ -36,7 +78,8 @@ registerTool({
         + 'the response is the active source AND a warning is emitted so the '
         + 'caller knows the inactive edits are not visible. For a freshly '
         + 'created object with NO active version yet, the inactive (working) '
-        + 'source is returned with version="inactive" and an honest note.',
+        + 'source is returned with version="inactive" and an honest note. '
+        + 'The first line is a [version: …] header, not part of the source.',
     isMutating: false,
     requiresSap: true,
     input_schema: {
@@ -117,13 +160,13 @@ registerTool({
                 // probe failed — leave resolvedVersion as 'unknown'
             }
         }
-        return {
-            content: JSON.stringify({
-                source,
-                version: resolvedVersion,
-                ...(splitStateWarning ? { split_state_warning: splitStateWarning } : {}),
-            }),
-        };
+        // Fix round 1 (I1): the header leads the result and the preview, but a
+        // spill file holds the source alone — tool_output_read line k is source
+        // line k, matching syntax-check / ATC line numbers.
+        return spillToolResult({ content: String(source) }, ctx, 'source', {
+            header: formatSourceHeader(resolvedVersion, splitStateWarning),
+            label: String(args.name).toUpperCase(),
+        });
     },
 });
 // -----------------------------------------------------------------------
@@ -155,10 +198,11 @@ registerTool({
         // `version` right after name/type puts it inside the excerpt window.
         const versionMatch = /\badtcore:version="([^"]*)"/.exec(result.rawXml ?? '');
         const version = versionMatch?.[1] || 'unknown';
-        // name/type/version lead the serialized JSON (rawXml stays last via the
-        // rest spread), so `version` sits inside the excerpt window while every
-        // ObjectStructure field is preserved.
-        const { name, type, ...rest } = result;
+        // name/type/version lead the serialized JSON, so `version` sits inside
+        // the excerpt window. Task 17: rawXml is parsed above and never sent to
+        // the model (it was the bulk of the result).
+        const { name, type, rawXml, ...rest } = result;
+        void rawXml;
         return { content: JSON.stringify({ name, type, version, ...rest }, null, 2) };
     },
 });
@@ -187,7 +231,7 @@ registerTool({
     },
     handler: async (args, ctx) => {
         const results = await ctx.adt.searchObject(args.query, args.type, args.maxResults ?? 100);
-        return { content: JSON.stringify(results, null, 2) };
+        return spillToolResult({ content: formatSearchHits(results) }, ctx, 'search', { label: `search "${args.query}"` });
     },
 });
 // -----------------------------------------------------------------------
@@ -231,7 +275,7 @@ registerTool({
     },
     handler: async (args, ctx) => {
         const result = await ctx.adt.sqlQuery(args.query, args.maxRows ?? 100);
-        return { content: JSON.stringify(result, null, 2) };
+        return spillToolResult({ content: formatSqlTsv(result) }, ctx, 'sql', { label: 'query result' });
     },
 });
 // -----------------------------------------------------------------------

package/dist/tools/shell/shell_exec.js

@@ -46,12 +46,21 @@ import { registerTool } from '../index.js';
 import { resolveSafePath, PathOutsideRootError } from '../_filesystem-shared.js';
 import { loadSafelist, buildSafeEnv, resolveExecutable, validateArgv, rejectPathSeparator, DEFAULT_SAFELIST, KILL_GRACE_MS, } from '../_command-shared.js';
 import { killProcessTree } from '../fiori/preview/registry.js';
+import { spillToolResult } from '../result-spill.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
 /** After the kill's grace: how long to wait for the pipes before returning anyway. */
 const ORPHAN_WAIT_MS = 3_000;
 const MAX_TIMEOUT_MS = 300_000;
 const MAX_OUTPUT_BYTES = 1_000_000; // per stream
+/**
+ * Task 17 (spec D12) — output above 8 000 chars is saved to the session spill
+ * file; the result carries the first 60 + last 20 lines (the exit code stays
+ * visible) and a pointer. Sized once, here, when the result is created.
+ */
 export async function shellExecHandler(args, ctx) {
+    return spillToolResult(await runShellExec(args, ctx), ctx, 'shell', { label: 'command output' });
+}
+async function runShellExec(args, ctx) {
     if (!args.command || typeof args.command !== 'string') {
         return { content: 'error: command is required (non-empty string)', is_error: true };
     }

package/dist/tools/subagent/adt-serial.js

@@ -0,0 +1,33 @@
+/**
+ * Task 18 (ruling F21) — parallel readers share one AdtClient, and concurrent
+ * ADT requests through it are unverified. Readers run their MODEL work in
+ * parallel, but their SAP calls go through one lock: one ADT request at a
+ * time for the whole reader group.
+ */
+/** A FIFO mutex. A call that fails releases the lock like one that succeeds. */
+export function createAdtLock() {
+    let tail = Promise.resolve();
+    return {
+        run(fn) {
+            const result = tail.then(() => fn());
+            tail = result.then(() => undefined, () => undefined);
+            return result;
+        },
+    };
+}
+/**
+ * A view of `adt` whose method calls run through `lock`. Methods run on the
+ * real client (`this` is the client, so its internal calls are not re-queued);
+ * non-function properties pass through. Every AdtClient method a reader tool
+ * calls is async, so returning a promise changes nothing for the caller.
+ */
+export function serializeAdt(adt, lock) {
+    return new Proxy(adt, {
+        get(target, prop, _receiver) {
+            const value = Reflect.get(target, prop, target);
+            if (typeof value !== 'function')
+                return value;
+            return (...args) => lock.run(() => value.apply(target, args));
+        },
+    });
+}

package/dist/tools/subagent/agent_run.js

@@ -122,6 +122,8 @@ export async function agentRunHandler(args, ctx) {
         cwd: ctx.cwd,
         provider: ctx.provider,
         skillSource: ctx.skillSource,
+        // Task 18 fix M4 — an agent_run child never starts reader subagents.
+        subagent: true,
         // previewHook + pendingDispatch + currentTransport + todoEmitter
         // intentionally omitted.
     };

package/dist/tools/subagent/read_agent.js

@@ -0,0 +1,178 @@
+/**
+ * read_agent — Task 18 (model control, 2026-09-27, spec D18).
+ *
+ * Heavy reading (many sources, a where-used walk, ATC-finding triage, a
+ * package inventory) runs in a lean child conversation and only a short
+ * report returns to the parent's history. Unlike agent_run (flag-gated, a
+ * full skill prefix per child), a reader carries:
+ *   - a ~300-token system prompt owned by the proxy (skill header `_reader`,
+ *     ruling F8; BYOK / AI-hub use the pinned copy in reader-prompt.ts),
+ *   - a fixed small tool list (READER_TOOLS: read-only, no tool search),
+ *   - the session model at effort `low`, role `reader` (never enforced, F7),
+ *   - a capped report: overflow is saved to a file and the tail is cut.
+ *
+ * Read-only and depth 1 are enforced by `ctx.readerMode` at dispatch (F22).
+ * The loop runs consecutive read_agent calls concurrently, each with its own
+ * ctx clone whose `adt` is serialized through one lock (F21). The child's
+ * spend is added to the parent's per-turn `readerSpend` (F24); the child also
+ * writes its own reader-*-cost.jsonl.
+ */
+import { EventEmitter } from 'node:events';
+import { listTools, registerTool, toolsForContext } from '../index.js';
+import { runTurn } from '../../agent/loop.js';
+import { collectTurnAssistantText } from '../../agent/turn-assistant-text.js';
+import { newSession } from '../../session/schema.js';
+import { computeSessionCost } from '../../cost/session-cost.js';
+import { sessionIdOf, spillIfLarge } from '../result-spill.js';
+import { INTERRUPTED_LINE, READER_SKILL, READER_SYSTEM_PROMPT, READER_TOOLS, hasReaderReadTools } from './reader-prompt.js';
+export { INTERRUPTED_LINE, READER_SKILL, READER_SYSTEM_PROMPT, READER_TOOLS, hasReaderReadTools };
+export const BRIEF_MAX_CHARS = 4_000;
+export const DEFAULT_REPORT_MAX_CHARS = 3_000;
+export const HARD_REPORT_MAX_CHARS = 6_000;
+/**
+ * Final review tools-I4 — told to every reader. The proxy owns the reader's
+ * system prompt (pinned byte-equal), so the CLI says this in the child's
+ * user message.
+ */
+export const PARENT_OUTPUT_LINE = 'A saved-output path in this brief (a scan or ATC result the main session already ran) can be read with ' +
+    'tool_output_read. Read it instead of repeating the scan: never re-run ATC or a scan whose output you were given.';
+/** The result when the account's proxy refuses the `_reader` skill. */
+export const NOT_ENABLED_LINE = 'readers are not enabled for this account — read the sources directly';
+function reportCap(raw) {
+    if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 1)
+        return DEFAULT_REPORT_MAX_CHARS;
+    return Math.min(Math.floor(raw), HARD_REPORT_MAX_CHARS);
+}
+function isNotEntitled(err) {
+    const e = err;
+    if (e?.error?.error === 'skill_not_in_entitlements')
+        return true;
+    return typeof e?.message === 'string' && e.message.includes('skill_not_in_entitlements');
+}
+export async function readAgentHandler(args, ctx) {
+    const brief = args?.brief;
+    if (typeof brief !== 'string' || brief.trim().length === 0) {
+        return { content: "error: 'brief' is required: say what to read and what to report.", is_error: true };
+    }
+    if (brief.length > BRIEF_MAX_CHARS) {
+        return { content: `error: 'brief' is ${brief.length} chars; keep it under ${BRIEF_MAX_CHARS}.`, is_error: true };
+    }
+    // Depth 1 (dispatch refuses this too; belt and braces for direct calls).
+    if (ctx.readerMode) {
+        return { content: 'error: a reader cannot start another reader.', is_error: true };
+    }
+    // Fix M4 — an agent_run child does its own reading.
+    if (ctx.subagent) {
+        return { content: 'error: a subagent cannot start a reader — read the sources directly.', is_error: true };
+    }
+    // Fix M5 — nothing a reader could read here (standalone, file tools off).
+    if (!hasReaderReadTools(new Set(toolsForContext(listTools(), ctx).map((t) => t.name)))) {
+        return { content: 'error: no read tools are available to a reader here — read the sources directly.', is_error: true };
+    }
+    if (ctx.signal?.aborted)
+        return { content: INTERRUPTED_LINE, is_error: true };
+    if (!ctx.provider) {
+        return { content: 'error: read_agent requires ctx.provider — not wired into this ToolContext.', is_error: true };
+    }
+    const cap = reportCap(args.report_max_chars);
+    // The session model, never a cheaper one (owner decision 11); effort low.
+    const model = ctx.session.model;
+    const childSession = newSession(`reader-${Date.now()}-${Math.floor(Math.random() * 1e9).toString(16)}`, ctx.session.sap_system ?? null, READER_SKILL, model);
+    // Only what a read needs. No previewHook (no writes), no chunkEmitter /
+    // todoEmitter (the child never paints the parent UI), no pendingDispatch /
+    // currentTransport (the child never changes parent REPL state).
+    const parentSessionId = sessionIdOf(ctx);
+    const childCtx = {
+        adt: ctx.adt,
+        sapAlias: ctx.sapAlias,
+        session: childSession,
+        cwd: ctx.cwd,
+        provider: ctx.provider,
+        skillSource: ctx.skillSource,
+        readerMode: true,
+        // Final review tools-I4 — the reader may open the parent's saved outputs.
+        ...(parentSessionId !== undefined ? { spillParentSessionId: parentSessionId } : {}),
+    };
+    const userMessage = `${brief}\n\n${PARENT_OUTPUT_LINE}\n\nReport limit: ${cap} characters.`;
+    let failure = null;
+    try {
+        await runTurn({
+            provider: ctx.provider,
+            userMessage,
+            skill: READER_SKILL,
+            ctx: childCtx,
+            // Null sink: the child's text lands in childSession.messages only.
+            chunkEmitter: new EventEmitter(),
+            modelRole: 'reader',
+            toolsOverride: READER_TOOLS,
+            effortOverride: 'low',
+            modelOverride: model,
+            suppressSaveHook: true,
+            // Fix I1 — Esc / Ctrl+C on the parent turn stops the reader's stream.
+            signal: ctx.signal,
+        });
+    }
+    catch (err) {
+        failure = err;
+    }
+    finally {
+        // Spend counts whether or not the reader finished.
+        if (ctx.readerSpend) {
+            ctx.readerSpend.cost += computeSessionCost(childSession);
+            ctx.readerSpend.calls += 1;
+        }
+    }
+    if (failure !== null) {
+        if (ctx.signal?.aborted)
+            return { content: INTERRUPTED_LINE, is_error: true };
+        if (isNotEntitled(failure))
+            return { content: NOT_ENABLED_LINE, is_error: true };
+        const msg = failure instanceof Error ? failure.message : String(failure);
+        return { content: `error: the reader failed — ${msg.slice(0, 300)}`, is_error: true };
+    }
+    const text = collectTurnAssistantText(childSession.messages, 0).trim();
+    if (text.length === 0) {
+        return {
+            content: 'error: the reader returned no report — read the sources directly.',
+            is_error: true,
+        };
+    }
+    if (text.length <= cap)
+        return { content: text };
+    // Over the cap: the full report goes to the PARENT's spill area under the
+    // parent's tool_use id, where tool_output_read can open it.
+    const head = text.slice(0, cap);
+    const sessionId = sessionIdOf(ctx);
+    const spilled = sessionId !== undefined
+        ? spillIfLarge({ text, sessionId, toolUseId: ctx.toolUseId, kind: 'report', threshold: cap })
+        : null;
+    const where = spilled?.spilled ? ` — full report saved to ${spilled.path}` : '';
+    return { content: `${head}\n[report cut at ${cap} chars${where}]` };
+}
+registerTool({
+    name: 'read_agent',
+    description: 'Hand heavy reading to a lean read-only reader; only its short report comes back. Use it for more ' +
+        'than two source reads, a where-used scan, ATC-finding triage or a package inventory when the turn ' +
+        'will keep working afterwards. The reader has read-only SAP and file tools; it cannot write, ask the ' +
+        'user or start another reader. Give a precise brief: what to read and what to report. To hand over ' +
+        'a result you already have (ATC findings), put its saved-output path in the brief: the reader reads it ' +
+        'and never re-runs the scan. Send ' +
+        'independent readers in one response; they run at the same time.',
+    isMutating: false,
+    category: 'subagent',
+    input_schema: {
+        type: 'object',
+        properties: {
+            brief: {
+                type: 'string',
+                description: 'What to read (objects, includes, packages) and what to report. Max 4000 characters.',
+            },
+            report_max_chars: {
+                type: 'number',
+                description: 'Report length limit. Default 3000, max 6000. Longer reports are cut and saved to a file.',
+            },
+        },
+        required: ['brief'],
+    },
+    handler: (args, ctx) => readAgentHandler(args, ctx),
+});

package/dist/tools/subagent/reader-prompt.js

@@ -0,0 +1,48 @@
+/**
+ * Task 18 (model control, 2026-09-27, spec D18, ruling F8) — the reader
+ * subagent's system prompt and tool list.
+ *
+ * The PROXY owns READER_SYSTEM_PROMPT (cspeach-proxy/src/skills/
+ * reader-prompt.ts): for the skill header `_reader` it sends that constant
+ * and ignores the client's `system`. This is the CLI's pinned copy, used only
+ * where the CLI talks to a model directly (BYOK, AI-hub, local).
+ * src/tools/__tests__/reader-prompt-pin.test.ts asserts the two template
+ * literals stay byte-equal — edit both files together.
+ *
+ * No imports on purpose: tool-dispatch.ts reads READER_TOOLS, and importing
+ * read_agent.ts there would close a cycle through agent/loop.ts.
+ */
+/** The skill header a reader's model calls carry. */
+export const READER_SKILL = '_reader';
+export const READER_SYSTEM_PROMPT = `You are a read-only investigator inside CSPeach. Read exactly what the brief asks for with the tools you have, then answer the brief. Report facts with object names, includes and line numbers. Say what you could not find. No recommendations unless the brief asks. Stay under the report limit.`;
+/**
+ * The reader's fixed, small, static tool list (no deferred entries, no tool
+ * search): the ten read-only tools of spec D18 plus tool_output_read (Task
+ * 17), so a reader can open a result that was saved to a file. Every entry is
+ * `isMutating: false`. Flag-gated entries (file_read, grep, glob) reach the
+ * reader only when the session has them on, and standalone hides the SAP ones.
+ * tool-dispatch.ts refuses every other tool while `ctx.readerMode` is set.
+ */
+export const READER_TOOLS = Object.freeze([
+    'sap_get_source',
+    'sap_object_structure',
+    'sap_search_object',
+    'sap_sql_query',
+    'sap_usage_references',
+    'sap_class_includes',
+    'sap_atc_run',
+    'file_read',
+    'grep',
+    'glob',
+    'tool_output_read',
+]);
+/** Task 18 fix I1 — the result of a reader stopped by Esc / Ctrl+C (or never started). */
+export const INTERRUPTED_LINE = 'interrupted: the reader was stopped before it finished';
+/**
+ * Task 18 fix M5 — true when a reader would have at least one real read tool
+ * among `visibleNames` (tool_output_read alone reads nothing new: standalone
+ * with the file tools off). The loop hides read_agent otherwise.
+ */
+export function hasReaderReadTools(visibleNames) {
+    return READER_TOOLS.some((n) => n !== 'tool_output_read' && visibleNames.has(n));
+}

package/dist/tools/todo.js

@@ -124,7 +124,9 @@ registerTool({
         'in_progress at a time. The user sees this list — keep items short and outcome-shaped. ' +
         'Update at EVERY step transition: when you finish a step, immediately call todo_set ' +
         'marking it completed and the next step in_progress. Never batch several finished steps ' +
-        'into one later call — the user watches the ▶ indicator live.',
+        'into one later call — the user watches the ▶ indicator live. ' +
+        // Task 16 (cost profile lever 7): a lone todo_set round re-reads the whole context.
+        'Call todo_set in the same response as your next action, never as the only tool call in a response.',
     isMutating: false,
     category: 'session',
     input_schema: {