@cspeach/cli 0.6.0

package/dist/tools/shell/shell_exec.js

@@ -0,0 +1,209 @@
+/**
+ * shell_exec — Phase 3 / Chunk 3B shell tool.
+ *
+ * Runs a hardcoded safelist of build / VCS commands via argv arrays —
+ * NO shell parser ever involved. Default safelist: npm, pnpm, ui5,
+ * cds, git, abaplint, node. User extends via the
+ *   [shell_exec]
+ *   allow = ["docker", "make"]
+ * block in ~/.cspeach/config.toml.
+ *
+ * Cross-platform: on Windows resolves the .cmd / .bat / .exe shim
+ * via PATH walk before spawning (Node's spawn with shell:false can't
+ * directly invoke .cmd files; using shell:true reopens shell-injection
+ * + CVE-2024-27980). On Unix the bare name is passed straight through
+ * — spawn finds it on PATH.
+ *
+ * Operational caps:
+ *   - 30 s wall-clock timeout (overridable up to 300 s via timeout_ms arg)
+ *   - 1 MB per-stream output cap (stdout + stderr each)
+ *   - cwd resolved through resolveSafePath — no escape
+ *   - env scrubbed: only PATH, HOME, USERPROFILE, TEMP, TMP, SystemRoot,
+ *     windir, Path pass through. CSPEACH_*, ANTHROPIC_*, SAP_* never leak.
+ *
+ * Flag-gated: invisible to listTools() unless CSPEACH_TOOL_SHELL_EXEC=on.
+ * isMutating: true — hooks into the existing approval gate.
+ */
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+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';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_TIMEOUT_MS = 300_000;
+const MAX_OUTPUT_BYTES = 1_000_000; // per stream
+export async function shellExecHandler(args, ctx) {
+    if (!args.command || typeof args.command !== 'string') {
+        return { content: 'error: command is required (non-empty string)', is_error: true };
+    }
+    if (args.cwd !== undefined && typeof args.cwd !== 'string') {
+        return { content: 'error: cwd must be a string when provided', is_error: true };
+    }
+    if (args.timeout_ms !== undefined && typeof args.timeout_ms !== 'number') {
+        return { content: 'error: timeout_ms must be a number when provided', is_error: true };
+    }
+    const argv = Array.isArray(args.args) ? args.args.filter((a) => typeof a === 'string') : [];
+    const argvErr = validateArgv(argv);
+    if (argvErr !== null)
+        return { content: `error: ${argvErr}`, is_error: true };
+    // Reject absolute paths and any name containing a path separator. This
+    // ensures the safelist check is meaningful — the model can't pass
+    // /bin/sh or C:\Windows\System32\cmd.exe just because its basename is
+    // safelisted (and it isn't, but the rule is "bare name only").
+    const sepErr = rejectPathSeparator(args.command);
+    if (sepErr !== null)
+        return { content: `error: ${sepErr}`, is_error: true };
+    const safelist = await loadSafelist();
+    if (!safelist.has(args.command)) {
+        return {
+            content: `error: command "${args.command}" is not in the safelist. allowed: ${[...safelist].sort().join(', ')}. extend via [shell_exec] allow = [...] in ~/.cspeach/config.toml.`,
+            is_error: true,
+        };
+    }
+    let cwd;
+    try {
+        cwd = args.cwd ? resolveSafePath(ctx.cwd, args.cwd) : path.resolve(ctx.cwd);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError) {
+            return { content: `error: ${err.message}`, is_error: true };
+        }
+        return { content: `error: ${err instanceof Error ? err.message : String(err)}`, is_error: true };
+    }
+    try {
+        const stat = await fs.stat(cwd);
+        if (!stat.isDirectory()) {
+            return { content: `error: cwd "${args.cwd ?? '.'}" is not a directory`, is_error: true };
+        }
+    }
+    catch {
+        return { content: `error: cwd "${args.cwd ?? '.'}" does not exist`, is_error: true };
+    }
+    const resolved = await resolveExecutable(args.command);
+    if (resolved === null) {
+        return {
+            content: `error: command "${args.command}" not installed on this system (not found on PATH).`,
+            is_error: true,
+        };
+    }
+    const timeoutMs = Math.min(Math.max(typeof args.timeout_ms === 'number' && args.timeout_ms > 0 ? args.timeout_ms : DEFAULT_TIMEOUT_MS, 1_000), MAX_TIMEOUT_MS);
+    return await new Promise((resolve) => {
+        let stdoutBuf = '';
+        let stderrBuf = '';
+        let stdoutTrunc = false;
+        let stderrTrunc = false;
+        let settled = false;
+        let timedOut = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        const child = spawn(resolved, argv, {
+            cwd,
+            env: buildSafeEnv(),
+            windowsHide: true,
+            shell: false,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        child.stdout?.on('data', (chunk) => {
+            const remaining = MAX_OUTPUT_BYTES - stdoutBuf.length;
+            if (remaining <= 0) {
+                stdoutTrunc = true;
+                return;
+            }
+            const text = chunk.toString('utf-8');
+            if (text.length <= remaining)
+                stdoutBuf += text;
+            else {
+                stdoutBuf += text.slice(0, remaining);
+                stdoutTrunc = true;
+            }
+        });
+        child.stderr?.on('data', (chunk) => {
+            const remaining = MAX_OUTPUT_BYTES - stderrBuf.length;
+            if (remaining <= 0) {
+                stderrTrunc = true;
+                return;
+            }
+            const text = chunk.toString('utf-8');
+            if (text.length <= remaining)
+                stderrBuf += text;
+            else {
+                stderrBuf += text.slice(0, remaining);
+                stderrTrunc = true;
+            }
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                child.kill('SIGTERM');
+            }
+            catch { /* ignore */ }
+            setTimeout(() => {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { /* ignore */ }
+            }, KILL_GRACE_MS).unref();
+        }, timeoutMs);
+        timer.unref();
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            settle({ content: `error: spawn failed — ${err.message}`, is_error: true });
+        });
+        child.on('close', (code, signal) => {
+            clearTimeout(timer);
+            if (timedOut) {
+                const tail = (stdoutBuf ? `stdout (partial):\n${stdoutBuf}\n${stdoutTrunc ? '[truncated]\n' : ''}` : '') +
+                    (stderrBuf ? `stderr (partial):\n${stderrBuf}\n${stderrTrunc ? '[truncated]\n' : ''}` : '');
+                settle({
+                    content: `error: command timed out after ${timeoutMs} ms — child killed.\n${tail}`,
+                    is_error: true,
+                });
+                return;
+            }
+            const stdoutSection = `stdout:\n${stdoutBuf}${stdoutTrunc ? '\n[truncated — exceeded 1 MB cap]' : ''}`;
+            const stderrSection = `stderr:\n${stderrBuf}${stderrTrunc ? '\n[truncated — exceeded 1 MB cap]' : ''}`;
+            const exitSection = `exit code: ${code ?? 'null'}${signal ? ` (signal: ${signal})` : ''}`;
+            settle({ content: `${stdoutSection}\n\n${stderrSection}\n\n${exitSection}` });
+        });
+    });
+}
+registerTool({
+    name: 'shell_exec',
+    description: 'Run a safelisted shell command (argv only — no shell parser). Default safelist: ' +
+        [...DEFAULT_SAFELIST].sort().join(', ') +
+        '. User extends via [shell_exec] allow = [...] in ~/.cspeach/config.toml. ' +
+        '30s default timeout (overridable up to 300s), 1 MB per-stream output cap. ' +
+        'Returns stdout, stderr, and exit code in separate sections.',
+    isMutating: true,
+    category: 'shell',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            command: {
+                type: 'string',
+                description: 'Bare command name (e.g. "npm", "git"). No paths. No absolute paths. Must appear in the safelist.',
+            },
+            args: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'argv array passed literally to the child. No shell parsing — metacharacters are inert.',
+            },
+            cwd: {
+                type: 'string',
+                description: 'Optional working directory relative to project root. Must resolve inside the project.',
+            },
+            timeout_ms: {
+                type: 'number',
+                description: 'Wall-clock timeout in ms. Default 30000, min 1000, max 300000.',
+            },
+        },
+        required: ['command'],
+    },
+    handler: shellExecHandler,
+});

package/dist/tools/snapshot.js

@@ -0,0 +1,107 @@
+/**
+ * Snapshot tools + autoSnapshot helper.
+ *
+ * Four registered tools (all isMutating: false — local-FS operations):
+ *   sap_snapshot_take    — take a snapshot before write (or on-demand)
+ *   sap_snapshot_list    — list snapshots for a type/name (or all)
+ *   sap_snapshot_read    — read raw source from a specific snapshot
+ *   sap_snapshot_cleanup — delete snapshots older than retentionHours
+ *
+ * Confirmed snapshots signatures (sap-client/src/safety/snapshots.ts):
+ *   take(type, name, source, reason?) → Promise<SnapshotEntry>
+ *   list(type?, name?)                → Promise<SnapshotEntry[]>
+ *   read(type, name, snapshotId)      → Promise<string>
+ *   cleanup(retentionHours?)          → Promise<number>
+ */
+import { registerTool } from './index.js';
+import { snapshots } from '@cspeach/sap-client';
+registerTool({
+    name: 'sap_snapshot_take',
+    description: "Take a snapshot of an object's current source before modification. Usually invoked automatically by the CLI before any write — rarely called directly by the model.",
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string', description: 'ABAP object name' },
+            type: { type: 'string', description: 'ABAP object type (PROG, CLAS, etc.)' },
+        },
+        required: ['name', 'type'],
+    },
+    handler: async (args, ctx) => {
+        const source = await ctx.adt.getSource(args.type, args.name).catch(() => null);
+        if (source === null) {
+            return { content: JSON.stringify({ skipped: true, reason: 'object_not_found' }) };
+        }
+        const entry = await snapshots.take(args.type, args.name, source, 'manual');
+        return { content: JSON.stringify({ snapshot: entry, size: source.length }) };
+    },
+});
+/**
+ * Auto-snapshot helper called by write tools before mutating an object.
+ * Silently skips if the object does not exist yet (first write after create).
+ *
+ * snapshots.take expects (type, name, source, reason).
+ */
+export async function autoSnapshot(objectName, objectType, adt) {
+    const src = await adt.getSource(objectType, objectName).catch(() => null);
+    if (src === null)
+        return; // new object — nothing to snapshot
+    await snapshots.take(objectType, objectName, src, 'before_write');
+}
+// ── sap_snapshot_list ─────────────────────────────────────────────────────────
+registerTool({
+    name: 'sap_snapshot_list',
+    description: 'List available snapshots. Pass type and name to filter by object; omit both to list all snapshots.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            type: { type: 'string', description: 'ABAP object type filter (optional)' },
+            name: { type: 'string', description: 'ABAP object name filter (optional)' },
+        },
+        required: [],
+    },
+    handler: async (args, _ctx) => {
+        const entries = await snapshots.list(args.type, args.name);
+        return { content: JSON.stringify(entries) };
+    },
+});
+// ── sap_snapshot_read ─────────────────────────────────────────────────────────
+registerTool({
+    name: 'sap_snapshot_read',
+    description: 'Read the raw source text from a specific snapshot. Use sap_snapshot_list first to find the snapshotId.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            type: { type: 'string', description: 'ABAP object type (PROG, CLAS, etc.)' },
+            name: { type: 'string', description: 'ABAP object name' },
+            snapshotId: { type: 'string', description: 'Snapshot file id from sap_snapshot_list' },
+        },
+        required: ['type', 'name', 'snapshotId'],
+    },
+    handler: async (args, _ctx) => {
+        const source = await snapshots.read(args.type, args.name, args.snapshotId);
+        return { content: source };
+    },
+});
+// ── sap_snapshot_cleanup ──────────────────────────────────────────────────────
+registerTool({
+    name: 'sap_snapshot_cleanup',
+    description: 'Delete snapshots older than retentionHours (default 168 = 7 days). Returns count of deleted snapshots.',
+    isMutating: false,
+    input_schema: {
+        type: 'object',
+        properties: {
+            retentionHours: {
+                type: 'number',
+                description: 'Delete snapshots older than this many hours (default: 168)',
+            },
+        },
+        required: [],
+    },
+    handler: async (args, _ctx) => {
+        const count = await snapshots.cleanup(args.retentionHours);
+        return { content: JSON.stringify({ deleted: count }) };
+    },
+});

package/dist/tools/subagent/_background-shared.js

@@ -0,0 +1,133 @@
+// cspeach-cli/src/tools/subagent/_background-shared.ts
+/**
+ * Phase 3 / Chunk 3E — in-memory background-process registry.
+ *
+ * background_run writes here; monitor_emit reads + consumes from here.
+ *
+ * Per-bg ring buffer with FIFO eviction at MAX_EVENTS_PER_BG. Each
+ * consume call reports a `dropped` counter when events were evicted
+ * before being read; the counter resets on consume so the agent can
+ * tell "events were lost since my last call" without per-call drift.
+ *
+ * Per-process only — never persisted. Two CLI instances on the same
+ * machine each have their own registry; no IPC. This is deliberate:
+ * the lifetime of a bg_id is bounded by the CLI process it was
+ * spawned in.
+ *
+ * Exit handler installed exactly once via installExitHandler(). When
+ * Node exits (normal or signal), every tracked child is SIGTERMd, then
+ * SIGKILLd after KILL_GRACE_MS ms. Both timers .unref() so they don't
+ * keep Node alive past the legitimate shutdown.
+ */
+import { KILL_GRACE_MS } from '../_command-shared.js';
+export const MAX_EVENTS_PER_BG = 10_000;
+const registry = new Map();
+let exitHandlerInstalled = false;
+export function registerBackground(p) {
+    const entry = {
+        bg_id: p.bg_id,
+        command: p.command,
+        argv: p.argv,
+        child: p.child,
+        startedAt: Date.now(),
+        closed: false,
+        exitCode: null,
+        signal: null,
+        events: [],
+        pendingDropped: 0,
+    };
+    registry.set(p.bg_id, entry);
+    return entry;
+}
+export function getBackground(bg_id) {
+    return registry.get(bg_id);
+}
+/**
+ * Append an event to the bg_id's ring buffer. FIFO-evicts the oldest
+ * entry once length reaches MAX_EVENTS_PER_BG; the eviction count is
+ * surfaced via ConsumeResult.dropped on the next consumeEvents() call.
+ *
+ * No-op if the bg_id is unknown (the consumer cleared the entry between
+ * the child's emission and this call). The dropped data is accepted as
+ * lost — spec contract, not a bug.
+ */
+export function recordEvent(bg_id, ev) {
+    const entry = registry.get(bg_id);
+    if (!entry)
+        return; // race: child wrote after consumeAndClear; silently drop
+    if (entry.events.length >= MAX_EVENTS_PER_BG) {
+        // We push AFTER the eviction, so free one extra slot to land at exactly MAX.
+        const drop = entry.events.length - MAX_EVENTS_PER_BG + 1;
+        entry.events.splice(0, drop);
+        entry.pendingDropped += drop;
+    }
+    entry.events.push(ev);
+    if (ev.kind === 'exit' && !entry.closed) {
+        entry.closed = true;
+        entry.exitCode = ev.exitCode ?? null;
+        entry.signal = ev.signal ?? null;
+    }
+}
+export function consumeEvents(bg_id, max) {
+    const entry = registry.get(bg_id);
+    if (!entry)
+        return null;
+    const events = entry.events.splice(0, max);
+    const dropped = entry.pendingDropped;
+    entry.pendingDropped = 0;
+    return {
+        events,
+        dropped,
+        closed: entry.closed,
+        exitCode: entry.exitCode,
+        signal: entry.signal,
+    };
+}
+/** Idempotent. Subsequent calls are silent no-ops. */
+export function installExitHandler() {
+    if (exitHandlerInstalled)
+        return;
+    exitHandlerInstalled = true;
+    // 'exit' fires synchronously during Node shutdown. Best-effort SIGTERM
+    // each tracked child; the SIGKILL escalation timer cannot fire from
+    // inside an 'exit' handler (event-loop is shutting down) so we
+    // additionally hook SIGINT/SIGTERM/SIGHUP below for graceful paths
+    // where the loop is still alive.
+    process.on('exit', () => {
+        for (const entry of registry.values()) {
+            if (!entry.closed) {
+                try {
+                    entry.child.kill('SIGTERM');
+                }
+                catch { /* ignore */ }
+            }
+        }
+    });
+    for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+        process.on(sig, () => {
+            for (const entry of registry.values()) {
+                if (!entry.closed) {
+                    try {
+                        entry.child.kill('SIGTERM');
+                    }
+                    catch { /* ignore */ }
+                    const t = setTimeout(() => {
+                        try {
+                            entry.child.kill('SIGKILL');
+                        }
+                        catch { /* ignore */ }
+                    }, KILL_GRACE_MS);
+                    t.unref();
+                }
+            }
+        });
+    }
+}
+/** Test-only — clears registry between cases. Does NOT uninstall the exit handler (handler is process-lifetime-scoped). */
+export function __resetRegistryForTests() {
+    registry.clear();
+}
+/** Test-only — observe whether installExitHandler has fired. */
+export function __isExitHandlerInstalledForTests() {
+    return exitHandlerInstalled;
+}

package/dist/tools/subagent/agent_run.js

@@ -0,0 +1,186 @@
+// cspeach-cli/src/tools/subagent/agent_run.ts
+/**
+ * agent_run — Phase 3 / Chunk 3E.
+ *
+ * Dispatches a sub-task to a fresh runTurn invocation with an isolated
+ * SessionState. Same process; isolated session — matches Decision 4
+ * (RESOLVED 2026-05-10) and Claude Code's Agent-tool semantics.
+ *
+ * Guards:
+ *   - CSPEACH_AGENT_DEPTH env var enforces a hard depth cap of
+ *     MAX_AGENT_DEPTH=3. Up to 3 nested agent_run invocations are
+ *     allowed in a single recursion chain (parent dispatches child at
+ *     depth 0→1, child can dispatch grandchild at 1→2, grandchild can
+ *     dispatch great-grandchild at 2→3; the next call at depth 3 is
+ *     refused). Bounds token cost in the worst case.
+ *   - Per-call max_tokens default DEFAULT_MAX_TOKENS=100_000, hard
+ *     cap HARD_MAX_TOKENS=200_000.
+ *   - `skill` arg is REQUIRED; no free-form subagent.
+ *   - `previewHook` is intentionally absent from the child ctx —
+ *     subagent cannot auto-approve writes.
+ *   - Subagent stdout is suppressed via a null-sink EventEmitter —
+ *     subagent text is captured into the return envelope, but doesn't
+ *     pollute the parent's REPL.
+ *
+ * Flag-gated: invisible to listTools() unless
+ * CSPEACH_TOOL_AGENT_RUN=on. isMutating: false (the subagent ITSELF may
+ * call mutating tools — but those go through their own approval gates).
+ */
+import { EventEmitter } from 'node:events';
+import { registerTool } from '../index.js';
+import { runTurn } from '../../agent/loop.js';
+import { collectTurnAssistantText } from '../../agent/turn-assistant-text.js';
+export const MAX_AGENT_DEPTH = 3;
+export const DEFAULT_MAX_TOKENS = 100_000;
+export const HARD_MAX_TOKENS = 200_000;
+// Same NAME_PATTERN shape playbook_get uses — alphanumerics + `:_-`, ≤64.
+const SKILL_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9:_-]{0,63}$/;
+export async function agentRunHandler(args, ctx) {
+    if (!args.skill || typeof args.skill !== 'string' || args.skill.trim().length === 0) {
+        return { content: "error: 'skill' is required (non-empty string).", is_error: true };
+    }
+    if (!SKILL_NAME_PATTERN.test(args.skill)) {
+        return { content: `error: invalid skill name '${args.skill}'. Names must match ${SKILL_NAME_PATTERN.source}.`, is_error: true };
+    }
+    if (!args.task || typeof args.task !== 'string' || args.task.trim().length === 0) {
+        return { content: "error: 'task' is required (non-empty string).", is_error: true };
+    }
+    if (!ctx.provider) {
+        return {
+            content: 'error: agent_run requires ctx.provider — not wired into this ToolContext. ' +
+                'This is a CSPeach internal wiring issue; the REPL and one-shot entry points provide one automatically.',
+            is_error: true,
+        };
+    }
+    if (!ctx.skillSource) {
+        return {
+            content: 'error: agent_run requires ctx.skillSource — not wired into this ToolContext. ' +
+                'This is a CSPeach internal wiring issue; the REPL and one-shot entry points provide one automatically.',
+            is_error: true,
+        };
+    }
+    // Depth guard — read BEFORE incrementing.
+    const currentDepth = Number.parseInt(process.env.CSPEACH_AGENT_DEPTH ?? '0', 10);
+    const depth = Number.isFinite(currentDepth) && currentDepth >= 0 ? currentDepth : 0;
+    if (depth >= MAX_AGENT_DEPTH) {
+        return {
+            content: `error: subagent depth cap reached (${depth} >= ${MAX_AGENT_DEPTH}). ` +
+                `Refusing further recursion to bound token cost. The parent agent should ` +
+                `complete this task itself rather than nest another subagent.`,
+            is_error: true,
+        };
+    }
+    // Token cap.
+    const maxTokensFloored = typeof args.max_tokens === 'number' && Number.isFinite(args.max_tokens)
+        ? Math.floor(args.max_tokens)
+        : 0;
+    const maxTokensRaw = maxTokensFloored > 0 ? maxTokensFloored : DEFAULT_MAX_TOKENS;
+    const maxTokensOverride = Math.min(maxTokensRaw, HARD_MAX_TOKENS);
+    // Build an isolated child SessionState. Fresh empty messages array;
+    // fresh session.id so saveSession (called by runTurn after each tool
+    // result) cannot collide with the parent's session file.
+    // `as any` casts: SessionState has many fields the child doesn't strictly
+    // need; spreading from parent + overriding id/messages/toolCalls/usage is
+    // the smallest reasonable contract. TypeScript can't express "subset of
+    // SessionState that runTurn actually reads" cleanly.
+    const childSession = {
+        ...ctx.session,
+        id: `subagent-${Date.now()}-${Math.floor(Math.random() * 1e9).toString(16)}`,
+        messages: [],
+        toolCalls: [],
+        // I1 fix: clone usage so child mutations don't inflate parent counters.
+        // loop.ts mutates session.usage during the LLM stream; a shared reference
+        // would corrupt the parent's per-turn delta calculations.
+        usage: ctx.session?.usage
+            ? { ...ctx.session.usage }
+            : { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0 },
+        // Cosmetic: child's started_at should reflect when it actually started,
+        // not parent's start time. Avoids surprising file timestamps.
+        started_at: new Date().toISOString(),
+        last_turn_at: new Date().toISOString(),
+    };
+    // Build an isolated child ctx. Crucial differences vs parent ctx:
+    //   - session: the fresh child session above (independent usage counters)
+    //   - previewHook: undefined — subagent must NOT auto-approve writes
+    //   - pendingDispatch / currentTransport: cleared — subagent doesn't
+    //     mutate parent REPL state
+    // chunkEmitter is passed via the RunTurn params (not the ctx) as a
+    // null-sink EventEmitter — see I2 fix below.
+    const childCtx = {
+        adt: ctx.adt,
+        sapAlias: ctx.sapAlias,
+        session: childSession,
+        cwd: ctx.cwd,
+        provider: ctx.provider,
+        skillSource: ctx.skillSource,
+        // previewHook + pendingDispatch + currentTransport intentionally omitted.
+    };
+    // I2 fix: a null-sink EventEmitter suppresses all subagent output. Every
+    // stdout-write site in loop.ts is guarded by `if (params.chunkEmitter)`,
+    // and emit() to a listener-less emitter is a no-op. Result: subagent text
+    // flows into childSession.messages (where collectTurnAssistantText reads it)
+    // but never reaches the user's terminal or the parent's Ink renderer.
+    const nullSinkEmitter = new EventEmitter();
+    // Increment depth env var BEFORE the child runs; restore after.
+    const priorDepth = process.env.CSPEACH_AGENT_DEPTH;
+    process.env.CSPEACH_AGENT_DEPTH = String(depth + 1);
+    try {
+        await runTurn({
+            provider: ctx.provider,
+            userMessage: args.task,
+            skill: args.skill,
+            ctx: childCtx,
+            chunkEmitter: nullSinkEmitter,
+            maxTokensOverride,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: `error: subagent failed — ${msg}`, is_error: true };
+    }
+    finally {
+        if (priorDepth === undefined)
+            delete process.env.CSPEACH_AGENT_DEPTH;
+        else
+            process.env.CSPEACH_AGENT_DEPTH = priorDepth;
+    }
+    const childText = collectTurnAssistantText(childSession.messages, 0);
+    if (childText.trim().length === 0) {
+        return {
+            content: 'subagent completed without emitting assistant text (no useful answer to return).',
+            is_error: false,
+        };
+    }
+    return { content: childText };
+}
+registerTool({
+    name: 'agent_run',
+    description: 'Dispatch a focused sub-task to a fresh subagent loop in the SAME process with an ISOLATED ' +
+        'session. The child runs the named skill against the given task and returns its final ' +
+        'assistant text. Depth-capped at 3 levels; default max_tokens 100000 (cap 200000). The ' +
+        'subagent inherits adt + skillSource + provider but NOT previewHook — subagent cannot ' +
+        'auto-approve mutating writes. A null-sink emitter is passed for chunkEmitter so subagent ' +
+        'output stays out of the parent UI.',
+    isMutating: false,
+    category: 'subagent',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            skill: {
+                type: 'string',
+                description: 'Required. Skill name the subagent runs in (e.g. "abap-review"). No leading slash.',
+            },
+            task: {
+                type: 'string',
+                description: 'Required. The user-message-equivalent the subagent receives.',
+            },
+            max_tokens: {
+                type: 'number',
+                description: 'Optional per-call cap. Default 100000, hard cap 200000.',
+            },
+        },
+        required: ['skill', 'task'],
+    },
+    handler: (args, ctx) => agentRunHandler(args, ctx),
+});