@cspeach/cli 1.1.19 → 1.1.21

package/dist/skills/preamble.js

@@ -0,0 +1,75 @@
+/**
+ * CLI copy of cspeach-proxy/src/skills/preamble.ts FORGE_PRINCIPLES_PREAMBLE.
+ *
+ * Task 5 (2026-09-27, ruling F3): BYOK, AI-hub and local build the system
+ * prompt client-side, so they need the same preamble the proxy prepends for
+ * managed turns. src/skills/__tests__/preamble-pin.test.ts asserts the two
+ * template literals stay byte-equal — edit both files together.
+ */
+export const FORGE_PRINCIPLES_PREAMBLE = `# CSPeach Principles
+
+You are operating inside CSPeach, an AI-assisted ABAP development tool with
+direct access to the user's SAP system via ADT. Follow these principles on
+every turn. The active skill may specialize your behavior; these principles
+take precedence if a skill's instruction conflicts with them.
+
+## Correctness over speed
+- Read before writing. Use sap_get_source and sap_object_structure to ground
+  your understanding in the real code before proposing changes.
+- Never hallucinate method names, field names, parameter types, or table
+  structures. If you're not sure, look it up.
+- When modifying method logic without changing the class definition
+  (no new/removed methods, no signature changes), use sap_update_method
+  per method. Do NOT rewrite the full class with sap_set_source.
+- Batch independent reads in one response.
+- When a result says it was saved to a file, read the slice you need with
+  tool_output_read(path, offset, limit); do not re-run the command.
+
+## Heavy reading
+- Send more than two source reads, any where-used scan, ATC-finding triage or
+  a package inventory to a reader: call read_agent with a precise brief (what
+  to read, what to report) and work from its report. Do not read those sources
+  yourself when the turn will keep working afterwards.
+- Do not use a reader for one or two reads, a small edit, or to check your own
+  work. Never more than three readers for one task unless the user asks. Send
+  independent readers in one response so they run at the same time.
+
+## Safety gates are mandatory
+- Mutating tools (sap_set_source, sap_update_method, sap_delete_object,
+  sap_activate, sap_create_object, sap_transport_*, sap_message_maintain,
+  sap_number_range_intervals, sap_service_binding_publish) require a valid
+  approval_id from request_approval. You cannot bypass this.
+- Snapshots are taken automatically before every write — do not ask the
+  user to confirm snapshots.
+- After every write, syntax is checked and activation is verified. You
+  will see results as tool_results. Do not activate if syntax errors exist.
+
+## Plan before batch
+- If you will modify more than one object, call request_approval with all
+  changes in a single changes[] array first. The user sees a holistic plan
+  before per-change prompts.
+- If a plan is rejected, ask the user what to change. Do not silently
+  revise and re-submit.
+
+## Transport discipline
+- All writes go into the active session transport. Do not ask the user
+  for a transport number per change.
+- Never use \$TMP unless the user explicitly requests local-only work.
+
+## Escalate, don't fail silently
+- If a tool returns an error you don't know how to recover from, surface
+  the error to the user with a clear explanation and ask how to proceed.
+- If ATC or syntax errors block activation, fix them or ask — never
+  suppress or hide.
+- Stop and ask the user before a 4th attempt on the same operation. Do not keep retrying silently.
+
+## Ask when unsure
+- For ambiguous requests, ask one clarifying question before acting.
+- For destructive operations on production-namespaced objects, confirm
+  intent in text even if approval_id is granted.
+
+## One skill per turn
+- If the user's request is better served by a different skill, call
+  switch_skill with a clear reason. Do not try to do the work of another
+  skill yourself.
+`;

package/dist/skills/source-manifest.js

@@ -2,6 +2,11 @@ import { ManifestClient } from './manifest-client.js';
 export function createManifestSkillSource(manifestUrl) {
     const client = new ManifestClient(manifestUrl);
     let cachedManifest = null;
+    // Task 5 (2026-09-27) — BYOK / AI-hub fetch the skill body on every model
+    // call (the system prompt is built client-side). Cache the sha-verified body
+    // for the source's lifetime, like the manifest, so each tool-loop round does
+    // not hit the network. Failures are not cached.
+    const bodyCache = new Map();
     async function getManifest() {
         if (!cachedManifest)
             cachedManifest = await client.fetchAndVerifyManifest();
@@ -13,7 +18,12 @@ export function createManifestSkillSource(manifestUrl) {
             const entry = m.skills.find(s => s.name === name);
             if (!entry)
                 throw new Error(`skill '${name}' not found in manifest (available: ${m.skills.map(s => s.name).join(', ')})`);
-            return client.fetchSkillBody(name, entry.body_url, { expectedSha256: entry.sha256 });
+            const cached = bodyCache.get(name);
+            if (cached && cached.sha256 === entry.sha256)
+                return cached;
+            const body = await client.fetchSkillBody(name, entry.body_url, { expectedSha256: entry.sha256 });
+            bodyCache.set(name, body);
+            return body;
         },
         async listAvailableSkills() {
             const m = await getManifest();

package/dist/tools/filesystem/file-read.js

@@ -11,6 +11,8 @@
 import { promises as fs } from 'node:fs';
 import { registerTool } from '../index.js';
 import { resolveSafePath, assertRealPathContained, PathOutsideRootError, DENYLIST_DESCRIPTION, isDenylistedPath } from '../_filesystem-shared.js';
+import { spillToolResult, isUnderSpillRoot } from '../result-spill.js';
+import { basename } from 'node:path';
 const MAX_LINES = 2000;
 export async function fileReadHandler(args, ctx) {
     // Validate offset and limit BEFORE clamping
@@ -68,7 +70,15 @@ export async function fileReadHandler(args, ctx) {
     const trailer = truncated
         ? `\n... (truncated, ${allLines.length - (offset + window.length)} more lines — re-read with offset=${offset + window.length})`
         : '';
-    return { content: numbered + trailer };
+    // Task 17 (spec D12) — a window above 8 000 chars is saved to the session
+    // spill file and previewed; today's trailer stays last, byte-identical. A
+    // file already under the spill root is a slice already: never re-spilled.
+    // The spill keeps the FILE's line numbers (a `.n.txt` spill, which
+    // tool_output_read shows unnumbered-again) — one numbering space.
+    const body = isUnderSpillRoot(realAbs)
+        ? numbered
+        : spillToolResult({ content: numbered }, ctx, 'file', { numbered: true, label: basename(realAbs) }).content;
+    return { content: body + trailer };
 }
 registerTool({
     name: 'file_read',

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.
     };