berry-agent 0.1.0-alpha.1

package/dist/host/settings-store.js

@@ -0,0 +1,112 @@
+/**
+ * host/settings-store — 数据目录用户配置文件 `<dataDir>/settings.json` 读写件
+ * （04 §9 定形块⑥·M3 兜缝——2026-09-11 审批分档批 ap-3）。
+ *
+ * 定位：sandbox 缺省档**持久用户配置层**——§8 三级解析挂第四层的载体：
+ * 工具参数 > 会话策略 > CLI 旗标（逐次） > **本文件（持久缺省）** > 代码常量。
+ * 持久位不覆盖逐次显式位（装配根做 gaps 填充，run-entry 只传显式胜者）。
+ *
+ * 两键面（本批定形）：`sandboxMode?` / `approvalPolicy?`——预设展开的持久
+ * 缺省位；**非敏感件**（两旋钮无秘密，不入 SENSITIVE_READ_BASENAMES——
+ * 模型可读面不设防，恰三件敏感清单测试锁不动）。
+ *
+ * 读写纪律（与 tool-policy-store 同族——「文件即用户资产」律）：
+ * - 读侧缺席 = {}（零负担首启）；文件级坏 JSON = warn 降级 {}（配置层坏形
+ *   取缺省 = 现状常量，非 fail-stop 面）；键级坏值 = 忽略该键 + warn 点名
+ *   （好键照常生效）；未知键 = warn 不动文件（人可手编他键，机器不覆写）。
+ * - 写侧**合并保留未知键**（预设写盘只动两键，用户手编的其他键原样存活）；
+ *   原子替换（tmp + rename——防撕裂）；坏形期拒写（'rejected'——与
+ *   appendToolPolicyEntry 同律，机器不在坏文件上覆写扩大破坏）。
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** 配置文件名（数据目录单段——04 §9 ⑥「本批定名」） */
+export const SETTINGS_BASENAME = 'settings.json';
+const SANDBOX_MODES = ['read-only', 'workspace-write', 'danger'];
+const APPROVAL_POLICIES = ['ask', 'never'];
+/**
+ * 装配期读用户配置（缺席 {} 零负担；坏 JSON 降级 {} + unhealthy；键级坏值
+ * 忽略点名、未知键 warn 不动文件）。
+ */
+export function readHostSettings(dataDir, options = {}) {
+    const warn = options.warn ?? ((message) => process.stderr.write(`${message}\n`));
+    const path = join(dataDir, SETTINGS_BASENAME);
+    if (!existsSync(path))
+        return { settings: {}, healthy: true };
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        warn(`配置读取失败（${path}）：${err instanceof Error ? err.message : String(err)}——视同缺席`);
+        return { settings: {}, healthy: false };
+    }
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch (err) {
+        warn(`配置坏形（${path}，JSON 解析失败：${err instanceof Error ? err.message : String(err)}）——视同缺席；手改修复前回写拒（防机器覆写扩大破坏）`);
+        return { settings: {}, healthy: false };
+    }
+    if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) {
+        warn(`配置坏形（${path}，顶层须为对象）——视同缺席；手改修复前回写拒`);
+        return { settings: {}, healthy: false };
+    }
+    // 键级校验：两键值域闭集外忽略点名；未知键 warn 保留不动（读侧不区分
+    // 「保留在内存」与否——本面只产两键，未知键经写侧合并律存活）
+    const record = doc;
+    const { sandboxMode, approvalPolicy, ...rest } = record;
+    const unknownKeys = Object.keys(rest);
+    if (unknownKeys.length > 0) {
+        warn(`配置含未知键 ${unknownKeys.join('、')}（${path}）——本面不消费、保留不动`);
+    }
+    const settings = {};
+    if (sandboxMode !== undefined) {
+        if (typeof sandboxMode === 'string' && SANDBOX_MODES.includes(sandboxMode)) {
+            settings.sandboxMode = sandboxMode;
+        }
+        else {
+            warn(`配置键 sandboxMode 值域外（read-only|workspace-write|danger）——忽略该键`);
+        }
+    }
+    if (approvalPolicy !== undefined) {
+        if (typeof approvalPolicy === 'string' && APPROVAL_POLICIES.includes(approvalPolicy)) {
+            settings.approvalPolicy = approvalPolicy;
+        }
+        else {
+            warn(`配置键 approvalPolicy 值域外（ask|never）——忽略该键`);
+        }
+    }
+    return { settings, healthy: true };
+}
+/**
+ * 写侧合并面：**只动两键**（在场键落值、缺席键不动现状——预设展开只写该
+ * 预设携带的旋钮），未知键原样保留（用户手编面不因预设切换损毁）；原子
+ * 替换落盘（tmp + rename）；文件级坏形期拒写。
+ */
+export function writeHostSettings(dataDir, patch, options = {}) {
+    // 坏形拒写第一闸：复用读侧全套校验（在坏文件上合并 = 覆写扩大破坏）
+    const load = readHostSettings(dataDir, options);
+    if (!load.healthy)
+        return 'rejected';
+    // 合并基 = 原文件解析出的全键形（含未知键——保留律）。重读一次拿未剥离
+    // 的原始对象（readHostSettings 产物只含两键，未知键需原始面承载）
+    const path = join(dataDir, SETTINGS_BASENAME);
+    let base = {};
+    if (existsSync(path)) {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed))
+            base = parsed;
+    }
+    const next = { ...base };
+    if (patch.sandboxMode !== undefined)
+        next.sandboxMode = patch.sandboxMode;
+    if (patch.approvalPolicy !== undefined)
+        next.approvalPolicy = patch.approvalPolicy;
+    mkdirSync(dataDir, { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    renameSync(tmp, path);
+    return 'written';
+}

package/dist/host/signals.js

@@ -0,0 +1,69 @@
+/**
+ * host/signals — 进程编舞（04 §1 信号与退出序；批 12c）。
+ *
+ * 信号序：SIGINT① → 触发优雅序（04 §1 六步——由调用方注入的 onGraceful
+ * 承载：runtime.shutdown 即 ①abort→②closer drain→③flush→④hooks→⑤LIFO）；
+ * 优雅窗内 SIGINT② → 立即退 130（第二次按键 = 用户明示放弃优雅）；SIGTERM
+ * 同 SIGINT①（serve stop 的进程外管理动词必经 TERM——幂等重入不另起第二套
+ * 停机编舞）。崩溃路径：未捕获异常先同步写 crash.log 再退（退 1 执行失败
+ * 档）；unhandledRejection 同律处置（裁量钉位：Node 缺省会升格为
+ * uncaughtException，显式接住 = fail-loud 且报文带「未处理拒绝」指向根因）。
+ *
+ * 全注入可测：信号注册（register）/ 终局（exit）均注——测试位收调用序，
+ * main 装配位接 process.on/process.exit。
+ */
+/**
+ * 装配信号编舞（main 装配位调用一次）。
+ *
+ * 状态机：quiet →（SIGINT①/SIGTERM）→ draining →（SIGINT②）→ 立即 130。
+ * SIGTERM 在 draining 态幂等直返（优雅序只起一次）；SIGINT② 只认 draining
+ * 态的第二次按键。
+ */
+export function installSignalChoreography(options) {
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const register = options.register ?? ((signal, listener) => process.on(signal, listener));
+    let draining = false; // 优雅序在飞位（SIGTERM 幂等 / SIGINT② 判据）
+    let terminated = false; // 终局幂等位（镜像 process.exit——已退则迟到链不再终局）
+    const finish = (code) => {
+        if (terminated)
+            return;
+        terminated = true;
+        exit(code);
+    };
+    register('SIGINT', () => {
+        if (!draining) {
+            draining = true;
+            void options
+                .onGraceful()
+                .then((code) => finish(code ?? 0))
+                .catch(() => finish(1)); // 优雅序自身抛错 = 执行失败档收场
+            return;
+        }
+        finish(130); // 第二次按键——明示放弃优雅，立即退
+    });
+    register('SIGTERM', () => {
+        if (draining)
+            return; // 已在优雅序——幂等直返（不另起第二套停机）
+        draining = true;
+        void options
+            .onGraceful()
+            .then((code) => finish(code ?? 0))
+            .catch(() => finish(1));
+    });
+}
+/**
+ * 装配崩溃编舞：未捕获异常/未处理拒绝 → 先同步写 crash.log 再退 1。
+ *
+ * 取证写失败不再拦退（崩溃路径唯一允许的静默归 writeCrashLog 实现侧）；
+ * 退码 1 = 执行失败档（04 §1 退出序不预设崩溃退码，07 §5 三态归档裁量）。
+ */
+export function installCrashChoreography(options) {
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const register = options.register ?? ((event, listener) => process.on(event, listener));
+    const handle = (error) => {
+        options.writeCrashLog(error); // 同步先写（进程生命周期取证）
+        exit(1);
+    };
+    register('uncaughtException', handle);
+    register('unhandledRejection', (reason) => handle(reason instanceof Error ? reason : new Error(`未处理拒绝：${String(reason)}`)));
+}

package/dist/host/single-instance.js

@@ -0,0 +1,105 @@
+/**
+ * host/single-instance — 单活跃机执法件（05 篇 §6.6；04 §1 运行时侧语义）。
+ *
+ * 同一数据目录同一时刻恰一活跃进程：启动即写活跃标记（pid + 启动时戳），
+ * 二次启动标记在场且 pid 活 → `HOST_DATA_DIR_BUSY` 拒入；pid 死 → 接管
+ * （陈旧标记清理后覆写）。serve 宿主（含 --daemon）是合法持有者——标记语义
+ * 对 TUI/serve 两宿主同形；daemon 猝死 = 标记随进程亡，下次启动 pid 判死后
+ * 接管（既有语义零新增）。豁免面（只读诊断/管理动词）由调用方裁——本件只
+ * 提供 acquire/release 原语不预判豁免。
+ *
+ * 裁量钉位（规范未明文、本笔定形）：标记文件名 `active.json`（05 §6.6 只钉
+ * 「数据目录下活跃标记文件（pid + 启动时戳）」未定名）；记录形
+ * `{ pid, startedAt }` 单 JSON 行。
+ */
+import { readFileSync, unlinkSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { BaseError } from '../contracts/index.js';
+/** 活跃标记文件名（数据目录下——本笔裁量钉位） */
+export const ACTIVE_MARKER_BASENAME = 'active.json';
+/** acquire 失败面——标记在场且 pid 活（拒入；不打既有进程——fail-loud 不执法） */
+export class DataDirBusyError extends BaseError {
+    constructor(busy) {
+        super('HOST_DATA_DIR_BUSY', `数据目录已有活跃进程（pid ${busy.pid}，启动于 ${new Date(busy.startedAt).toISOString()}）——同一数据目录同一时刻恰一活跃进程；如确系残留标记且该 pid 已死会自动接管`);
+    }
+}
+/** 进程探活缺省实现：信号 0 探测（ESRCH = 死；EPERM = 活但非属主——按活计） */
+function defaultIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/**
+ * 占据活跃标记（启动序第一步——先占标记再开库，拒双开于开库之前）。
+ *
+ * 判序：标记文件在场且可解析 → pid 活（isAlive 注入判）→ 拒（DataDirBusyError
+ * / HOST_DATA_DIR_BUSY）；pid 死 → 接管覆写（tookOver = true）；标记残缺
+ * （坏 JSON/缺字段）→ 视同陈旧接管（宁接管勿误拒——标记非真相源，durable
+ * 日志才是）。标记缺席 → 直写（tookOver = false）。
+ */
+export function acquireActiveMarker(dataDir, opts = {}) {
+    const pid = opts.pid ?? process.pid;
+    const now = opts.now ?? (() => Date.now());
+    const isAlive = opts.isAlive ?? defaultIsAlive;
+    const ensureDir = opts.ensureDir ?? ((dir) => mkdirSync(dir, { recursive: true }));
+    const writeFile = opts.writeFile ?? ((path, text) => writeFileSync(path, text));
+    const readFile = opts.readFile ?? ((path) => readFileSync(path, 'utf8'));
+    const tryUnlink = opts.tryUnlink ??
+        ((path) => {
+            try {
+                unlinkSync(path);
+            }
+            catch {
+                // ENOENT 幂等；其他错上抛（fail-loud——标记不可清是数据目录病态）
+            }
+        });
+    const markerPath = join(dataDir, ACTIVE_MARKER_BASENAME);
+    ensureDir(dataDir);
+    let tookOver = false;
+    let prevText = null;
+    try {
+        prevText = readFile(markerPath);
+    }
+    catch {
+        prevText = null; // 标记缺席（ENOENT）——首占非接管
+    }
+    if (prevText !== null) {
+        let prev = null;
+        try {
+            prev = JSON.parse(prevText);
+        }
+        catch {
+            prev = null; // 坏 JSON——残缺标记
+        }
+        if (prev !== null && typeof prev.pid === 'number' && Number.isInteger(prev.pid) && prev.pid > 0) {
+            if (isAlive(prev.pid)) {
+                // 活进程持锁——拒入（携带既有记录供诊断面呈现）
+                throw new DataDirBusyError({
+                    pid: prev.pid,
+                    startedAt: typeof prev.startedAt === 'number' ? prev.startedAt : 0,
+                });
+            }
+            tookOver = true; // pid 判死 → 陈旧标记接管
+        }
+        else {
+            tookOver = true; // 残缺（坏 JSON / pid 字段坏）→ 视同陈旧（宁接管勿误拒）
+        }
+    }
+    const record = { pid, startedAt: now() };
+    writeFile(markerPath, `${JSON.stringify(record)}\n`);
+    let released = false;
+    return {
+        tookOver,
+        record,
+        release: () => {
+            if (released)
+                return;
+            released = true;
+            tryUnlink(markerPath);
+        },
+    };
+}

package/dist/host/subagent-factory.js

@@ -0,0 +1,291 @@
+import { canonicalWorkspaceRoot } from '../context/index.js';
+import { EXCLUDED_FROM_DERIVED_SURFACE, IN_PROCESS_CAPABILITIES } from '../subagent/index.js';
+import { formatSkillBlock, validateSkillRefList } from '../skills/index.js';
+/** 派生面结构性恒留名（fs 四名——子自建结构性；bash 恒弃另列） */
+const STRUCTURALLY_KEPT = new Set(EXCLUDED_FROM_DERIVED_SURFACE.filter((name) => name !== 'bash'));
+/** 委派会话登记表工厂（装配根自持单例） */
+export function createDelegationSessionTracker() {
+    const depths = new Map();
+    return {
+        record(sessionId, depth) {
+            depths.set(sessionId, depth);
+        },
+        depthOf(sessionId) {
+            return depths.get(sessionId);
+        },
+        release(sessionId) {
+            depths.delete(sessionId);
+        },
+    };
+}
+/**
+ * 派生面整形器（工厂侧执法律）：bash 恒弃（永不升格总则特例——子管道无
+ * 人在场应答 def 内部升权）；fs 四名恒留（子自建结构性——白名单不含亦在，
+ * 与 deriveToolSurface 剔除语义互补：那层剔父名集、这层整子实面）；其余
+ * 按白名单滤（白名单缺省 = 全留——service 交集已在 availableTools 在场
+ * 时算过，缺席透传形此处亦透传）。
+ */
+export function shapeDerivedTools(whitelist) {
+    const allow = whitelist !== undefined ? new Set(whitelist) : undefined;
+    return (tools) => tools.filter((tool) => {
+        if (tool.name === 'bash')
+            return false;
+        if (STRUCTURALLY_KEPT.has(tool.name))
+            return true;
+        return allow === undefined || allow.has(tool.name);
+    });
+}
+/**
+ * 尾扫末条 assistant 消息文本（黑盒输出面——子会话事件流的最后一条
+ * assistant/message 的 text 块拼接；缺席 = 空串诚实回执）。
+ */
+function lastAssistantText(events) {
+    for (let i = events.length - 1; i >= 0; i -= 1) {
+        const event = events[i];
+        if (event === undefined || event.type !== 'assistant/message')
+            continue;
+        const blocks = event.data?.content;
+        if (!Array.isArray(blocks))
+            return '';
+        return blocks
+            .filter((block) => block.type === 'text')
+            .map((block) => block.text)
+            .join('');
+    }
+    return '';
+}
+/** RunResult 终态 → SubagentStopReason 映射（completed→stop/aborted→aborted/failed→error） */
+function stopReasonOf(status) {
+    if (status === 'completed')
+        return 'stop';
+    if (status === 'failed')
+        return 'error';
+    return 'aborted';
+}
+/**
+ * RP4 机器账铸造（in-process 工厂结算位——04 §10 structured 定形段）：
+ * 从子会话事件流单次扫铸 {turnCount, messageCount, usage 两桶}。
+ * - turnCount = 'turn/start' 计数；
+ * - messageCount = user/message + assistant/message 计数（模型可见消息——
+ *   结算通知「（N 条消息）」取数位）；
+ * - usage = 末条 assistant/message 计量（05 §1.1 通道词律同源——主 loop
+ *   末条 assistant）的两桶投影；零 turn 诚实 null。
+ */
+function forgeAccountFacts(events) {
+    let turnCount = 0;
+    let messageCount = 0;
+    let lastUsage;
+    for (const event of events) {
+        if (event.type === 'turn/start')
+            turnCount += 1;
+        if (event.type === 'user/message' || event.type === 'assistant/message')
+            messageCount += 1;
+        if (event.type === 'assistant/message') {
+            const usage = event.data?.usage;
+            // 窄 guard 两桶（durable 回读形防御）——在场即视为末条计量（后扫覆盖前扫）
+            if (typeof usage === 'object' &&
+                usage !== null &&
+                typeof usage.input === 'number' &&
+                typeof usage.output === 'number') {
+                lastUsage = usage;
+            }
+        }
+    }
+    return { turnCount, messageCount, lastUsage };
+}
+/**
+ * 机器账组装（structured + 顶层 usage 同值双填——同源一次铸造）：顶层位
+ * = 末条 assistant 完整 Usage 透传（第三方 provider 只报顶层的独立保留位）；
+ * structured.usage = 同源两桶投影（无计量诚实 null）。
+ */
+function forgeMachineAccount(input) {
+    const facts = forgeAccountFacts(input.events);
+    const structured = {
+        childSessionId: input.childSessionId,
+        // jobName 仅 background 形在场（与注册表条目/通知文案同名——one-shot 无 Job 身份）
+        ...(input.request.background === true && input.request.name !== undefined ? { jobName: input.request.name } : {}),
+        durationMs: Date.now() - input.startedAt,
+        turnCount: facts.turnCount,
+        messageCount: facts.messageCount,
+        usage: facts.lastUsage !== undefined ? { input: facts.lastUsage.input, output: facts.lastUsage.output } : null,
+        stopReason: input.stopReason,
+    };
+    return { structured, usage: facts.lastUsage };
+}
+/**
+ * in-process 子代理 provider（真工厂——SubagentProvider 契约的本体实装）。
+ * capabilities 五布尔恒真（IN_PROCESS_CAPABILITIES 单源）。
+ */
+export function createInProcessSubagentProvider(options) {
+    const { stack, tracker, warn } = options;
+    return {
+        capabilities: IN_PROCESS_CAPABILITIES,
+        async run(request) {
+            // reserve 线起跑前执法（04 §5——总预算 90% 已越线则不起跑）：诚实回执
+            // aborted + diagnostic，不建会话不耗预算——余量留给主循环写终态
+            if (options.reserveBreached?.() === true) {
+                return {
+                    output: '',
+                    stopReason: 'aborted',
+                    diagnostic: '后台预算已达 90% reserve 线——子代理不起跑，余量留给主循环写终态（04 §5）',
+                };
+            }
+            // skills 键执法（06 §11.6 spawn 永久注入模）：形状三验工厂侧统一复验
+            //（单执法点覆盖声明式 def/程序化 def/直呼 request 全腿——解析层管形状、
+            // 工厂兜底：程序化与直呼腿不经解析层）；存在性逐名解析，任一缺席 =
+            // 拒 spawn 回执缺口 fail-ask（不建会话不耗预算——reserve 线同形）。
+            // disable-model-invocation 隐藏件不受限（作者侧声明面——清单滤除律
+            // 只限模型自动装载面）。
+            let childSystemPrompt = request.systemPrompt;
+            if (request.skills !== undefined && request.skills.length > 0) {
+                const shapeErrors = validateSkillRefList(request.skills);
+                if (shapeErrors.length > 0) {
+                    return {
+                        output: '',
+                        stopReason: 'aborted',
+                        diagnostic: `skills 键形状违例：${shapeErrors.join('；')}——子代理不起跑（06 §11.6 形状护栏）`,
+                    };
+                }
+                if (options.resolveSkill === undefined) {
+                    return {
+                        output: '',
+                        stopReason: 'aborted',
+                        diagnostic: '技能注册表不可达（无插件装配形）——skills 键子代理不起跑（fail-closed，06 §11.6）',
+                    };
+                }
+                const missing = [];
+                const blocks = [];
+                for (const ref of request.skills) {
+                    const skill = options.resolveSkill(ref);
+                    if (skill === undefined) {
+                        missing.push(ref);
+                    }
+                    else {
+                        blocks.push(formatSkillBlock(skill, skill.content));
+                    }
+                }
+                if (missing.length > 0) {
+                    return {
+                        output: '',
+                        stopReason: 'aborted',
+                        diagnostic: `技能未解析（${missing.join('、')}）——子代理不起跑（06 §11.6 skills 键 fail-ask）；可查 <available_skills> 清单核对名称`,
+                    };
+                }
+                // 全命中：具名块拼入子 systemPrompt 尾（systemPrompt 缺席 = 空串起拼
+                //——注入不依赖其在场；与清单渐进披露并存——额外正文常驻非替代披露）
+                childSystemPrompt = `${request.systemPrompt ?? ''}\n\n${blocks.join('\n\n')}`;
+            }
+            // service 已在 request.tools 位算好 effectiveTools（availableTools 在场
+            // = 派生面∩白名单交集；缺席 = 透传白名单）——整形器以之为准
+            const whitelist = request.tools;
+            // 委派边界①：审批型升权路由——子会话 ask 落父会话审批面（ownership
+            // 织入注释的执法位：恰一键 {sessionId: 父}——子代理在父会话内发起的
+            // 审批落回父会话呈现面）。background 形先发挂起通知（恰一条幂等由
+            // 父 driver dedupeKey 面执法；one-shot 不发——挂着等待即知情）。
+            const parentSessionId = request.parentSessionId;
+            const askApproval = parentSessionId !== undefined
+                ? async (req, opts) => {
+                    if (request.background === true && request.notifyApproval !== undefined && req.approvalId !== undefined) {
+                        try {
+                            await request.notifyApproval({
+                                approvalId: req.approvalId,
+                                toolName: req.toolName ?? request.name ?? '未知工具',
+                                ...(req.reason !== undefined ? { reason: req.reason } : {}),
+                            });
+                        }
+                        catch (err) {
+                            warn(`审批挂起通知失败（不阻断 ask 本体）：${err instanceof Error ? err.message : String(err)}`);
+                        }
+                    }
+                    return stack.channels.askApproval(parentSessionId, req, opts);
+                }
+                : undefined;
+            // 子会话装配（真工厂核心）：origin 'delegation' durable 归因；model/
+            // systemPrompt def 直传（skills 注入后形）；shapeTools 派生面整形；
+            // askApproval 升父面。startedAt 在建会话前取（机器账 durationMs 计量
+            // 含装配段——「子运行墙钟」从委派受理起算）。
+            const startedAt = Date.now();
+            const child = stack.manager.create({
+                origin: 'delegation',
+                workspaceRoot: canonicalWorkspaceRoot(),
+                ...(request.name !== undefined ? { title: request.name } : {}),
+                ...(request.model !== undefined ? { model: request.model } : {}),
+                ...(childSystemPrompt !== undefined ? { systemPrompt: childSystemPrompt } : {}),
+                shapeTools: shapeDerivedTools(whitelist),
+                ...(askApproval !== undefined ? { askApproval } : {}),
+            });
+            const driver = child.driver;
+            tracker.record(child.sessionId, request.depth ?? 1);
+            // 协作停止桥（只 background 形注入——one-shot 父同步等无停止位）：
+            // JobHandle 置 stopping → 轮询观察 → abort 子 run；reserve 线观察
+            // （04 §5——非交互子代理 90% 线强停）同轮合流：越线 → abort + 记因
+            //（回执 diagnostic 归因预算而非泛 aborted）
+            let reserveStopped = false;
+            const observeStop = request.stopRequested;
+            const observeReserve = options.reserveBreached;
+            let timer;
+            if (observeStop !== undefined || observeReserve !== undefined) {
+                timer = setInterval(() => {
+                    if (observeStop !== undefined && observeStop()) {
+                        driver.abort();
+                        return;
+                    }
+                    if (observeReserve !== undefined && observeReserve()) {
+                        reserveStopped = true;
+                        driver.abort();
+                    }
+                }, 500);
+                timer.unref();
+            }
+            try {
+                // 子 prompt 提交：source 缺省 'user'（父即子的用户；origin
+                // 'delegation' 在会话行是 durable 归因——EventSource 闭集无该词）
+                const outcome = await driver.submit(request.prompt);
+                const events = driver.session.events();
+                const output = lastAssistantText(events);
+                // 机器账铸造（RP4——已起跑位含防御位都铸：childSessionId 已有、
+                // 计量如实〔防御位 turnCount 0 形〕；pre-spawn 拒径不铸〔无会话〕）
+                const account = forgeMachineAccount({
+                    childSessionId: child.sessionId,
+                    request,
+                    startedAt,
+                    events,
+                    stopReason: outcome.status === 'injected' || outcome.status === 'wake-refused'
+                        ? 'aborted'
+                        : stopReasonOf(outcome.status),
+                });
+                if (outcome.status === 'injected' || outcome.status === 'wake-refused') {
+                    // 理论不达防御位（新会话无停摆/无唤醒件）——诚实回执不伪装完成
+                    return {
+                        output,
+                        stopReason: 'aborted',
+                        diagnostic: `子会话提交未起跑（${outcome.status}）`,
+                        structured: account.structured,
+                        ...(account.usage !== undefined ? { usage: account.usage } : {}),
+                    };
+                }
+                return {
+                    output,
+                    stopReason: stopReasonOf(outcome.status),
+                    ...(reserveStopped && outcome.status === 'aborted'
+                        ? { diagnostic: '后台预算达 90% reserve 线——子代理强停，余量留给主循环写终态（04 §5）' }
+                        : {}),
+                    ...(outcome.status === 'failed' && outcome.errorMessage !== undefined
+                        ? { diagnostic: outcome.errorMessage }
+                        : {}),
+                    structured: account.structured,
+                    ...(account.usage !== undefined ? { usage: account.usage } : {}),
+                };
+            }
+            finally {
+                if (timer !== undefined)
+                    clearInterval(timer);
+                tracker.release(child.sessionId);
+                // 单会话收口（05 §7 retire 律）：dismantle 终态停摆 + 摘活体登记
+                //（原 driver.dismantle 直调的「活体登记回收挂账」销账——durable 面
+                // 不受影响，log 仍可查）
+                stack.manager.retire(child.sessionId);
+            }
+        },
+    };
+}