@kiturone/kapibala 0.0.6 → 0.0.8

package/dist/index.d.cts

@@ -437,6 +437,15 @@ interface Usage {
 }
 /** canonical 消息角色；'tool' 仅用于工具结果消息，wire 角色转换只发生在请求投影阶段。 */
 type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
+/** 子代理通知背景消息的来源元数据；仅用于去重与审计，不发送到 Provider wire。 */
+interface SubagentSourceMetadata {
+    readonly eventId: string;
+    readonly agentId: string;
+    readonly rootTaskId: string;
+    readonly role: string;
+    readonly status: string;
+    readonly originBranchId: string;
+}
 /**
  * 协议无关的历史真源；wire 格式只在请求投影时出现。
  * 不变量：assistant 消息中的 tool_use 进入历史后，对应 tool_result 消息必须紧跟其后。
@@ -455,6 +464,8 @@ interface CanonicalMessage {
     role: MessageRole;
     content: ContentBlock[];
     timestamp?: number;
+    /** 子代理通知背景消息来源元数据（仅用于审计与收件箱幂等去重）。 */
+    subagentSource?: SubagentSourceMetadata;
 }
 /** 判别并收窄为文本块。 */
 declare function isTextBlock(block: ContentBlock): block is TextBlock;
@@ -799,10 +810,24 @@ interface MessageStore {
     clear(): Promise<void>;
 }
 
-/** 会话正文 schema 版本；读取时不匹配即拒绝恢复，不做跨版本猜测。 */
-declare const SESSION_SCHEMA_VERSION = 1;
-/** 会话记录类型：header 只出现一次，message 承载正文，其余为状态记录。 */
-type SessionRecordType = 'header' | 'message' | 'run_started' | 'run_finished' | 'message_state' | 'history_repair' | 'usage' | 'checkpoint' | 'context_pruned' | 'compaction_state' | 'title' | 'reset' | 'legacy_import';
+/** 会话正文 schema v1 版本常量（只读兼容）。 */
+declare const SESSION_SCHEMA_VERSION_V1 = 1;
+/** 会话正文 schema v2 版本常量（当前规范）。 */
+declare const SESSION_SCHEMA_VERSION_V2 = 2;
+/** 当前会话正文默认创建与支持的 schema 版本。 */
+declare const SESSION_SCHEMA_VERSION = 2;
+/** 默认主分支标识。 */
+declare const MAIN_BRANCH_ID = "main";
+/** 会话记录类型：header 只出现一次，message 承载正文，其余为分支或全局控制记录。 */
+type SessionRecordType = 'header' | 'message' | 'run_started' | 'run_finished' | 'message_state' | 'history_repair' | 'usage' | 'checkpoint' | 'context_pruned' | 'compaction_state' | 'title' | 'reset' | 'legacy_import' | 'branch_created' | 'branch_selected' | 'branch_summary' | 'archive_state';
+/**
+ * 判断指定记录类型是否属于全局控制记录。
+ *
+ * 保证：
+ * - 全局控制记录的 parentId 为 null，不推进分支上下文叶子；
+ * - 其余记录为分支记录，必须有合法的前驱因果 parentId 并推进对应分支的叶子。
+ */
+declare function isGlobalControlRecordType(type: SessionRecordType): boolean;
 /** 会话文件首条记录：身份与创建环境快照；conversationId 与文件名强绑定。 */
 interface SessionHeader {
     conversationId: string;
@@ -812,14 +837,26 @@ interface SessionHeader {
     gitBranch?: string;
     /** 旧历史导入的幂等身份；存在时同一来源只导入一次。 */
     importIdentity?: string;
+    /** v1 副本升级的幂等来源身份（来源路径 + 源 conversationId + 源内容哈希）。 */
+    upgradeIdentity?: string;
+    /** 派生或 Fork 来源会话与切点记录 ID。 */
+    parentSessionId?: string;
+    forkPointRecordId?: string;
 }
-/** 单条 JSONL 记录封装；parentId 链接前驱，恢复时校验追加次序。 */
+/** 单条 JSONL 记录封装；v2 引入连续物理 seq 与 prevRecordId，因果 parentId 与 branchId 独立。 */
 interface SessionRecord {
     schemaVersion: number;
     type: SessionRecordType;
     recordId: string;
     timestamp: number;
+    /** 物理连续序号（v2，从 0 开始自增；v1 为 undefined）。 */
+    seq?: number;
+    /** 物理前驱记录 ID（v2 为上一条物理记录 ID，首条记录为 null；v1 为 undefined）。 */
+    prevRecordId?: string | null;
+    /** 上下文因果父节点记录 ID（分支记录必须有合法更早的父节点；全局控制记录为 null）。 */
     parentId: string | null;
+    /** 分支归属标识（v2 分支记录归属；全局控制记录为 null 或 undefined；v1 为 undefined）。 */
+    branchId?: string | null;
     payload: Record<string, unknown>;
 }
 /** loadState 返回的版本化状态视图；记录自最近 reset 起有效。 */
@@ -829,14 +866,59 @@ interface SessionState {
     records: SessionRecord[];
     /** 只随正文、修复与 reset 改变，不因 usage 或缓存写入失效。 */
     contentRevision: string;
+    /** 物理末记录 ID。 */
+    logRevision: string;
+    /** 当前活动分支 ID（默认 'main'）。 */
+    activeBranchId: string;
+    /** 当前活动分支叶子记录 ID。 */
+    activeLeafId: string | null;
+    /** 所有分支的叶子节点映射表。 */
+    branchLeaves: ReadonlyMap<string, string>;
+    /** 会话文件 schema 版本。 */
+    schemaVersion: number;
+}
+/** 会话分支元数据信息。 */
+interface BranchInfo {
+    /** 分支唯一标识。 */
+    branchId: string;
+    /** 分支切点记录 ID（主分支 main 为根节点 ID）。 */
+    baseRecordId: string;
+    /** 分支当前最新叶子节点 ID。 */
+    leafRecordId: string;
+    /** 分支创建时间（若无记录则为首条记录时间）。 */
+    createdAt: number;
+    /** 是否为当前活动分支。 */
+    isActive: boolean;
+    /** 沿该分支因果链回溯的总消息数。 */
+    messageCount: number;
 }
 /** MessageStore 的可选状态能力；旧 SDK Store 不需要实现，宿主据此降级持久压缩。 */
 interface StatefulMessageStore extends MessageStore {
-    appendRecord(type: Exclude<SessionRecordType, 'header' | 'message'>, payload: Record<string, unknown>): Promise<SessionRecord>;
-    loadState(): Promise<SessionState>;
+    appendRecord(type: Exclude<SessionRecordType, 'header' | 'message'>, payload: Record<string, unknown>, options?: {
+        branchId?: string;
+        parentId?: string;
+    }): Promise<SessionRecord>;
+    loadState(options?: {
+        branchId?: string;
+    }): Promise<SessionState>;
 }
 /** 判断 Store 是否支持版本化状态；不读取数据或改变旧 Store。 */
 declare function supportsSessionState(store: MessageStore): store is StatefulMessageStore;
+/**
+ * 校验目标切点是否处于完整闭合的工具事务边界。
+ *
+ * 保证与约束：
+ * - 沿目标切点因果链从根至切点按因果顺序扫描；
+ * - 若因果链中包含发起了 tool_use 的 assistant 消息，必须紧随其后且在切点之前包含全部对应的 tool_result 结果；
+ * - 若切点位于未闭合工具事务的内部（包括发起 tool_use 的 assistant 自身，或仅回填了部分工具结果的 tool 消息），
+ *   抛出 `UNCLOSED_TOOL_TRANSACTION_FORK` 错误拒绝分叉；
+ * - 绝不依赖推测修复，保护持久化分支树的历史闭合不变量。
+ *
+ * @param records 会话中所有可用记录列表
+ * @param targetRecordId 切点记录唯一标识
+ * @throws {KapibalaError} 当切点位于未闭合工具事务内部或切点不存在时
+ */
+declare function assertClosedToolTransaction(records: SessionRecord[], targetRecordId: string): void;
 /**
  * 版本化消息与上下文状态的单文件存储。所有写入串行并 fsync，失败后拒绝继续写入。
  * 调用者须在打开前取得单写者锁；本类不允许静默跳过中部损坏或重复身份。
@@ -848,29 +930,99 @@ declare class SessionStore implements StatefulMessageStore {
     private observer?;
     private onDiagnostic?;
     private stamp?;
+    private schemaVersion;
+    private activeBranchId;
+    private branchLeaves;
     private constructor();
+    /** 获取当前会话文件使用的 Schema 版本（1 或 2）。 */
+    getSchemaVersion(): number;
+    /** 判断当前会话是否为只读历史（v1 历史文件强制只读）。 */
+    isReadOnly(): boolean;
+    /** 获取当前选中的活动分支标识。 */
+    getActiveBranchId(): string;
+    /** 获取所有分支当前叶子记录 ID 映射快照。 */
+    getBranchLeaves(): ReadonlyMap<string, string>;
     /** 注册可重建缓存的写后通知；缓存失败只诊断，不撤销或毒化已 fsync 的正文。 */
     setAppendObserver(observer: (record: SessionRecord) => void, onDiagnostic?: (message: string) => void): void;
-    /** 以独占创建方式安装新头部，已有文件明确失败，绝不覆盖其它会话。 */
+    /** 以独占创建方式安装新头部（默认生成 Schema v2 格式），已有文件明确失败，绝不覆盖其它会话。 */
     static create(filePath: string, header: SessionHeader): Promise<SessionStore>;
     /** 打开并验证已有会话；尾部残片先保存到隔离文件，中部损坏与未知版本拒绝恢复。 */
     static open(filePath: string): Promise<SessionStore>;
     /** 获取完整记录快照，等候已排队写入后读取；调用者不能借此修改内部记录。 */
     readRecords(): Promise<SessionRecord[]>;
     /** 消息级持久化，补稳定身份并保留所有终态字段，成功后方可进入下一次写入。 */
-    append(message: CanonicalMessage): Promise<void>;
+    append(message: CanonicalMessage, options?: {
+        branchId?: string;
+        parentId?: string;
+    }): Promise<void>;
     /** 持久化状态记录，fsync 成功才返回；失败会毒化当前写者，要求重新验证后恢复。 */
-    appendRecord(type: Exclude<SessionRecordType, 'header' | 'message'>, payload: Record<string, unknown>): Promise<SessionRecord>;
-    /** 重建 reset 后的状态；统计记录和检查点不会推进正文 revision。 */
-    loadState(): Promise<SessionState>;
+    appendRecord(type: Exclude<SessionRecordType, 'header' | 'message'>, payload: Record<string, unknown>, options?: {
+        branchId?: string;
+        parentId?: string;
+    }): Promise<SessionRecord>;
+    /**
+     * 创建新分支记录并推进分支叶子。
+     *
+     * 约束：
+     * - 分支标识必须符合命名规范（字母、数字、下划线、短横线）；
+     * - 目标分支必须不存在；
+     * - 切点记录 baseRecordId 必须为正文中已存在的合法记录；
+     * - 拒绝未闭合工具事务分叉：因果链上不得包含未全部回填 tool_result 的工具调用；
+     * - v1 历史会话禁止创建分支。
+     */
+    createBranch(branchId: string, baseRecordId: string): Promise<SessionRecord>;
     /**
-     * 恢复原始正文，并将幂等修复叠加到原工具事务；不合并连续消息，也不执行工具。
-     * 缺失结果用 history_repair 落盘，独立于实际工具结果和正文，不伪造成功。
+     * 切换活动分支并持久化记录。
+     *
+     * 约束：
+     * - 目标分支必须已被创建或存在；
+     * - v1 历史会话禁止切换分支。
+     */
+    selectBranch(branchId: string): Promise<SessionRecord>;
+    /**
+     * 追加逻辑归档控制记录。
+     *
+     * 约束：
+     * - 归档状态记录为全局控制记录（parentId 为 null，不推进分支上下文叶子）；
+     * - payload 结构为 { archived: boolean }；
+     * - v1 历史会话禁止变更归档状态。
+     */
+    setArchiveState(archived: boolean): Promise<SessionRecord>;
+    /**
+     * 查询当前会话是否处于已归档状态。
+     */
+    isArchived(): Promise<boolean>;
+    /**
+     * 获取当前会话中所有已知分支的元数据与状态列表。
+     */
+    getBranches(): Promise<BranchInfo[]>;
+    /** 重建指定分支（默认当前活动分支）reset 后的状态视图。 */
+    loadState(options?: {
+        branchId?: string;
+    }): Promise<SessionState>;
+    /**
+     * 沿因果 parentId 链从叶子节点回溯，生成合法线性消息序列投影。
+     *
+     * 保证与约束：
+     * - 仅包含回溯因果链上的消息与状态叠加，全局控制记录与其他分支记录被天然隔离；
+     * - 支持 reset 边界截断与 history_repair 幂等叠加；
+     * - 严格校验工具事务闭合不变量，拒绝半事务破坏；
+     * - 修复缺失结果时自动持久化 history_repair（v2 下在目标分支上记录）。
+     */
+    buildProjection(options?: {
+        branchId?: string;
+        leafRecordId?: string;
+    }): Promise<CanonicalMessage[]>;
+    /**
+     * 恢复当前活动分支的原始正文，并将幂等修复叠加到原工具事务。
      */
     load(): Promise<CanonicalMessage[]>;
     /** SDK 清空语义通过持久边界实现；此前摘要、剪裁及失败状态不再参与恢复。 */
     clear(): Promise<void>;
-    /** 生成前驱关联的 Envelope，前驱仅表达追加次序，未来 DAG 不改变当前恢复规则。 */
+    /**
+     * 生成 Envelope 记录。
+     * v2 下严格维护连续物理序号 seq、物理前驱 prevRecordId 与因果 parentId / branchId。
+     */
     private makeRecord;
     /** 单写者队列不吞异常；后续写入依赖同一失败 Promise，防止继续污染正文。 */
     private enqueue;
@@ -916,6 +1068,8 @@ interface ProjectIdentity {
     /** true 表示 cwd 位于 Git 工作树内；同工作树子目录共用同一桶。 */
     gitWorktree?: boolean;
 }
+/** Windows 桶和头部使用相同大小写规范，POSIX 保持路径大小写语义。 */
+declare function normalizedProjectRoot(root: string): string;
 /** 解析真实工作树根；同工作树子目录共用桶，非 Git 目录和不同 worktree 独立。不会改变 cwd。 */
 declare function resolveSessionProject(cwd: string): ProjectIdentity;
 /**
@@ -923,7 +1077,8 @@ declare function resolveSessionProject(cwd: string): ProjectIdentity;
  * 正文 JSONL 始终是唯一真源。
  */
 interface SessionMetadata {
-    schemaVersion: 1;
+    /** 元数据缓存格式版本（1 或 2）。 */
+    schemaVersion: number;
     conversationId: string;
     fileName: string;
     projectRoot: string;
@@ -939,10 +1094,24 @@ interface SessionMetadata {
     lastModelId?: string;
     /** 旧历史导入的幂等身份（来源路径 + 内容哈希）；重复导入据此跳过。 */
     importIdentity?: string;
+    /** v1 副本升级的来源身份哈希。 */
+    upgradeIdentity?: string;
     size: number;
     mtimeMs: number;
-    /** 最后计入的记录 ID；与正文 stat 一同用于增量校验。 */
+    /** 兼容字段：最后计入的记录 ID。 */
     revision: string;
+    /** 会话文件使用的 Schema 版本（1 或 2）。 */
+    sessionSchemaVersion?: number;
+    /** 物理末记录 ID（与 revision 语义一致）。 */
+    logRevision?: string;
+    /** 内容正文 revision（仅正文/修复/reset 变化）。 */
+    contentRevision?: string;
+    /** 当前活动分支 ID（默认 'main'）。 */
+    activeBranchId?: string;
+    /** 当前活动分支叶子记录 ID。 */
+    activeLeafId?: string | null;
+    /** 会话是否已归档。 */
+    archived?: boolean;
 }
 /** 打开的会话句柄：持有单写者锁与 Store，宿主用毕必须 release。 */
 interface ManagedSession {
@@ -960,8 +1129,13 @@ interface ManagedSession {
     /** 释放单写者锁并移除句柄；宿主须先结束 AgentSession 的工具/摘要清理。 */
     release(): Promise<void>;
 }
-/** SessionManager 配置；cwd 决定项目桶，homeDirectory 便于测试隔离。 */
+/** SessionManager 配置；workspaceRoot/projectRoot/cwd 决定项目桶，homeDirectory 便于测试隔离。 */
 interface SessionManagerOptions {
+    /** 显式工作区物理根路径。 */
+    workspaceRoot?: string;
+    /** 显式项目根路径。 */
+    projectRoot?: string;
+    /** 执行或参考目录；若未提供工作区根，以此解析项目工作树。 */
     cwd?: string;
     homeDirectory?: string;
     onDiagnostic?: (message: string) => void;
@@ -977,19 +1151,45 @@ declare class SessionManager {
     constructor(options?: SessionManagerOptions);
     /** 默认新建独立空会话，写入头部并持有单写者锁；不读取其它正文。 */
     create(): Promise<ManagedSession>;
-    /** 每页 20 项按正文活动排序；有效 sidecar 只读元数据，不读取完整 JSONL。 */
-    list(page?: number): Promise<{
+    /** 每页 20 项按正文活动排序；有效 sidecar 只读元数据，不读取完整 JSONL。默认排除已归档会话。 */
+    list(page?: number, options?: {
+        includeArchived?: boolean;
+    }): Promise<{
         items: SessionMetadata[];
         total: number;
         page: number;
         pages: number;
     }>;
+    /** 解析完整 ID 或唯一前缀对应的会话文件与 ID。 */
+    private resolveSession;
+    /**
+     * 逻辑归档指定会话。
+     *
+     * 约束：
+     * - 必须取得会话独占锁；
+     * - 若会话当前正处于活动打开状态，拒绝归档并抛出 SESSION_IN_USE；
+     * - 向会话正文追加 archive_state { archived: true } 并刷新 sidecar 缓存。
+     */
+    archiveSession(id: string): Promise<void>;
+    /**
+     * 恢复已逻辑归档的会话。
+     */
+    restoreSession(id: string): Promise<void>;
     /** 一次扫描建立排序目录，分页和继续最近会话共用；有效缓存不读取正文。 */
     private allMetadata;
-    /** 打开完整 ID 或唯一前缀；跨桶、缺失与歧义均失败，同一 Manager 已持有的目标直接返回。 */
-    open(id: string): Promise<ManagedSession>;
+    /**
+     * 打开完整 ID 或唯一前缀；跨桶、缺失与歧义均失败，同一 Manager 已持有的目标直接返回。
+     *
+     * @param id 完整会话 ID 或唯一前缀
+     * @param options 可选参数，autoUpgradeLegacy 为 true 时若目标为 v1 旧会话则自动创建/复用 v2 副本以支持无感续写
+     */
+    open(id: string, options?: {
+        autoUpgradeLegacy?: boolean;
+    }): Promise<ManagedSession>;
     /** 继续最近有正文的会话；没有历史才新建，显式打开失败绝不回退为空会话。 */
-    continueRecent(): Promise<ManagedSession>;
+    continueRecent(options?: {
+        autoUpgradeLegacy?: boolean;
+    }): Promise<ManagedSession>;
     /** 标题作为独立耐久记录；标题或浏览不改变正文活动排序。 */
     rename(id: string, title: string): Promise<void>;
     /** 等候所有存储队列后释放句柄；宿主必须先结束 AgentSession 的工具/摘要清理。 */
@@ -999,6 +1199,40 @@ declare class SessionManager {
      * 保留源文件，安装身份写入头部，缓存丢失或进程退出后仍不会重复导入。
      */
     importLegacy(): Promise<string[]>;
+    /**
+     * 将旧版 v1 会话升级为独立的 v2 会话副本。
+     *
+     * 保证与约束：
+     * - 原 v1 会话文件保持只读且绝不进行原地修改；
+     * - 升级生成全新独立会话文件，Header 中记录 upgradeIdentity；
+     * - 幂等：若同一 v1 文件已升级过，直接返回已有 v2 会话句柄，不重复生成副本；
+     * - 升级过程使用单写者锁保护临时文件，原子发布；
+     * - 失败时不污染目标桶目录。
+     *
+     * @param idOrFileName 原会话 conversationId 或文件名（如 `xxx.jsonl`）
+     * @returns 升级后的独立 v2 会话句柄（持有写者锁）
+     */
+    upgradeLegacyV1Session(idOrFileName: string): Promise<ManagedSession>;
+    /**
+     * 从当前会话的指定路径（指定分支或切点）导出生成全新的独立会话文件。
+     *
+     * 保证与约束：
+     * - 新会话拥有全新独立的 conversationId；
+     * - Header 记录 parentSessionId 与 forkPointRecordId；
+     * - 仅复制导出路径上的必需状态，映射为新会话的 main 分支并重排连续 seq/prevRecordId；
+     * - 拒绝半事务分叉：切点若为未闭合工具调用的 assistant 消息，立即报错；
+     * - 历史 usage 标为导入来源（importedFromFork: true），不重复计入新会话执行费用；
+     * - 临时文件写入、fsync 后原子发布，同步目录；
+     * - 导出失败绝不污染或修改源会话。
+     *
+     * @param options 导出配置
+     * @returns 新独立会话句柄（持有写者锁）
+     */
+    forkSession(options: {
+        sourceSessionId: string;
+        branchId?: string;
+        forkPointRecordId?: string;
+    }): Promise<ManagedSession>;
     /** 绑定写后缓存与锁生命周期；正文优先，缓存失败不使保存成功的消息消失。 */
     private attach;
     /** 缓存通过文件名、身份、统计与正文 stat 校验；失败交由正文重建。 */
@@ -1016,6 +1250,184 @@ declare class SessionManager {
     private report;
 }
 
+/**
+ * @fileoverview 跨项目会话目录扫描（CrossProjectSessionCatalog）与有界全文检索。
+ *
+ * 约束、边界与为什么：
+ * 1. 跨项目扫描与增量 Sidecar 校验（Cross-Project Incremental Discovery）：
+ *    扫描 ~/.kapibala/sessions 全局项目桶目录，优先通过 sidecar 缓存校验读取元数据；
+ *    若缓存缺失或 stat（大小/mtime）失配，流式读取正文重建，严禁将未校验缓存当真源。
+ * 2. 有界全文检索（Bounded Full-Text Search）：
+ *    - 范围限定：仅搜索 user / assistant 可见文本与 branch_summary 分支摘要，
+ *      默认绝对排除 tool_result 原始输出、私有 reasoning、协议私有字段与凭据；
+ *    - 检索语法：支持空格 AND、引号短语、project:/branch:/tag: 属性限定与 re: 正则模式；
+ *    - 中文检索：按原生字面子串匹配，不依赖第三方分词库；
+ *    - 有界保护：单行限长截断、病态正则超时熔断、最大结果数量上限，超限返回 partial 及原因。
+ * 3. 逻辑归档隔离（Archive Isolation）：
+ *    默认目录列表与全文搜索严格排除已归档（archived: true）会话，除非显式指定 includeArchived。
+ */
+
+/**
+ * 跨项目会话目录项。
+ */
+interface SessionCatalogEntry extends SessionMetadata {
+    /** 所属项目桶键名（SHA256 哈希）。 */
+    readonly projectKey: string;
+    /** 会话文件物理绝对路径。 */
+    readonly filePath: string;
+}
+/**
+ * 全文检索命中结果项。
+ */
+interface SearchHit {
+    /** 所属会话 ID。 */
+    readonly conversationId: string;
+    /** 所属项目根路径。 */
+    readonly projectRoot: string;
+    /** 所属分支 ID。 */
+    readonly branchId: string;
+    /** 命中的记录 ID。 */
+    readonly recordId: string;
+    /** 命中角色（user / assistant / branch_summary）。 */
+    readonly role: 'user' | 'assistant' | 'branch_summary';
+    /** 命中记录的时间戳。 */
+    readonly timestamp: number;
+    /** 命中片段摘要（包含关键词的上下文片段）。 */
+    readonly snippet: string;
+    /** 是否处于可分叉/可续答的合法边界。 */
+    readonly canResume: boolean;
+}
+/**
+ * 全文检索选项。
+ */
+interface SearchOptions {
+    /** 限定项目根路径或 projectKey。 */
+    readonly project?: string;
+    /** 限定分支名。 */
+    readonly branch?: string;
+    /** 限定标签。 */
+    readonly tag?: string;
+    /** 是否包含已归档会话（默认 false）。 */
+    readonly includeArchived?: boolean;
+    /** 最大返回命中记录数（默认 50，最大 200）。 */
+    readonly limit?: number;
+    /** 搜索总体超时时间（毫秒，默认 10,000ms）。 */
+    readonly timeoutMs?: number;
+    /** 取消信号。 */
+    readonly signal?: AbortSignal;
+}
+/**
+ * 全文检索结果响应。
+ */
+interface SearchResponse {
+    /** 命中结果列表。 */
+    readonly hits: readonly SearchHit[];
+    /** 扫描的会话总数。 */
+    readonly totalSessionsScanned: number;
+    /** 扫描的记录总数。 */
+    readonly totalRecordsScanned: number;
+    /** 是否为有界部分截断结果。 */
+    readonly isPartial: boolean;
+    /** 产生截断或跳过的原因列表。 */
+    readonly partialReasons?: readonly string[];
+}
+/**
+ * 目录扫描配置选项。
+ */
+interface CatalogOptions {
+    /** 会话全局存储根目录（缺省为 ~/.kapibala/sessions）。 */
+    readonly sessionsDir?: string;
+    /** 用户主目录（用于测试隔离）。 */
+    readonly homeDirectory?: string;
+    /** 诊断回调。 */
+    readonly onDiagnostic?: (message: string) => void;
+}
+/**
+ * 具有超时保护的正则匹配结果。
+ */
+interface SafeRegexMatchResult {
+    /** 是否匹配成功。 */
+    readonly matched: boolean;
+    /** 首次匹配的字符起始索引，未匹配为 -1。 */
+    readonly matchIndex: number;
+    /** 是否因超时而提前终止。 */
+    readonly timedOut?: boolean;
+    /** 异常信息。 */
+    readonly error?: string;
+}
+/**
+ * 在独立 Worker 线程中执行正则匹配，并在超时时强制 terminate 线程。
+ * 彻底防御主事件循环被 ReDoS 灾难性回溯阻塞。
+ *
+ * 保证：
+ * - 默认复用长寿命常驻 Worker 实例，消除每次匹配 ~93ms 的新建开销；
+ * - 超时后强制终止底层卡死 Worker 线程，释放 CPU 资源并重建新实例；
+ * - 捕获正则语法异常与执行异常，显式提供 error 字段供诊断，不向上抛出未捕获错误；
+ * - 纯内存通信，不产生临时磁盘文件。
+ *
+ * @param pattern 正则表达式模式文本
+ * @param flags 正则表达式修饰符（如 'i', 'm' 等）
+ * @param text 待检索的目标文本
+ * @param timeoutMs 超时毫秒数（默认 1000ms）
+ */
+declare function safeRegexMatch(pattern: string, flags: string, text: string, timeoutMs?: number): Promise<SafeRegexMatchResult>;
+/**
+ * 跨项目会话目录检索器（CrossProjectSessionCatalog）。
+ */
+declare class CrossProjectSessionCatalog {
+    readonly sessionsDir: string;
+    private readonly diagnostic?;
+    constructor(options?: CatalogOptions);
+    /**
+     * 跨项目流式扫描全局目录下的所有会话元数据。
+     *
+     * 保证：
+     * - 优先校验并利用 sidecar 增量缓存；
+     * - 缓存损坏或缺失时从正文重建并持久化 sidecar；
+     * - 默认排除已归档（archived）会话。
+     */
+    scanSessions(options?: {
+        projectRoot?: string;
+        projectKey?: string;
+        includeArchived?: boolean;
+    }): Promise<SessionCatalogEntry[]>;
+    /**
+     * 有界跨项目全文检索。
+     *
+     * 保证：
+     * - 仅搜索可见文本（user / assistant 文字）与分支摘要；
+     * - 支持空格 AND、引号短语、project:/branch: 前缀与 re: 正则；
+     * - 中文子串字面匹配；
+     * - 遵守限长、超时与最大返回限制，返回 partial 标志与原因。
+     *
+     * @param query 搜索关键词或查询表达式
+     * @param options 搜索选项
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResponse>;
+    /**
+     * 解析查询字符串。
+     */
+    private parseQuery;
+    /**
+     * 在单个会话文件中流式搜索匹配记录。
+     */
+    private searchInSessionFile;
+    /**
+     * 判定文本是否匹配查询条件。
+     */
+    private matches;
+    /**
+     * 生成关键词周边的摘录片段。
+     */
+    private generateSnippet;
+    /**
+     * 读取或增量重建单个会话文件的元数据。
+     */
+    private resolveMetadata;
+    private sidecarPath;
+    private report;
+}
+
 /** 对对象 key 确定性排序，保证摘要、工具 schema 与 fingerprint 不受插入顺序影响。 */
 declare function stableSerialize(value: unknown): string;
 
@@ -1078,6 +1490,546 @@ declare class UnicodeTokenEstimator implements TokenEstimator {
     observe(request: ModelRequest, actualPromptTokens: number, modelFingerprint?: string): void;
 }
 
+/**
+ * @fileoverview 工作区物理身份解析、路径规范化与目录边界校验。
+ *
+ * 约束、边界与为什么：
+ * 1. 绝对路径与 native 规范化：
+ *    Core 处于 Headless 环境，禁止依赖隐式进程工作目录（process.cwd 机制）或 process.chdir 进行相对路径解析。
+ *    所有工作区与执行目录参数必须由宿主提供绝对路径，并通过 fs.realpathSync.native 展开符号链接与 Windows 8.3 短名。
+ * 2. Windows 盘符与大小写统一：
+ *    Windows 文件系统大小写不敏感且保留驱动器盘符。在 Windows 下统一盘符大写（如 "c:\" -> "C:\"），
+ *    身份哈希计算使用正斜杠且全小写；POSIX 下保持原始大小写与斜杠。
+ * 3. 工作区越界防御（WORKSPACE_ESCAPE）：
+ *    执行目录 executionCwd 必须严格位于 workspaceRoot 内部或与其相同，杜绝利用上层目录跳转越过工作区边界。
+ * 4. 别名与冲突检测：
+ *    rootDir / cwd 作为兼容别名；若与 workspaceRoot / executionCwd 同时提供且物理路径不一致，必须立即显式报错。
+ */
+/**
+ * 规范化 Windows 驱动器盘符为大写。
+ * 非 Windows 路径或非驱动器盘符路径原样返回。
+ */
+declare function normalizeDriveLetter(p: string): string;
+/**
+ * 将绝对路径转换为操作系统原生物理长路径。
+ *
+ * 保证：
+ * - 必须接收绝对路径，否则抛出 CONFIG_INVALID；
+ * - 若路径存在，使用 fs.realpathSync.native 展开所有软链接与 Windows 8.3 短名；
+ * - 若路径尚不存在，回溯到最近存在的祖先目录取 native 物理路径后再拼接剩余子路径；
+ * - Windows 下统一规范驱动器盘符为大写。
+ *
+ * 何时失败：
+ * - 传入相对路径时抛出 CONFIG_INVALID。
+ */
+declare function toNativePhysicalPath(absolutePath: string): string;
+/**
+ * 判定两个路径在物理上是否指向同一位置。
+ *
+ * 保证：
+ * - 展开物理路径后进行对比；
+ * - Windows 下忽略大小写与斜杠差异，POSIX 下严格区分大小写。
+ */
+declare function isSamePath(pathA: string, pathB: string): boolean;
+/**
+ * 检查 target 物理路径是否位于 base 物理路径内部（或两者相同）。
+ *
+ * 保证：
+ * - 跨盘符（Windows）或父路径逃逸（..）判定为 false；
+ * - Windows 下路径对比不区分大小写。
+ *
+ * 不做什么：
+ * - 不检查路径是否实际在文件系统上存在（仅做纯路径层级边界判定）。
+ */
+declare function isPathInside(base: string, target: string): boolean;
+/**
+ * 计算规范化项目身份哈希（projectKey）。
+ *
+ * 保证：
+ * - Windows 下统一使用小写与正斜杠，使不同大小写或短名别名映射到相同 projectKey；
+ * - 输出 SHA-256 十六进制摘要，与 SessionManager 存储分桶完全同源。
+ */
+declare function computeProjectKey(canonicalProjectRoot: string): string;
+/** 供 resolveWorkspaceContext 消费的工作区解析输入。 */
+interface WorkspaceResolutionInput {
+    /** 显式工作区物理根路径。 */
+    workspaceRoot?: string;
+    /** 兼容别名：工具执行与会话基目录。 */
+    rootDir?: string;
+    /** 显式命令执行目录（必须位于 workspaceRoot 内部）。 */
+    executionCwd?: string;
+    /** 兼容别名：执行目录。 */
+    cwd?: string;
+    /** 显式项目根路径；缺省与 workspaceRoot 相同。 */
+    projectRoot?: string;
+}
+/** 规范化后的工作区上下文。 */
+interface WorkspaceContext {
+    /** 规范化后的工作区绝对物理根路径。 */
+    readonly workspaceRoot: string;
+    /** 规范化后的默认命令执行绝对物理路径。 */
+    readonly executionCwd: string;
+    /** 规范化后的项目根绝对物理路径。 */
+    readonly projectRoot: string;
+    /** 确定性的项目身份哈希。 */
+    readonly projectKey: string;
+}
+/**
+ * 解析并验证工作区上下文。
+ *
+ * 保证：
+ * - 校验 workspaceRoot 与 rootDir 必有其一，缺失时抛出 WORKSPACE_ROOT_REQUIRED；
+ * - 若两者皆提供且物理路径不一致，抛出 CONFIG_INVALID；
+ * - executionCwd / cwd 冲突时抛出 CONFIG_INVALID；
+ * - executionCwd 必须位于 workspaceRoot 内部，越界时抛出 WORKSPACE_ESCAPE；
+ * - 所有输出路径均为 native 规范化绝对路径，不依赖隐式 process.cwd 寻址。
+ *
+ * 何时失败：
+ * - 缺少工作区根（WORKSPACE_ROOT_REQUIRED）；
+ * - 路径为非绝对路径或别名冲突（CONFIG_INVALID）；
+ * - 执行目录越界（WORKSPACE_ESCAPE）。
+ */
+declare function resolveWorkspaceContext(input: WorkspaceResolutionInput): WorkspaceContext;
+
+/** 本次会话的自动执行边界；FullAccess 只能由宿主为本次会话显式选择。 */
+type SessionMode = 'Approval' | 'Plan' | 'Auto' | 'FullAccess';
+/** 规则动作与裁决结果共用同一词表；ask 表示交人工审批，不是放行。 */
+type PermissionAction = 'allow' | 'ask' | 'deny';
+/** 一次 Shell 执行的精确目标；字段组合构成审批与缓存命中的身份，任何维度都不允许通配。 */
+interface ShellScope {
+    command: string;
+    interpreter: string;
+    executablePath?: string;
+    cwd: string;
+    /** 解释器身份摘要（路径、大小、mtime 推导）；解释器被替换后规则与缓存即失配。 */
+    executableDigest?: string;
+    /** 命令直接引用的工作目录内脚本的内容摘要；仅单脚本命令可计算，组合命令缺省。 */
+    scriptDigest?: string;
+    /** 执行前复核用指纹；审批后重新推导不一致时按目标漂移拒绝执行。 */
+    executionFingerprint?: string;
+}
+/** 宿主提供的显式规则；tool / capability / shell 三种范围必须恰好声明一个。 */
+interface PermissionRule {
+    action: PermissionAction;
+    tool?: string;
+    capability?: Capability;
+    shell?: ShellScope;
+}
+/** 权限裁决的全部输入；硬限制与缓存命中由宿主查询后以标志位传入，策略本身不持有状态。 */
+interface PermissionRequest {
+    mode: SessionMode;
+    toolName: string;
+    capabilities: readonly Capability[];
+    /** 危险性来自工具元数据；未命中 allow 规则时，非 FullAccess 模式一律降级为 ask。 */
+    dangerous?: boolean;
+    /** 宿主硬限制；命中即拒绝，优先级高于一切规则与缓存。 */
+    hardDenied?: boolean;
+    shell?: ShellScope;
+    /** 规则表须先经 validatePermissionRules 校验；同动作规则按声明顺序取首个命中。 */
+    rules?: readonly PermissionRule[];
+    /** 会话缓存命中标志（来自 SessionApprovalCache）；仅在 deny / ask 规则都未命中时生效。 */
+    cachedApproval?: boolean;
+    /** 会话缓存拒绝标志；在 deny 规则之后、ask 规则之前生效。 */
+    cachedDenial?: boolean;
+}
+/** 裁决结果及其来源；source 供审计区分硬限制、Plan、规则、缓存与模式默认。 */
+interface PermissionDecision {
+    decision: PermissionAction;
+    source: 'hard_limit' | 'plan' | 'explicit_rule' | 'session_cache' | 'mode_default';
+    /** 命中规则在 rules 中的下标；仅 source 为 explicit_rule 时存在。 */
+    ruleIndex?: number;
+}
+/** 拒绝含糊的 Shell 前缀/通配符和结构不完整的规则。 */
+declare function validatePermissionRules(rules: readonly PermissionRule[]): void;
+/** 纯策略裁决；宿主硬限制和 Plan 始终先于任何规则或会话缓存。 */
+declare class PermissionPolicy {
+    /**
+     * 裁决顺序固定：硬限制 → Plan 收窄 → deny 规则 → 会话缓存拒绝 → ask 规则 →
+     * 会话缓存允许 → allow 规则（run_command 必须带 shell 范围，工具级 allow 不能放行命令）
+     * → 模式默认。同一输入总是得到同一裁决，不读取任何外部状态。
+     */
+    decide(request: PermissionRequest): PermissionDecision;
+}
+/** 只向模型展示当前模式与整项拒绝规则允许请求的工具。 */
+declare function visibleTools(tools: readonly Tool[], mode: SessionMode, rules?: readonly PermissionRule[]): Tool[];
+
+/** 路径沙箱配置；workspaceRoot 是所有文件访问的词法与物理边界。 */
+interface SandboxConfig {
+    /** 显式工作区物理根路径。 */
+    workspaceRoot?: string;
+    /** 兼容别名：等同于 workspaceRoot。 */
+    rootDir?: string;
+    /**
+     * 严格模式：任何解析后落在 workspaceRoot 之外的物理路径一律拒绝，
+     * 不存在 fail-open 开关。
+     */
+    allowSymlinks?: boolean;
+}
+/**
+ * 把文件访问限制在 workspaceRoot 内：先做词法归一化检查，再展开符号链接与 Windows 短名做物理检查，两层都通过才放行。
+ * 由 AgentSession 会话持有独立实例，避免全局单例缓存串扰。
+ */
+declare class PathSandbox {
+    /** 显式工作区绝对物理根路径。 */
+    readonly workspaceRoot: string;
+    /** 兼容别名：等同于 workspaceRoot。 */
+    readonly rootDir: string;
+    readonly allowSymlinks: boolean;
+    private cachedRealRootDir?;
+    constructor(config: SandboxConfig);
+    /**
+     * workspaceRoot 的物理路径。经过 toNativePhysicalPath 展开符号链接与 8.3 短名。
+     */
+    private get realRootDir();
+    /**
+     * 检查并解析安全路径
+     * 1. 解析相对路径为相对于 workspaceRoot 的绝对路径
+     * 2. 词法检查：`..` 归一化后必须仍在 workspaceRoot 内
+     * 3. 物理检查：解析符号链接与短名后的真实物理路径必须仍在 workspaceRoot 内
+     */
+    resolveSafePath(targetPath: string): string;
+    /**
+     * 把词法路径映射为物理路径。
+     *
+     * 关键点在于**向上回溯到最近一个真实存在的祖先**再取 realpath，然后把尚未存在的尾段拼回去：
+     * - 目标已存在 → 直接 realpath，符号链接立刻被展开；
+     * - 目标不存在(典型场景：write_file 新建文件) → 若只看目标本身，所有校验都会被跳过，
+     *   于是 `write_file('linkDir/new.txt')` 可以借道指向外部的 linkDir 越界写入。
+     *   回溯到 linkDir 取 realpath 即可识破这种穿透。
+     */
+    private toPhysicalPath;
+}
+
+/**
+ * @fileoverview 子代理权限求交（ChildGrant）与角色模型路由。
+ *
+ * 约束、边界与为什么：
+ * 1. 逐轴求交（Intersection Only）：
+ *    子代理的权限永远是「父级有效策略」、「角色预设上界」与「显式 ChildGrant 请求」三者的交集。
+ *    任何维度（模式、规则、能力、工具、工作区、深度、预算）只能收紧，绝对不得越级放宽。
+ * 2. 祖先 Deny 并集继承与 Ask 保留：
+ *    祖先链上的所有 deny 规则无条件继承，子代理无法绕过；祖先的 ask 规则必须保留，
+ *    不因子代理声明 allow 规则或 FullAccess 模式而消失。
+ * 3. 角色预设为单一真源：
+ *    - explore：只读探索，禁用通用 Shell 与写能力，首选场景 fast；
+ *    - planner：分析规划，禁用通用 Shell 与写能力，首选场景 planning；
+ *    - implement：具体实施，可委派写与执行权限，首选场景 execution；
+ *    - advisor：纯文本推理，工具集合严格为空，首选场景 planning；
+ *    - custom：自定义工具白名单，继承父场景绑定，必须显式声明 allowedTools。
+ * 4. Plan 模式硬约束与深度熔断：
+ *    Plan 模式绝对禁止 agent:spawn；达到最大深度（默认 3，硬上限 5）的子代理绝对禁止继续派生。
+ * 5. 防伪造与不可委派拦截：
+ *    请求不存在于父可用工具列表中的工具名，立即拒绝并抛出 TOOL_NOT_DELEGATABLE。
+ */
+
+/** 子代理业务角色预设。 */
+type SubagentRole = 'explore' | 'planner' | 'implement' | 'advisor' | 'custom';
+/** 默认子代理派生深度限制。根代理深度为 0，深度达到 3 时不可再派生。 */
+declare const DEFAULT_MAX_SUBAGENT_DEPTH = 3;
+/** 运行时子代理硬上限深度。任何配置不得超过此深度。 */
+declare const HARD_LIMIT_MAX_SUBAGENT_DEPTH = 5;
+/** 子代理限额配置。 */
+interface ChildLimits {
+    /** 允许的最大模型步骤数；默认 15。 */
+    maxSteps: number;
+    /** 单任务最大墙钟执行时间（毫秒）；默认 300,000（5分钟）。 */
+    timeoutMs: number;
+}
+/** 默认子代理限额。 */
+declare const DEFAULT_CHILD_LIMITS: Readonly<ChildLimits>;
+/** 角色预设定义规范。 */
+interface RolePresetDefinition {
+    /** 角色唯一标识。 */
+    readonly role: SubagentRole;
+    /** 中文说明。 */
+    readonly description: string;
+    /** 绑定的首选场景模型角色；custom 继承父轮。 */
+    readonly preferredRole: PrimaryModelRole | 'inherit';
+    /** 允许的能力上界集合；不在集合内的能力即使父级具备也被剥离。 */
+    readonly allowedCapabilities: readonly Capability[];
+    /** 绝对禁止的能力集合；在求交时强制剔除。 */
+    readonly disallowedCapabilities: readonly Capability[];
+    /** 是否允许工具集合非空；advisor 强制要求为空。 */
+    readonly allowTools: boolean;
+    /** 是否需要显式提供工具白名单；custom 必须显式提供。 */
+    readonly requireExplicitTools: boolean;
+}
+/**
+ * 角色预设单一真源映射表。
+ */
+declare const ROLE_PRESETS: Readonly<Record<SubagentRole, RolePresetDefinition>>;
+/** 获取指定角色的预设定义。若角色不存在抛出 CONFIG_INVALID。 */
+declare function getRolePreset(role: string): RolePresetDefinition;
+/** 派生子代理时的请求载荷（ChildGrant）。由调用方或 spawn_agent 工具传入。 */
+interface ChildGrant {
+    /** 申请的角色。 */
+    role: SubagentRole;
+    /** 可选工具白名单收紧；若指定必须为父可用工具子集；custom 角色必选。 */
+    allowedTools?: readonly string[];
+    /** 显式声明允许的能力子集；只能收紧。 */
+    allowedCapabilities?: readonly Capability[];
+    /** 子任务追加的补充权限规则（只能收紧）。 */
+    permissionRules?: readonly PermissionRule[];
+    /** 申请生效的会话模式；只能比父模式更严格或相同，不可放宽。 */
+    mode?: SessionMode;
+    /** 子任务执行工作目录；必须位于父工作区内部。 */
+    executionCwd?: string;
+    /** 子任务运行限额；只能比默认/父限额更严格。 */
+    limits?: Partial<ChildLimits>;
+    /** 显式场景或模型覆盖；仅在宿主允许时生效。 */
+    modelOverride?: string;
+}
+/** 父会话在派生时刻的有效策略快照。 */
+interface ParentPolicySnapshot {
+    /** 父会话当前模式。 */
+    mode: SessionMode;
+    /** 父会话当前生效的全部规则（含祖先 deny 规则）。 */
+    rules: readonly PermissionRule[];
+    /** 父会话可用工具详细列表或元数据。 */
+    availableTools: readonly (Tool | {
+        name: string;
+        metadata?: {
+            permissions?: Capability[];
+        };
+    })[];
+    /** 父会话物理工作区根绝对路径。 */
+    workspaceRoot: string;
+    /** 父会话当前命令执行工作目录绝对路径。 */
+    executionCwd: string;
+    /** 父会话当前深度（根会话为 0）。 */
+    currentDepth: number;
+    /** 允许的最大深度（缺省为 DEFAULT_MAX_SUBAGENT_DEPTH）。 */
+    maxDepth?: number;
+    /** 父会话当前场景模型角色。 */
+    currentPrimaryRole?: PrimaryModelRole;
+    /** 父会话可用限额。 */
+    limits?: Partial<ChildLimits>;
+}
+/** 逐轴求交后派生出的子代理有效策略。 */
+interface DerivedChildPolicy {
+    /** 子代理最终生效的 SessionMode。 */
+    readonly mode: SessionMode;
+    /** 子代理最终生效的权限规则（祖先 deny 并集 + 祖先 ask 保留 + 子收紧规则）。 */
+    readonly rules: readonly PermissionRule[];
+    /** 子代理最终可使用的工具名称列表。 */
+    readonly allowedTools: readonly string[];
+    /** 子代理最终允许的能力集合。 */
+    readonly allowedCapabilities: readonly Capability[];
+    /** 子代理规范化命令执行绝对工作目录。 */
+    readonly executionCwd: string;
+    /** 子代理所在任务树深度。 */
+    readonly depth: number;
+    /** 子代理生效的场景模型角色。 */
+    readonly preferredRole: PrimaryModelRole;
+    /** 子代理是否允许继续派生（agent:spawn）。 */
+    readonly canSpawnSubagent: boolean;
+    /** 子代理生效的运行限额。 */
+    readonly limits: Readonly<ChildLimits>;
+}
+/**
+ * 模式收紧计算：比较并选择两者中更严格的模式。
+ * 子代理绝对不能比父模式更宽松。
+ */
+declare function tightenMode(parentMode: SessionMode, requestedMode?: SessionMode): SessionMode;
+/**
+ * 核心纯函数：逐轴求交派生子代理有效权限与策略。
+ *
+ * 保证：
+ * - 纯函数无外部副作用，不依赖网络、文件系统（除纯路径层级判断）或全局状态；
+ * - 祖先 deny 规则取并集继承，祖先 ask 规则完整保留；
+ * - 模式、能力、工具、工作区、深度与限额逐轴求交收紧；
+ * - 角色预设与调用方 ChildGrant 白名单求交；
+ * - 若请求未知工具名或父级未提供的工具名，立即拒绝并抛出 TOOL_NOT_DELEGATABLE；
+ * - Plan 模式绝对禁止 agent:spawn；
+ * - 深度达到或超过 maxDepth 时绝对禁止继续派生子代理。
+ *
+ * 何时失败：
+ * - custom 角色未提供 allowedTools（CONFIG_INVALID）；
+ * - 包含不可委派的未知工具名（TOOL_NOT_DELEGATABLE）；
+ * - 子执行目录越出父工作区根范围（WORKSPACE_ESCAPE）；
+ * - 父处于 Plan 模式且尝试申请破坏性能力（PERMISSION_DENIED）；
+ * - 角色名称未知（CONFIG_INVALID）。
+ */
+declare function deriveChildPolicy(parent: ParentPolicySnapshot, grant: ChildGrant): DerivedChildPolicy;
+
+/** 执行能力的最小分类；权限规则、模式裁决与工具元数据声明共用这一词汇表。 */
+type Capability = 'fs:read' | 'fs:write' | 'exec' | 'net:outbound' | 'env:read' | 'agent:spawn' | 'external:call';
+/**
+ * 外部调用的精确执行身份；供审批缓存、发送前复核与审计消费。
+ * 包含服务端物理身份、连接代次、目录 epoch 与定义摘要等不可伪造字段。
+ */
+interface ToolExecutionIdentity {
+    serverIdentity?: string;
+    connectionGeneration?: number;
+    catalogEpoch?: number;
+    toolDigest?: string;
+    [key: string]: unknown;
+}
+/**
+ * 显式 opt-in 规范化执行结果；普通对象返回值保持兼容不强制包装。
+ */
+interface ToolExecutionResult {
+    content: string;
+    isError?: boolean;
+    errorCode?: string;
+    retryPolicy?: 'never' | 'after_user_action';
+    execution?: ToolResultExecution;
+}
+interface ToolMetadata {
+    /** 注册来源标记（如 'builtin'）；注册表据此执行冲突策略并支持按源注销。 */
+    source?: string;
+    /** 标记危险工具；未命中 allow 规则时，非 FullAccess 模式一律降级为 ask 而非按模式默认放行。 */
+    dangerous?: boolean;
+    /** 所需能力的声明；v0.0.1 不据此授权，v0.0.2 的执行前权限决策才会消费。 */
+    permissions?: Capability[];
+    /** 工具自身等待进程资源回收，执行器不可再使用通用 Promise.race 超时。 */
+    managesTimeout?: boolean;
+    /** 只读提示；工具声明自身无副作用，供 UI 展示与只读过滤参考。 */
+    readOnlyHint?: boolean;
+}
+/** 工具执行期由宿主注入的运行环境；信号取消后工具应尽快清理在途资源再返回。 */
+interface ToolContext {
+    /** 显式工作区物理根路径，经 native realpath 规范化。 */
+    workspaceRoot?: string;
+    /** 显式命令执行工作目录绝对路径（位于 workspaceRoot 内部）。 */
+    executionCwd?: string;
+    /** 会话持有的 PathSandbox 独占实例；文件类工具优先使用此沙箱。 */
+    sandbox?: PathSandbox;
+    /** 兼容别名：本次执行的沙箱根目录；等同于 workspaceRoot。 */
+    rootDir: string;
+    signal?: AbortSignal;
+    logger?: (message: string) => void;
+    /** 命令工具在真实进程创建后调用；审计失败时须先回收进程再报告结果未知。 */
+    onProcessSpawned?: () => Promise<void>;
+    onProgress?: (progress: {
+        elapsedMs: number;
+        outputBytes: number;
+    }) => void;
+    /** 子代理调度与后台执行上下文字段。 */
+    sessionId?: string;
+    branchId?: string;
+    runId?: string;
+    toolCallId?: string;
+    depth?: number;
+    agentId?: string;
+    rootTaskId?: string;
+    /** 父事务提交成功后的回调注册器；仅当整批工具消息持久化落盘后才调用。 */
+    onCommitted?: (action: () => void | Promise<void>) => void;
+    /** 任务准备失败或父事务未持久化时的回滚清理动作注册器。 */
+    onRollback?: (action: () => void | Promise<void>) => void;
+    /** 父级会话有效安全策略快照（用于派生子代理时的真实基线求交）。 */
+    parentPolicy?: ParentPolicySnapshot;
+}
+/**
+ * 工具输入参数校验结果；valid 为 false 或抛出异常均阻止审批和发送。
+ */
+interface ToolInputValidation {
+    valid: boolean;
+    message?: string;
+}
+/** 工具契约；parameters 是 JSON Schema，模型只能看到经 toToolDefinition 投影后的三个字段。 */
+interface Tool<TInput = Record<string, unknown>, TOutput = unknown> {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>;
+    readonly metadata?: ToolMetadata;
+    /** 声明本次输入的精确执行目标，供审批展示与执行前指纹复核；无固定执行目标的工具不实现。 */
+    approvalScope?(input: TInput, rootDir: string, executionCwd?: string): ShellScope;
+    /** 本次执行身份；审批缓存与执行前复核消费，缺省保持旧工具规则。 */
+    executionIdentity?(input: TInput, rootDir: string): ToolExecutionIdentity;
+    /** 无副作用地校验最终参数，不修改参数、不访问远端；异常与拒绝均阻止审批和发送。 */
+    validateInput?(input: TInput): ToolInputValidation | undefined;
+    /** 显式 opt-in 转换为标准执行结果；未提供时普通返回值继续作为常规输出。 */
+    toExecutionResult?(raw: TOutput): ToolExecutionResult;
+    execute(input: TInput, ctx: ToolContext): Promise<TOutput>;
+}
+/** 恒等构造器：只为工具实现提供类型推断与统一书写形式，不产生任何运行时包装。 */
+declare function defineTool<TInput = Record<string, unknown>, TOutput = unknown>(tool: Tool<TInput, TOutput>): Tool<TInput, TOutput>;
+/** 投影为模型可见的工具描述；刻意丢弃 metadata 与 approvalScope，执行侧信息不进入协议。 */
+declare function toToolDefinition(tool: Tool): ToolDefinition;
+
+/**
+ * @fileoverview 共享工作区写租约（Workspace Write Lease）协调器。
+ *
+ * 约束、边界与为什么：
+ * 1. 串行化共享工作区写操作：
+ *    当多个智能体（如父代理与后台子代理）在同一物理工作区运行且未挂载独立 Git worktree 时，
+ *    并发写入会导致文件撕裂与状态脏化。通过写租约对文件写入、Shell 执行与外部写操作进行强制互斥。
+ * 2. 覆盖范围不仅限文件写：
+ *    写操作涵盖声明了 `fs:write` 的工具、声明了 `exec` 的命令执行、以及未显式声明 `readOnlyHint: true` 的外部 MCP 工具。
+ * 3. 安全释放与排队唤醒：
+ *    操作完成、异常中止或被取消时，必须在 finally 中安全释放写租约；释放后原子唤醒队列中的下一个排队者。
+ *    支持 AbortSignal 取消与超时保护，被取消的排队项安全从队列剔除，防止死锁。
+ * 4. 物理根分桶与大小写归一：
+ *    租约按物理路径（经 toNativePhysicalPath 规范化）分桶，不同工作区互不影响；
+ *    Windows 下路径对比大小写不敏感。
+ */
+
+/** 活动写租约句柄。持有者调用 release() 释放写锁。 */
+interface WorkspaceWriteLease {
+    /** 租约唯一标识。 */
+    readonly leaseId: string;
+    /** 规范化工作区物理根路径。 */
+    readonly workspaceRoot: string;
+    /** 租约持有者标识（如 sessionId 或 agentId）。 */
+    readonly ownerId: string;
+    /** 获取租约的时间戳（毫秒）。 */
+    readonly acquiredAt: number;
+    /** 释放租约并唤醒后续排队者；多次调用幂等。 */
+    release(): void;
+}
+/** 判定一个工具是否属于具有写副作用的操作。 */
+declare function isWriteOperation(tool: Tool): boolean;
+/**
+ * 工作区写租约协调器。
+ * 支持同工作区写操作排队与互斥，异工作区并发无阻。
+ */
+declare class WorkspaceLeaseCoordinator {
+    private readonly buckets;
+    private getBucketKey;
+    private getOrCreateBucket;
+    /**
+     * 检查指定工作区当前是否有活跃的写租约。
+     */
+    isLocked(workspaceRoot: string): boolean;
+    /**
+     * 获取指定工作区当前活跃的租约所有者信息。
+     */
+    getActiveLease(workspaceRoot: string): {
+        leaseId: string;
+        ownerId: string;
+        acquiredAt: number;
+    } | undefined;
+    /**
+     * 尝试非阻塞获取写租约。若当前被占用立即返回 undefined。
+     */
+    tryAcquire(workspaceRoot: string, ownerId: string): WorkspaceWriteLease | undefined;
+    /**
+     * 阻塞排队获取写租约。
+     *
+     * 保证：
+     * - 若无活动租约，立即获取并返回；
+     * - 若被占用，加入 FIFO 队列等待；
+     * - 支持 AbortSignal 取消；取消时立即移出队列并抛出 ABORTED；
+     * - 支持可选超时，超时抛出 LEASE_TIMEOUT。
+     */
+    acquire(workspaceRoot: string, ownerId: string, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<WorkspaceWriteLease>;
+    private removeFromQueue;
+    private releaseLease;
+    /**
+     * 使用写租约包装异步操作。执行完毕或发生异常时在 finally 中安全释放。
+     */
+    withWriteLease<T>(workspaceRoot: string, ownerId: string, action: (lease: WorkspaceWriteLease) => Promise<T>, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<T>;
+}
+/** 运行时共享写租约协调器单例。 */
+declare const sharedWorkspaceLeaseCoordinator: WorkspaceLeaseCoordinator;
+
 type CompactionReason = 'threshold' | 'manual' | 'overflow';
 /**
  * 最近一次请求准备或只读检查发布的上下文快照，供宿主展示与诊断。
@@ -1126,8 +2078,8 @@ interface ContextManagerOptions {
     onDiagnostic?: (message: string) => void;
     /** 摘要角色绑定来源；缺省时跳过二级摘要，仅保留一级剪裁。 */
     router?: ModelRouter;
-    /** 转发给文件观察提取；项目根不作为历史工具相对路径的推断依据。 */
-    projectRoot?: string;
+    /** 转发给文件观察提取；必须显式指定物理项目根绝对路径，禁止缺省隐式回退。 */
+    projectRoot: string;
     /** 当前已注册的内置工具名集合；剪裁白名单只认可其中的内置只读工具。 */
     builtInToolNames?: () => ReadonlySet<string>;
     /** 每个摘要 attempt 的使用量回调；在候选校验前触发，失败摘要仍计消耗。 */
@@ -1461,193 +2413,55 @@ interface SkillCatalog {
     text: string;
     included: number;
     omitted: number;
-    estimatedTokens: number;
-}
-/** 生成确定性 L2.5；预算含标题、XML、转义及遗漏提示，只删完整条目。 */
-declare function formatSkillCatalog(skills: readonly SkillMetadata[], contextWindow?: number, remainingTokens?: number): SkillCatalog;
-/** 模型目录分页输入；游标只定位快照，不提供信任或正文访问授权。 */
-interface SkillQuery {
-    query?: string;
-    cursor?: string;
-    limit?: number;
-}
-/** 有界模型元数据页；不包含正文，游标按实际返回条目推进。 */
-interface SkillQueryPage {
-    skills: {
-        name: string;
-        description: string;
-        scope: string;
-        argumentHint?: string;
-    }[];
-    total: number;
-    nextCursor?: string;
-}
-
-/** 确定性技能注册表；刷新原子替换快照，运行中加载必须与发现指纹一致。 */
-declare class SkillRegistry {
-    private readonly options;
-    private definitions;
-    private warnings;
-    private revisionValue;
-    /** 固定宿主配置副本，外部对象变更不能静默改变本轮发现或信任。 */
-    constructor(options: SkillOptions);
-    /** 获取独立诊断副本，调用方不能修改生效候选或权限。 */
-    get diagnostics(): SkillDiagnostic[];
-    /** 快照游标身份随正文、来源、可用性变化而失效。 */
-    get revision(): string;
-    /** 是否由宿主启用；关闭只影响本次能力，不删除历史或文件。 */
-    get enabled(): boolean;
-    /** 每轮开始重新发现；取消不发布半个快照，非法单文件只产生诊断。 */
-    refresh(signal?: AbortSignal): Promise<void>;
-    /** 按名称查询胜出元数据副本；未知名称返回 undefined，正文仅由 load 校验后懒读取。 */
-    get(name: string): SkillMetadata | undefined;
-    /** 宿主可检查不可用条目；模型/用户视图分别施加调用控制，均不读取正文。 */
-    list(caller?: 'host' | 'model' | 'user', query?: string): SkillMetadata[];
-    /** 按当前快照校验调用控制与物理身份，不接受模型提供的信任或 caller 升级。 */
-    load(name: string, caller: 'model' | 'user', signal?: AbortSignal): Promise<SkillDefinition>;
-    /** 查询可信模型集合；过期游标可修正，预算不足不返回不前进的分页。 */
-    queryModel(input?: SkillQuery, remainingTokens?: number): SkillQueryPage;
-    /** 复核配置根、词法发现路径和原文件字节，返回本次有界读取文本；漂移要求新运行，不能热替换。 */
-    verify(skill: SkillMetadata, signal?: AbortSignal): Promise<string>;
-}
-
-/** 本次会话的自动执行边界；FullAccess 只能由宿主为本次会话显式选择。 */
-type SessionMode = 'Approval' | 'Plan' | 'Auto' | 'FullAccess';
-/** 规则动作与裁决结果共用同一词表；ask 表示交人工审批，不是放行。 */
-type PermissionAction = 'allow' | 'ask' | 'deny';
-/** 一次 Shell 执行的精确目标；字段组合构成审批与缓存命中的身份，任何维度都不允许通配。 */
-interface ShellScope {
-    command: string;
-    interpreter: string;
-    executablePath?: string;
-    cwd: string;
-    /** 解释器身份摘要（路径、大小、mtime 推导）；解释器被替换后规则与缓存即失配。 */
-    executableDigest?: string;
-    /** 命令直接引用的工作目录内脚本的内容摘要；仅单脚本命令可计算，组合命令缺省。 */
-    scriptDigest?: string;
-    /** 执行前复核用指纹；审批后重新推导不一致时按目标漂移拒绝执行。 */
-    executionFingerprint?: string;
-}
-/** 宿主提供的显式规则；tool / capability / shell 三种范围必须恰好声明一个。 */
-interface PermissionRule {
-    action: PermissionAction;
-    tool?: string;
-    capability?: Capability;
-    shell?: ShellScope;
-}
-/** 权限裁决的全部输入；硬限制与缓存命中由宿主查询后以标志位传入，策略本身不持有状态。 */
-interface PermissionRequest {
-    mode: SessionMode;
-    toolName: string;
-    capabilities: readonly Capability[];
-    /** 危险性来自工具元数据；未命中 allow 规则时，非 FullAccess 模式一律降级为 ask。 */
-    dangerous?: boolean;
-    /** 宿主硬限制；命中即拒绝，优先级高于一切规则与缓存。 */
-    hardDenied?: boolean;
-    shell?: ShellScope;
-    /** 规则表须先经 validatePermissionRules 校验；同动作规则按声明顺序取首个命中。 */
-    rules?: readonly PermissionRule[];
-    /** 会话缓存命中标志（来自 SessionApprovalCache）；仅在 deny / ask 规则都未命中时生效。 */
-    cachedApproval?: boolean;
-    /** 会话缓存拒绝标志；在 deny 规则之后、ask 规则之前生效。 */
-    cachedDenial?: boolean;
-}
-/** 裁决结果及其来源；source 供审计区分硬限制、Plan、规则、缓存与模式默认。 */
-interface PermissionDecision {
-    decision: PermissionAction;
-    source: 'hard_limit' | 'plan' | 'explicit_rule' | 'session_cache' | 'mode_default';
-    /** 命中规则在 rules 中的下标；仅 source 为 explicit_rule 时存在。 */
-    ruleIndex?: number;
-}
-/** 拒绝含糊的 Shell 前缀/通配符和结构不完整的规则。 */
-declare function validatePermissionRules(rules: readonly PermissionRule[]): void;
-/** 纯策略裁决；宿主硬限制和 Plan 始终先于任何规则或会话缓存。 */
-declare class PermissionPolicy {
-    /**
-     * 裁决顺序固定：硬限制 → Plan 收窄 → deny 规则 → 会话缓存拒绝 → ask 规则 →
-     * 会话缓存允许 → allow 规则（run_command 必须带 shell 范围，工具级 allow 不能放行命令）
-     * → 模式默认。同一输入总是得到同一裁决，不读取任何外部状态。
-     */
-    decide(request: PermissionRequest): PermissionDecision;
-}
-/** 只向模型展示当前模式与整项拒绝规则允许请求的工具。 */
-declare function visibleTools(tools: readonly Tool[], mode: SessionMode, rules?: readonly PermissionRule[]): Tool[];
-
-/** 执行能力的最小分类；权限规则、模式裁决与工具元数据声明共用这一词汇表。 */
-type Capability = 'fs:read' | 'fs:write' | 'exec' | 'net:outbound' | 'env:read' | 'agent:spawn' | 'external:call';
-/**
- * 外部调用的精确执行身份；供审批缓存、发送前复核与审计消费。
- * 包含服务端物理身份、连接代次、目录 epoch 与定义摘要等不可伪造字段。
- */
-interface ToolExecutionIdentity {
-    serverIdentity?: string;
-    connectionGeneration?: number;
-    catalogEpoch?: number;
-    toolDigest?: string;
-    [key: string]: unknown;
-}
-/**
- * 显式 opt-in 规范化执行结果；普通对象返回值保持兼容不强制包装。
- */
-interface ToolExecutionResult {
-    content: string;
-    isError?: boolean;
-    errorCode?: string;
-    retryPolicy?: 'never' | 'after_user_action';
-    execution?: ToolResultExecution;
-}
-interface ToolMetadata {
-    /** 注册来源标记（如 'builtin'）；注册表据此执行冲突策略并支持按源注销。 */
-    source?: string;
-    /** 标记危险工具；未命中 allow 规则时，非 FullAccess 模式一律降级为 ask 而非按模式默认放行。 */
-    dangerous?: boolean;
-    /** 所需能力的声明；v0.0.1 不据此授权，v0.0.2 的执行前权限决策才会消费。 */
-    permissions?: Capability[];
-    /** 工具自身等待进程资源回收，执行器不可再使用通用 Promise.race 超时。 */
-    managesTimeout?: boolean;
-    /** 只读提示；工具声明自身无副作用，供 UI 展示与只读过滤参考。 */
-    readOnlyHint?: boolean;
-}
-/** 工具执行期由宿主注入的运行环境；信号取消后工具应尽快清理在途资源再返回。 */
-interface ToolContext {
-    /** 本次执行的沙箱根目录；文件类工具以此为界解析相对路径并拒绝越界。 */
-    rootDir: string;
-    signal?: AbortSignal;
-    logger?: (message: string) => void;
-    /** 命令工具在真实进程创建后调用；审计失败时须先回收进程再报告结果未知。 */
-    onProcessSpawned?: () => Promise<void>;
-    onProgress?: (progress: {
-        elapsedMs: number;
-        outputBytes: number;
-    }) => void;
+    estimatedTokens: number;
 }
-/**
- * 工具输入参数校验结果；valid 为 false 或抛出异常均阻止审批和发送。
- */
-interface ToolInputValidation {
-    valid: boolean;
-    message?: string;
+/** 生成确定性 L2.5；预算含标题、XML、转义及遗漏提示，只删完整条目。 */
+declare function formatSkillCatalog(skills: readonly SkillMetadata[], contextWindow?: number, remainingTokens?: number): SkillCatalog;
+/** 模型目录分页输入；游标只定位快照，不提供信任或正文访问授权。 */
+interface SkillQuery {
+    query?: string;
+    cursor?: string;
+    limit?: number;
 }
-/** 工具契约；parameters 是 JSON Schema，模型只能看到经 toToolDefinition 投影后的三个字段。 */
-interface Tool<TInput = Record<string, unknown>, TOutput = unknown> {
-    readonly name: string;
-    readonly description: string;
-    readonly parameters: Record<string, unknown>;
-    readonly metadata?: ToolMetadata;
-    /** 声明本次输入的精确执行目标，供审批展示与执行前指纹复核；无固定执行目标的工具不实现。 */
-    approvalScope?(input: TInput, rootDir: string): ShellScope;
-    /** 本次执行身份；审批缓存与执行前复核消费，缺省保持旧工具规则。 */
-    executionIdentity?(input: TInput, rootDir: string): ToolExecutionIdentity;
-    /** 无副作用地校验最终参数，不修改参数、不访问远端；异常与拒绝均阻止审批和发送。 */
-    validateInput?(input: TInput): ToolInputValidation | undefined;
-    /** 显式 opt-in 转换为标准执行结果；未提供时普通返回值继续作为常规输出。 */
-    toExecutionResult?(raw: TOutput): ToolExecutionResult;
-    execute(input: TInput, ctx: ToolContext): Promise<TOutput>;
+/** 有界模型元数据页；不包含正文，游标按实际返回条目推进。 */
+interface SkillQueryPage {
+    skills: {
+        name: string;
+        description: string;
+        scope: string;
+        argumentHint?: string;
+    }[];
+    total: number;
+    nextCursor?: string;
+}
+
+/** 确定性技能注册表；刷新原子替换快照，运行中加载必须与发现指纹一致。 */
+declare class SkillRegistry {
+    private readonly options;
+    private definitions;
+    private warnings;
+    private revisionValue;
+    /** 固定宿主配置副本，外部对象变更不能静默改变本轮发现或信任。 */
+    constructor(options: SkillOptions);
+    /** 获取独立诊断副本，调用方不能修改生效候选或权限。 */
+    get diagnostics(): SkillDiagnostic[];
+    /** 快照游标身份随正文、来源、可用性变化而失效。 */
+    get revision(): string;
+    /** 是否由宿主启用；关闭只影响本次能力，不删除历史或文件。 */
+    get enabled(): boolean;
+    /** 每轮开始重新发现；取消不发布半个快照，非法单文件只产生诊断。 */
+    refresh(signal?: AbortSignal): Promise<void>;
+    /** 按名称查询胜出元数据副本；未知名称返回 undefined，正文仅由 load 校验后懒读取。 */
+    get(name: string): SkillMetadata | undefined;
+    /** 宿主可检查不可用条目；模型/用户视图分别施加调用控制，均不读取正文。 */
+    list(caller?: 'host' | 'model' | 'user', query?: string): SkillMetadata[];
+    /** 按当前快照校验调用控制与物理身份，不接受模型提供的信任或 caller 升级。 */
+    load(name: string, caller: 'model' | 'user', signal?: AbortSignal): Promise<SkillDefinition>;
+    /** 查询可信模型集合；过期游标可修正，预算不足不返回不前进的分页。 */
+    queryModel(input?: SkillQuery, remainingTokens?: number): SkillQueryPage;
+    /** 复核配置根、词法发现路径和原文件字节，返回本次有界读取文本；漂移要求新运行，不能热替换。 */
+    verify(skill: SkillMetadata, signal?: AbortSignal): Promise<string>;
 }
-/** 恒等构造器：只为工具实现提供类型推断与统一书写形式，不产生任何运行时包装。 */
-declare function defineTool<TInput = Record<string, unknown>, TOutput = unknown>(tool: Tool<TInput, TOutput>): Tool<TInput, TOutput>;
-/** 投影为模型可见的工具描述；刻意丢弃 metadata 与 approvalScope，执行侧信息不进入协议。 */
-declare function toToolDefinition(tool: Tool): ToolDefinition;
 
 /** 归一化技能白名单；参数模式/未知名称不得退化成宽泛命令授权。 */
 declare function normalizeSkillTools(skill: SkillDefinition, tools: readonly Tool[]): ReadonlySet<string> | undefined;
@@ -1856,6 +2670,14 @@ interface ExecutorOptions {
     onToolResult?: (tool: Tool, input: Record<string, unknown>, result: ToolResultBlock) => void | Promise<void>;
     tools: ToolRegistry | ToolRegistrySnapshot;
     hooks: HookRegistry;
+    /** 显式工作区物理根路径，经 native realpath 规范化；缺省回退到 rootDir。 */
+    workspaceRoot?: string;
+    /** 显式命令执行工作目录绝对路径（位于 workspaceRoot 内部）；缺省回退到 rootDir。 */
+    executionCwd?: string;
+    /** 会话持有的 PathSandbox 独占实例；文件类工具优先使用此沙箱。 */
+    sandbox?: PathSandbox;
+    /** 共享工作区写租约协调器；并发写入互斥保护。 */
+    leaseCoordinator?: WorkspaceLeaseCoordinator;
     /** 工具执行的绝对根目录；路径解析与审批均以此为基准。 */
     rootDir: string;
     /** 会话级取消信号；与 cancel() 的内部信号合并生效。 */
@@ -1866,6 +2688,10 @@ interface ExecutorOptions {
     eventLogger?: EventLogger;
     sessionId?: string;
     runId?: string;
+    branchId?: string;
+    rootTaskId?: string;
+    depth?: number;
+    agentId?: string;
     /** 固定模式或每次裁决时读取的取值函数；宿主可中途切换。 */
     mode?: SessionMode | (() => SessionMode);
     permissionRules?: readonly PermissionRule[];
@@ -1884,6 +2710,10 @@ declare class ToolExecutor {
     private readonly onToolResult?;
     private readonly tools;
     private readonly hooks;
+    private readonly workspaceRoot;
+    private readonly executionCwd;
+    private readonly sandbox?;
+    private readonly leaseCoordinator?;
     private readonly rootDir;
     private readonly signal?;
     private readonly logger?;
@@ -1891,6 +2721,12 @@ declare class ToolExecutor {
     private readonly eventLogger?;
     private readonly sessionId?;
     private readonly runId?;
+    private readonly branchId?;
+    private readonly rootTaskId?;
+    private readonly depth?;
+    private readonly agentId?;
+    private readonly committedActions;
+    private readonly rollbackActions;
     private readonly mode;
     private readonly permissionRules;
     private readonly approvalChannel?;
@@ -1899,6 +2735,15 @@ declare class ToolExecutor {
     private readonly neverFailures;
     private readonly cancellation;
     constructor(options: ExecutorOptions);
+    /**
+     * 父工具事务提交成功后调用，按注册顺序执行所有提交动作。
+     * 动作执行成功后逐项清理对应回滚动作，若某项失败保留剩余回滚动作。
+     */
+    commit(): Promise<void>;
+    /**
+     * 父工具事务提交失败或取消时调用，按逆序执行所有回滚清理动作。
+     */
+    rollback(): Promise<void>;
     /** 中止本轮正在等待或执行的工具；调用方仍须等待 runAll 完成资源回收及结果审计。 */
     cancel(): void;
     /**
@@ -1930,6 +2775,10 @@ declare class ToolExecutor {
      * 因此内置工具仍需避免执行用户可控的同步高复杂度计算。
      */
     private withTimeout;
+    /**
+     * 构建当前会话在派生时刻的父权限策略快照。
+     */
+    private deriveParentPolicySnapshot;
 }
 
 /** 加载预检结果；只有最终成功工具结果或真实用户消息提交后才形成活动资格。 */
@@ -2062,48 +2911,6 @@ declare function cleanupCommandResults(rootDir: string, now?: number): void;
 /** 使用固定解释器执行命令；超时和中止必须先处理进程树再返回。 */
 declare function createRunCommandTool(environment: ShellEnvironment): Tool<RunCommandInput, CommandResult>;
 
-/** 路径沙箱配置；rootDir 是所有文件访问的词法与物理边界。 */
-interface SandboxConfig {
-    rootDir: string;
-    /**
-     * v0.0.1 恒为严格模式：任何解析后落在 rootDir 之外的物理路径一律拒绝，
-     * 不存在 fail-open 开关。该字段为 v0.0.2 权限引擎预留，当前不改变校验行为。
-     */
-    allowSymlinks?: boolean;
-}
-/**
- * 把文件访问限制在 rootDir 内：先做词法归一化检查，再展开符号链接做物理检查，两层都通过才放行。
- * 实例会缓存 rootDir 的物理路径，应按 rootDir 复用实例，而不是每次调用新建。
- */
-declare class PathSandbox {
-    readonly rootDir: string;
-    readonly allowSymlinks: boolean;
-    private cachedRealRootDir?;
-    constructor(config: SandboxConfig);
-    /**
-     * rootDir 的物理路径。rootDir 自身可能是一个符号链接(如 macOS 的 /var → /private/var)，
-     * 必须先归一化，否则物理路径与 rootDir 比较时会产生误判。
-     */
-    private get realRootDir();
-    /**
-     * 检查并解析安全路径
-     * 1. 解析相对路径为相对于 rootDir 的绝对路径
-     * 2. 词法检查：`..` 归一化后必须仍在 rootDir 内
-     * 3. 物理检查：解析符号链接后的真实路径必须仍在 rootDir 内
-     */
-    resolveSafePath(targetPath: string): string;
-    /**
-     * 把词法路径映射为物理路径。
-     *
-     * 关键点在于**向上回溯到最近一个真实存在的祖先**再取 realpath，然后把尚未存在的尾段拼回去：
-     * - 目标已存在 → 直接 realpath，符号链接立刻被展开；
-     * - 目标不存在(典型场景：write_file 新建文件) → 若只看目标本身，所有校验都会被跳过，
-     *   于是 `write_file('linkDir/new.txt')` 可以借道指向外部的 linkDir 越界写入。
-     *   回溯到 linkDir 取 realpath 即可识破这种穿透。
-     */
-    private toPhysicalPath;
-}
-
 declare const readFileTool: Tool<{
     path: string;
     startLine?: number;
@@ -2452,6 +3259,532 @@ declare class AgentLoop {
     run(history: CanonicalMessage[]): AsyncIterable<SessionEvent>;
 }
 
+/**
+ * @fileoverview 后台子代理任务状态机、来源元数据与限额类型定义。
+ *
+ * 约束、边界与为什么：
+ * 1. 状态机严格单向/受控回环：
+ *    preparing → accepted → running → waiting_children → completed / failed / cancelled / interrupted。
+ *    有未结束后代时，自身主轮结束必须进入 waiting_children，等待后代收口后返回 running 完成终结。
+ * 2. 来源链不可伪造（Origin Invariant）：
+ *    每项任务持有稳定的 rootTaskId、parentAgentId、parentSessionId、originBranchId、originRunId
+ *    与 spawnToolCallId，用作跨轮次对账、收件箱投递与去重键。
+ * 3. 严格容量控制：
+ *    每树活动上限 4，整运行时活动上限 8，每树累计上限 16，超额立即拒绝不排队，防止死锁。
+ */
+
+/**
+ * 子代理任务生命周期状态。
+ */
+type AgentTaskStatus = 'preparing' | 'accepted' | 'running' | 'waiting_children' | 'cancelling' | 'completed' | 'failed' | 'cancelled' | 'interrupted';
+/**
+ * 判断指定状态是否属于活跃占用槽位状态（preparing / accepted / running / waiting_children / cancelling）。
+ */
+declare function isActiveTaskStatus(status: AgentTaskStatus): boolean;
+/**
+ * 判断指定状态是否为终态（completed / failed / cancelled / interrupted）。
+ */
+declare function isTerminalTaskStatus(status: AgentTaskStatus): boolean;
+/**
+ * 描述子代理任务的来源与继承上下文。
+ */
+interface AgentTaskOrigin {
+    /** 根任务标识（同一次根用户指令启动的所有子孙任务共享）。 */
+    readonly rootTaskId: string;
+    /** 父代理 ID（根任务派生的一级子代理其 parentAgentId 为 undefined）。 */
+    readonly parentAgentId?: string;
+    /** 父会话会话 ID。 */
+    readonly parentSessionId: string;
+    /** 派生来源分支 ID。 */
+    readonly originBranchId: string;
+    /** 派生来源运行轮次 ID。 */
+    readonly originRunId: string;
+    /** 触发派生的工具调用 ID。 */
+    readonly spawnToolCallId: string;
+    /** 派生代次（从 1 开始）。 */
+    readonly generation: number;
+    /** 任务树深度（根会话为 0，一级子代理为 1，最大支持深度通常为 3）。 */
+    readonly depth: number;
+}
+/** 每棵任务树允许的最大并发活动子任务数。 */
+declare const MAX_ACTIVE_TASKS_PER_TREE = 4;
+/** 整个 AgentRuntime 允许的最大并发活动子任务数。 */
+declare const MAX_ACTIVE_TASKS_PER_RUNTIME = 8;
+/** 每棵任务树累计受理的最大任务数（失败/取消不返还额度）。 */
+declare const MAX_TOTAL_TASKS_PER_TREE = 16;
+/** 默认最大步骤数。 */
+declare const DEFAULT_MAX_STEPS = 15;
+/** 默认墙钟超时毫秒数（5 分钟）。 */
+declare const DEFAULT_TIMEOUT_MS: number;
+/** 子代理限额配置。 */
+interface AgentTaskLimits {
+    /** 最大模型交互步骤数（默认 15）。 */
+    maxSteps?: number;
+    /** 墙钟最大超时毫秒数（默认 5 分钟 = 300,000ms）。 */
+    timeoutMs?: number;
+}
+/** 创建子代理输入参数。 */
+interface SpawnAgentParams {
+    [key: string]: unknown;
+    /** 任务简要描述。 */
+    description: string;
+    /** 任务提示词与具体指令。 */
+    prompt: string;
+    /** 业务角色预设。 */
+    role: SubagentRole;
+    /** 显式限制的工具名称白名单（进一步收紧）。 */
+    allowedTools?: string[];
+    /** 子任务执行目录（必须在工作区根以内）。 */
+    cwd?: string;
+    /** 物理隔离模式。 */
+    isolation?: 'inherit' | 'worktree';
+    /** 模型覆盖参数。 */
+    modelOverride?: string;
+    /** 限额配置。 */
+    limits?: AgentTaskLimits;
+}
+/** spawn_agent 启动回执。 */
+interface SpawnAgentReceipt {
+    /** 生成的子代理唯一标识。 */
+    agentId: string;
+    /** 受理状态（固定为 'accepted'）。 */
+    status: 'accepted';
+    /** 角色预设。 */
+    role: SubagentRole;
+    /** 任务简要描述。 */
+    description: string;
+    /** 任务树深度。 */
+    depth: number;
+    /** 归属的根任务标识。 */
+    rootTaskId: string;
+    /** 解析出的模型场景角色。 */
+    modelRole: PrimaryModelRole | 'inherit';
+    /** 实际工作区根。 */
+    workspaceRoot: string;
+    /** 实际执行目录。 */
+    executionCwd: string;
+}
+/**
+ * 运行时内存中的子代理任务完整记录。
+ */
+interface AgentTaskRecord {
+    /** 子代理唯一标识。 */
+    readonly agentId: string;
+    /** 来源上下文。 */
+    readonly origin: AgentTaskOrigin;
+    /** 预设角色。 */
+    readonly role: SubagentRole;
+    /** 任务描述。 */
+    readonly description: string;
+    /** 任务 Prompt。 */
+    readonly prompt: string;
+    /** 当前生命周期状态。 */
+    status: AgentTaskStatus;
+    /** 创建时间。 */
+    readonly createdAt: number;
+    /** 开始运行时间。 */
+    startedAt?: number;
+    /** 终结时间。 */
+    finishedAt?: number;
+    /** 派生的直接子代理 ID 集合。 */
+    readonly childAgentIds: Set<string>;
+    /** 任务结果摘要。 */
+    summary?: string;
+    /** 失败或取消原因。 */
+    error?: string;
+    /** 实际使用的模型标识。 */
+    modelId?: string;
+    /** 工作区物理根路径。 */
+    readonly workspaceRoot: string;
+    /** 执行物理目录。 */
+    readonly executionCwd: string;
+    /** 剩余/分配的限额。 */
+    readonly limits: Readonly<Required<AgentTaskLimits>>;
+    /** 显式限制的工具名称白名单。 */
+    allowedTools?: readonly string[];
+    /** 物理隔离模式。 */
+    isolation?: 'inherit' | 'worktree';
+    /** 模型覆盖参数。 */
+    modelOverride?: string;
+    /** 派生并锁定的不可扩大策略快照。 */
+    effectivePolicy?: unknown;
+    /** 活动槽位是否已被安全释放（防止 cancelTask 与 runTask.finally 重复释放导致容量失真）。 */
+    slotReleased?: boolean;
+}
+/** 查询子代理过滤选项。 */
+interface ListAgentsFilter {
+    /** 限定根任务标识。 */
+    rootTaskId?: string;
+    /** 限定父代理 ID。 */
+    parentAgentId?: string;
+    /** 限定父会话 ID。 */
+    parentSessionId?: string;
+    /** 限定状态。 */
+    status?: AgentTaskStatus | 'active' | 'terminal';
+}
+
+/**
+ * @fileoverview 可靠通知投递发件箱（SubagentOutbox）与收件箱（SessionInbox）。
+ *
+ * 约束、边界与为什么：
+ * 1. 至少一次投递与幂等去重（At-least-once & Idempotent Delivery）：
+ *    通知持有基于 agentId + generation + terminalRevision 生成的全局确定性 eventId。
+ *    父收件箱严格根据 eventId 去重，即使崩溃重投也绝不重复向父会话注入重复消息。
+ * 2. 消息身份与权限降级：
+ *    消费时通知作为带 subagent 来源的普通背景消息（协议投影为 user）持久化入父历史，
+ *    绝对不能以 system 权限注入，且模型伪造文本不获得特权。
+ * 3. 绝不追加第二个启动工具结果：
+ *    spawn_agent 的 tool_result 在受理时已即刻闭合；通知作为独立的背景消息追加，
+ *    严禁伪造或追加第二个 tool_result 污染 canonical 工具事务。
+ */
+
+/**
+ * 收件箱与协调器所依赖的持久化消息下沉抽象契约。
+ */
+interface SessionMessageSink {
+    /** 获取当前活动分支标识。 */
+    getActiveBranchId(): string;
+    /** 追加一条持久化消息至指定分支。 */
+    append(message: CanonicalMessage, options?: {
+        branchId?: string;
+    }): Promise<unknown>;
+    /** 读取现有持久化记录列表（用于启动幂等对账）。 */
+    readRecords?(): Promise<ReadonlyArray<{
+        type: string;
+        payload: Record<string, unknown>;
+    }>>;
+}
+/**
+ * 子代理终态通知数据结构。
+ */
+interface AgentNotification {
+    /** 投递事件全局唯一幂等标识。 */
+    readonly eventId: string;
+    /** 任务标识。 */
+    readonly agentId: string;
+    /** 根任务标识。 */
+    readonly rootTaskId: string;
+    /** 目标父会话 ID。 */
+    readonly parentSessionId: string;
+    /** 派生来源分支 ID。 */
+    readonly originBranchId: string;
+    /** 派生来源运行轮次 ID。 */
+    readonly originRunId: string;
+    /** 触发派生的工具调用 ID。 */
+    readonly spawnToolCallId: string;
+    /** 派生代次。 */
+    readonly generation: number;
+    /** 角色预设。 */
+    readonly role: SubagentRole;
+    /** 任务描述。 */
+    readonly description: string;
+    /** 终态状态。 */
+    readonly status: AgentTaskStatus;
+    /** 终态结果摘要。 */
+    readonly summary?: string;
+    /** 错误信息。 */
+    readonly error?: string;
+    /** 产物列表。 */
+    readonly artifacts?: string[];
+    /** 产生时间戳。 */
+    readonly timestamp: number;
+}
+/**
+ * 格式化子代理通知内容为协议背景消息文本。
+ */
+declare function formatNotificationContent(notification: AgentNotification): string;
+/**
+ * 子代理发件箱配置选项。
+ */
+interface SubagentOutboxOptions {
+    /** 可选持久化 JSONL 日志路径；配置后自动落盘并在重启时恢复未确认通知。 */
+    storagePath?: string;
+}
+/**
+ * 子代理端可靠发件箱（SubagentOutbox）。
+ */
+declare class SubagentOutbox {
+    private readonly notifications;
+    private readonly acknowledgedEventIds;
+    private readonly storagePath?;
+    constructor(options?: SubagentOutboxOptions);
+    /**
+     * 从已完成的子代理记录生成并登记终态通知。
+     */
+    enqueueFromTask(task: AgentTaskRecord, terminalRevision?: string): AgentNotification;
+    /**
+     * 获取所有未被确认的待投递通知。
+     */
+    getPendingNotifications(): AgentNotification[];
+    /**
+     * 确认指定通知投递已在父会话中落盘（ACK）。
+     */
+    acknowledge(eventId: string): void;
+    /**
+     * 查询指定通知是否已被确认。
+     */
+    isAcknowledged(eventId: string): boolean;
+}
+/**
+ * 父会话收件箱（SessionInbox），负责去重与作为背景消息持久化入父历史。
+ */
+declare class SessionInbox {
+    private static readonly globalInFlightConsumes;
+    private readonly store;
+    private readonly consumedEventIds;
+    constructor(store: SessionMessageSink);
+    /**
+     * 消费并持久化一条子代理通知。
+     *
+     * 保证：
+     * - 幂等去重：已消费过的 eventId 直接返回成功，绝不重复追加消息；
+     * - 并发合并：相同 eventId 的并发消费请求复用在途 Promise，消除竞态窗口；
+     * - 检查父历史现有消息，避免跨进程/重启后重复消费；
+     * - 构造协议兼容的背景消息（role: 'user'，带 subagentSource 标记），通过 store.append 保存；
+     * - 严格保持在来源分支上落盘；
+     * - 绝不追加第二个启动结果。
+     *
+     * @param notification 待投递的通知对象
+     * @returns 是否为新写入的消息（false 表示幂等跳过）
+     */
+    consume(notification: AgentNotification): Promise<boolean>;
+    /**
+     * 判断指定 eventId 是否已在收件箱中被消费。
+     */
+    hasConsumed(eventId: string): boolean;
+}
+
+/**
+ * @fileoverview 后台子代理任务树运行时调度器（AgentRuntime）。
+ *
+ * 约束、边界与为什么：
+ * 1. 状态机严格管理与等待收口：
+ *    preparing → accepted → running → waiting_children → completed / failed / cancelled / interrupted。
+ *    子代理主轮次执行结束若有活跃后代，必须进入 waiting_children 占槽等待收口，不得提前发最终完成通知。
+ * 2. 启动事务即刻闭合（Launch Transaction Invariant）：
+ *    spawn_agent 在准备阶段完成参数/权限/容量校验并登记意图后，立即向父返回 accepted 回执，
+ *    父工具事务即刻闭合，父代理继续推进后续步骤；父事务提交确认后异步激活启动子会话。
+ * 3. 严格容量控制与死锁防护：
+ *    每树活动槽 4，运行时活动槽 8，每树累计受理 16，超额立即抛出 AGENT_CAPACITY_EXCEEDED，
+ *    严禁持槽等待或隐式启动队列，防止祖先等待子级、子级等待槽位产生死锁。
+ * 4. 级联取消与后代收口：
+ *    任务失败或取消时无条件级联取消所有后代任务，并等待后代清理完成后才释放自身槽位与写入终态。
+ */
+
+/** 子代理会话执行器类型；生产环境调用真实的 AgentSession，测试环境可注入 Mock。 */
+type SubagentSessionRunner = (record: AgentTaskRecord, signal: AbortSignal) => Promise<{
+    summary: string;
+    modelId?: string;
+}>;
+/** 启动子代理时的调用方上下文。 */
+interface SpawnContext {
+    /** 根任务标识；若为根会话直接派生，可缺省由 Runtime 自动初始化。 */
+    rootTaskId?: string;
+    /** 父会话会话 ID。 */
+    sessionId: string;
+    /** 派生来源分支 ID。 */
+    branchId: string;
+    /** 派生来源运行轮次 ID。 */
+    runId: string;
+    /** 触发派生的工具调用 ID。 */
+    toolCallId: string;
+    /** 当前父任务深度；根会话为 0。 */
+    depth: number;
+    /** 父代理 ID；根会话时为 undefined。 */
+    agentId?: string;
+    /** 当前派生代次。 */
+    generation?: number;
+    /** 父工作区根。 */
+    workspaceRoot: string;
+    /** 父执行目录。 */
+    executionCwd: string;
+    /** 父权限策略快照。 */
+    parentPolicy?: ParentPolicySnapshot;
+}
+/**
+ * AgentRuntime 初始化选项。
+ */
+interface AgentRuntimeOptions {
+    runner?: SubagentSessionRunner;
+    validateModelOverride?: (modelId: string) => boolean;
+    outboxPath?: string;
+}
+/**
+ * 后台子代理任务树调度与状态机协调器。
+ */
+declare class AgentRuntime {
+    private readonly tasks;
+    private readonly controllers;
+    private readonly timers;
+    private readonly stateListeners;
+    /** 宿主观察订阅独立于调度等待；关闭宿主订阅不能影响任务收口。 */
+    private readonly taskChangeListeners;
+    private taskChangeNotificationPending;
+    private readonly outbox;
+    private readonly runningPromises;
+    private runner;
+    private readonly validateModelOverride?;
+    private isClosed;
+    private totalActiveCount;
+    private readonly treeActiveCounts;
+    private readonly treeTotalCounts;
+    constructor(options?: AgentRuntimeOptions);
+    /**
+     * 获取发件箱实例，供通知查询与 ACK 对账。
+     */
+    getOutbox(): SubagentOutbox;
+    /**
+     * 注入或替换子代理执行器。
+     */
+    setRunner(runner: SubagentSessionRunner): void;
+    /**
+     * 获取指定子代理记录快照。
+     */
+    getTask(agentId: string): AgentTaskRecord | undefined;
+    /**
+     * 订阅任务创建与状态变化；通知只表示快照可能已更新，不提供可变任务对象。
+     * 同一轮微任务内的变化可合并，不保证逐个中间状态；订阅时不主动发送通知，
+     * 宿主应先订阅，再通过 listTasks 按会话和根任务读取独立复制的快照。
+     * 监听器的同步异常与异步拒绝均隔离，不等待监听器，也不触发结果投递或父模型请求。
+     *
+     * @param listener 无参数变化监听器；应只读取展示状态，异步监听器可自行重叠执行。
+     * @returns 幂等取消函数；同一监听器的多次订阅独立取消，运行时关闭时全部释放。
+     * 已关闭的运行时不保留新订阅，返回的取消函数可安全调用。
+     */
+    subscribeTaskChanges(listener: () => void | Promise<void>): () => void;
+    /**
+     * 判断目标任务是否为指定祖先任务的后代（直接或间接子任务）。
+     */
+    isDescendantOf(targetId: string, ancestorId: string): boolean;
+    /**
+     * 准备并受理子代理启动请求（spawn_agent 执行第一阶段）。
+     *
+     * 保证：
+     * - 严格校验参数必填项与预设角色；
+     * - 深度超限立即拒绝（SUBAGENT_DEPTH_EXCEEDED）；
+     * - 容量超限立即拒绝（AGENT_CAPACITY_EXCEEDED）；
+     * - 工作区路径越界立即拒绝（SUBAGENT_WORKSPACE_VIOLATION）；
+     * - 生成 agentId 并原子预留活动槽与累计槽；
+     * - 登记为 preparing 状态并返回 accepted 回执，使父工具事务能立刻闭合。
+     */
+    prepareSpawn(context: SpawnContext, params: SpawnAgentParams): Promise<SpawnAgentReceipt>;
+    /**
+     * 激活并启动已受理的子代理任务（父事务提交确认后触发）。
+     *
+     * 状态跃迁：preparing → accepted → running。
+     */
+    activateSpawn(agentId: string): Promise<void>;
+    /**
+     * 撤销处于 preparing 状态的子代理任务（父事务提交失败或异常中止时触发）。
+     */
+    rollbackPreparedSpawn(agentId: string): Promise<void>;
+    /**
+     * 任务主执行流程与生命周期状态机驱动。
+     */
+    private runTask;
+    /**
+     * 等待指定任务的所有直接与间接后代达到终态。
+     */
+    private waitForChildren;
+    /**
+     * 级联取消指定任务的所有直接与间接活跃后代。
+     */
+    private cascadeCancelChildren;
+    /**
+     * 处理任务超时事件。
+     */
+    private handleTaskTimeout;
+    /**
+     * 显式取消指定子代理任务。
+     *
+     * 保证：
+     * - 幂等性：已处于终态直接返回；
+     * - 跃迁为 cancelling 并中断当前执行信号；
+     * - 级联取消所有后代子代理并等待后代清理完成；
+     * - 等待自身 runner 退出并完成清理（R07）；
+     * - 释放活动槽位，写入 cancelled 终态，生成可靠通知（R08）。
+     */
+    cancelTask(agentId: string, reason?: string): Promise<void>;
+    /**
+     * 等待指定的子代理任务终结或超时。
+     *
+     * @param agentIds 目标子代理 ID 列表
+     * @param timeoutMs 超时毫秒数（默认 30,000，上限 60,000）
+     * @param signal 中止信号
+     */
+    waitAgents(agentIds: string[], timeoutMs?: number, signal?: AbortSignal): Promise<{
+        completed: string[];
+        pending: string[];
+    }>;
+    /**
+     * 按过滤条件查询子代理任务列表；每条记录深度复制，调用方修改快照不影响运行时。
+     */
+    listTasks(filter?: ListAgentsFilter): AgentTaskRecord[];
+    /**
+     * 关闭 Runtime 并取消所有活动任务；立即释放宿主订阅，再等待任务清理收口。
+     */
+    close(): Promise<void>;
+    /**
+     * 幂等释放指定任务占用的活动容量槽位。
+     * 防止取消操作与主轮次 finally 重复扣减导致槽位泄漏。
+     */
+    private releaseTaskSlotOnce;
+    private releaseActiveSlot;
+    private clearTaskTimer;
+    /** 先保留调度等待者的同步唤醒时序，再异步通知宿主读取任务快照。 */
+    private notifyStateChange;
+    /**
+     * 合并宿主变化通知，避免宿主回调同步重入任务状态转换；不改变内部等待者的唤醒时序。
+     * 派发前再次检查订阅与关闭状态，取消后的回调不会执行，观察者失败不传播至任务。
+     */
+    private notifyTaskChanges;
+    private waitForNextStateChange;
+}
+
+/**
+ * @fileoverview 子代理四大调度与管理工具实现（spawn_agent、list_agents、wait_agent、cancel_agent）。
+ *
+ * 约束、边界与为什么：
+ * 1. 启动事务闭合不变量（Launch Transaction Closure）：
+ *    spawn_agent 在准备阶段完成校验并预留容量后，立即返回 accepted 回执，
+ *    父工具事务即刻闭合，父代理继续推进后续步骤；父事务确认后异步激活启动子代理，
+ *    严禁在 spawn_agent 的 execute 中 await 子任务完成。
+ * 2. 权限与能力声明：
+ *    四大管理工具均显式声明 agent:spawn capability，经正常 PermissionPolicy 策略检查，
+ *    Plan 模式自动隐藏与拦截。
+ * 3. 超时自管理（managesTimeout: true）：
+ *    spawn_agent、wait_agent、cancel_agent 自行管理超时与资源清理，不受通用工具超时误杀。
+ */
+
+/**
+ * 创建 spawn_agent 工具。
+ *
+ * @param runtime AgentRuntime 调度器实例
+ */
+declare function createSpawnAgentTool(runtime: AgentRuntime): Tool<SpawnAgentParams, SpawnAgentReceipt>;
+/**
+ * 创建 list_agents 工具。
+ */
+declare function createListAgentsTool(runtime: AgentRuntime): Tool<ListAgentsFilter, unknown>;
+/**
+ * 创建 wait_agent 工具。
+ */
+declare function createWaitAgentTool(runtime: AgentRuntime): Tool<{
+    agentIds: string[];
+    timeoutMs?: number;
+}, unknown>;
+/**
+ * 创建 cancel_agent 工具。
+ */
+declare function createCancelAgentTool(runtime: AgentRuntime): Tool<{
+    agentId: string;
+    reason?: string;
+}, unknown>;
+/**
+ * 创建完整的子代理四大管理工具集合。
+ */
+declare function createAgentTools(runtime: AgentRuntime): Tool[];
+
 /**
  * 任务准备上下文；提供当前会话取消信号、runId 与不可变工具快照。
  */
@@ -2489,7 +3822,11 @@ interface SessionConfig {
     defaultProvider: ModelProvider;
     /** 消息级落盘通道；支持状态能力的 Store 额外启用持久压缩与交互终态。 */
     store?: MessageStore;
-    /** 工具执行与会话基目录；projectRoot/cwd 缺省沿用此值。 */
+    /** 文件访问与沙箱隔离的物理根绝对路径，经 native realpath 规范化；缺失时抛出 WORKSPACE_ROOT_REQUIRED。 */
+    workspaceRoot?: string;
+    /** 默认命令执行目录绝对路径，必须位于 workspaceRoot 内部；缺省为 workspaceRoot。 */
+    executionCwd?: string;
+    /** 工具执行与会话基目录兼容别名；与 workspaceRoot 冲突时失败。 */
     rootDir?: string;
     systemPrompt?: string;
     maxSteps?: number;
@@ -2500,13 +3837,25 @@ interface SessionConfig {
     mode?: SessionMode;
     permissionRules?: readonly PermissionRule[];
     approvalChannel?: ApprovalChannel;
+    /** 项目根路径；缺省为 workspaceRoot。 */
     projectRoot?: string;
+    /** 兼容别名：执行目录。 */
     cwd?: string;
     userInstructionsPath?: string;
     /** 未提供时使用默认日志 sink 的审计目录；init 时恢复不完整审计。 */
     auditRecoveryDirectory?: string;
     /** 接收普通运行日志失败的脱敏诊断；诊断失败也不得中断问答或替代审计。 */
     onDiagnostic?: (message: string) => void;
+    /** 会话持有的沙箱实例；缺省基于 workspaceRoot 自动创建独占实例。 */
+    sandbox?: PathSandbox;
+    /** 共享工作区写租约协调器；缺省使用全局共享单例。 */
+    leaseCoordinator?: WorkspaceLeaseCoordinator;
+    /** 父任务或任务树根 ID，用于多智能体任务层级限制与追踪。 */
+    rootTaskId?: string;
+    /** 当前子会话在代理树中的深度，根会话为 0。 */
+    depth?: number;
+    /** 当前子会话对应的 agentId。 */
+    agentId?: string;
 }
 /** getStats 返回的统计快照；全部字段为独立副本，宿主修改不影响会话内部状态。 */
 interface SessionStats {
@@ -2547,9 +3896,19 @@ declare class AgentSession {
     private summaryUsage;
     private readonly summaryAttempts;
     private readonly accountedAttempts;
+    /** 文件访问与沙箱隔离的物理根绝对路径，经 native realpath 规范化。 */
+    readonly workspaceRoot: string;
+    /** 默认命令执行目录绝对路径，必须位于 workspaceRoot 内部。 */
+    readonly executionCwd: string;
+    /** 规范化项目身份哈希。 */
+    readonly projectKey: string;
+    /** 工具执行与会话基目录兼容别名；语义等同于 workspaceRoot。 */
     readonly rootDir: string;
     readonly tools: ToolRegistry;
     readonly hooks: HookRegistry;
+    /** 会话持有的独占路径沙箱实例。 */
+    readonly sandbox: PathSandbox;
+    private readonly leaseCoordinator;
     private readonly router;
     private readonly store?;
     private readonly customSystemPrompt?;
@@ -2566,6 +3925,9 @@ declare class AgentSession {
     private readonly userInstructionsPath?;
     private instructionSnapshot?;
     private readonly auditRecoveryDirectory?;
+    private readonly rootTaskId?;
+    private readonly depth;
+    private readonly agentId?;
     private history;
     private totalTurns;
     private usageStats;
@@ -2593,6 +3955,14 @@ declare class AgentSession {
      * 保证返回当前状态的独立切片，外部修改不污染内部挂载表。
      */
     getPlugins(): readonly AgentPlugin[];
+    /**
+     * 获取当前会话绑定的路径沙箱实例。
+     *
+     * 保证：
+     * - 返回由当前会话独立持有的 PathSandbox 实例，其根目录严格绑定到当前会话的 workspaceRoot；
+     * - 外部通过此沙箱执行路径规范化与逃逸校验时，遵循 native realpath 解析语义。
+     */
+    getSandbox(): PathSandbox;
     /**
      * 空闲时原子替换角色的模型绑定；本方法不改变当前角色或工具权限。
      * @param profile 模型协议、请求目标和输出预算。
@@ -2721,4 +4091,4 @@ declare class AgentSession {
     private findClosedToolMessages;
 }
 
-export { AbortError, AgentLoop, type AgentLoopOptions, type AgentPlugin, AgentSession, AnthropicProvider, type AnthropicProviderOptions, type ApprovalChannel, type ApprovalChoice, type ApprovalRequest, type CanonicalMessage, type Capability, type ChatCapabilities, type CommandResult, type ConflictPolicy, type ContentBlock, type ContextBudget, ContextBudgetError, ContextManager, type ContextManagerOptions, ContextOverflowError, type ContextSnapshot, ContextStorageError, type ContextSummary, type ContextUsage, type ContextWindowValue, DEFAULT_CONTEXT_WINDOW_TOKENS, type EventLogger, type ExecutorOptions, FatalError, type FileDetails, FileLogSink, type FileLogSinkOptions, type FileObservation, type HistoryRepair, type HookContext, type HookHandlers, type HookPoint, HookRegistry, type InstructionLoadOptions, type InstructionSnapshot, type InstructionSource, type InteractionBoundary, type InteractionTerminal, JSONLMessageStore, KapibalaError, type LogChannel, type LogEvent, type LogField, type LogInput, type LogLevel, type LogSink, type ManagedSession, type MessageRole, type MessageStore, ModelError, type ModelErrorCategory, type ModelErrorInfo, type ModelErrorOptions, type ModelEvent, type ModelProfile, type ModelProtocol, type ModelProvider, type ModelProviderBinding, type ModelRequest, type ModelRole, type ModelRouter, type NormalizedHistory, OpenAICompatibleProvider, type OpenAIProviderOptions, OpenAIResponsesProvider, type OpenAIResponsesProviderOptions, PathSandbox, type PermissionAction, type PermissionDecision, PermissionPolicy, type PermissionRequest, type PermissionRule, type PluginCommandContribution, type PluginContext, type PluginContribution, PreDispatchError, type PreparedSkill, type PreparedTaskContext, type PreparedTaskResult, type PrimaryModelRole, type ProjectIdentity, PromptAssembler, type PromptAssemblerOptions, type PromptContentSource, type ProtocolItemMetadata, type ProtocolOrigin, type ProviderStateBlock, type RedactedThinkingBlock, type RequestPreparation, type ResolvedContextWindow, type RunCommandInput, type RunMetrics, SESSION_SCHEMA_VERSION, SKILL_LIMITS, SUMMARY_OUTPUT_BUFFER_MULTIPLIER, type SandboxConfig, SessionApprovalCache, SessionBusyError, type SessionConfig, type SessionEvent, type SessionHeader, SessionLock, SessionManager, type SessionManagerOptions, type SessionMetadata, type SessionMode, type SessionRecord, type SessionRecordType, type SessionState, type SessionStats, SessionStore, type ShellDetectOptions, type ShellEnvironment, type ShellKind, type ShellPreference, type ShellScope, SimpleModelRouter, type SkillActivation, type SkillCatalog, type SkillContentSource, type SkillContextState, type SkillDefinition, type SkillDiagnostic, type SkillDocument, type SkillMetadata, type SkillOptions, type SkillQuery, type SkillQueryPage, SkillRegistry, type SkillResourceInput, type SkillResourcePage, type SkillRoot, SkillRuntime, type SkillScanResult, type SkillScope, type StatefulMessageStore, type StepLogEntry, type StepLogStage, StructuredLogger, type SummaryCandidate, SummaryService, type SummaryServiceOptions, type TextBlock, type ThinkingBlock, type TokenEstimate, type TokenEstimator, type Tool, type ToolContext, type ToolDecision, type ToolDefinition, ToolError, type ToolExecutionIdentity, type ToolExecutionResult, ToolExecutor, type ToolHardDenial, type ToolInputValidation, type ToolMetadata, ToolNotFound, ToolRegistry, type ToolRegistrySnapshot, type ToolResultBlock, type ToolResultExecution, type ToolUseBlock, TransportError, type TurnMetrics, UnicodeTokenEstimator, type Usage, assembleCanonicalToolResults, builtinTools, classifyBashOutput, cleanupCommandResults, commandAuditSummary, compareSkillPaths, createContextBudget, createDefaultLogSinks, createLogId, createMessageId, createRunCommandTool, defineTool, describeModelError, detectShell, editFileTool, escapeSkillXml, estimateSkillTokens, executionFingerprint, extractFileDetails, findSkillContent, formatSkillCatalog, globTool, grepTool, identifyHistory, indexInteractions, inspectSkillContent, intersectSkillTools, isSkillName, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, isWithinSkillRoot, listSkillResources, loadInstructions, normalizeHistory, normalizeSkillTools, parseSkillDocument, projectSafeFields, readBoundedSkillText, readFileTool, readSkillResource, recoverIncompleteAudit, renderFileDetails, renderSkillReloads, requestFingerprint, resolveContextWindow, resolveSessionProject, sanitizeModelErrorMessage, sanitizeSessionTitle, scanSkillRoot, skillDigest, skillFailure, skillPathKey, stableJsonStringify, stableSerialize, supportsSessionState, toToolDefinition, truncateToolOutput, validateModelBinding, validatePermissionRules, validateSummary, visibleTools, writeFileTool };
+export { AbortError, AgentLoop, type AgentLoopOptions, type AgentNotification, type AgentPlugin, AgentRuntime, type AgentRuntimeOptions, AgentSession, type AgentTaskLimits, type AgentTaskOrigin, type AgentTaskRecord, type AgentTaskStatus, AnthropicProvider, type AnthropicProviderOptions, type ApprovalChannel, type ApprovalChoice, type ApprovalRequest, type BranchInfo, type CanonicalMessage, type Capability, type CatalogOptions, type ChatCapabilities, type ChildGrant, type ChildLimits, type CommandResult, type ConflictPolicy, type ContentBlock, type ContextBudget, ContextBudgetError, ContextManager, type ContextManagerOptions, ContextOverflowError, type ContextSnapshot, ContextStorageError, type ContextSummary, type ContextUsage, type ContextWindowValue, CrossProjectSessionCatalog, DEFAULT_CHILD_LIMITS, DEFAULT_CONTEXT_WINDOW_TOKENS, DEFAULT_MAX_STEPS, DEFAULT_MAX_SUBAGENT_DEPTH, DEFAULT_TIMEOUT_MS, type DerivedChildPolicy, type EventLogger, type ExecutorOptions, FatalError, type FileDetails, FileLogSink, type FileLogSinkOptions, type FileObservation, HARD_LIMIT_MAX_SUBAGENT_DEPTH, type HistoryRepair, type HookContext, type HookHandlers, type HookPoint, HookRegistry, type InstructionLoadOptions, type InstructionSnapshot, type InstructionSource, type InteractionBoundary, type InteractionTerminal, JSONLMessageStore, KapibalaError, type ListAgentsFilter, type LogChannel, type LogEvent, type LogField, type LogInput, type LogLevel, type LogSink, MAIN_BRANCH_ID, MAX_ACTIVE_TASKS_PER_RUNTIME, MAX_ACTIVE_TASKS_PER_TREE, MAX_TOTAL_TASKS_PER_TREE, type ManagedSession, type MessageRole, type MessageStore, ModelError, type ModelErrorCategory, type ModelErrorInfo, type ModelErrorOptions, type ModelEvent, type ModelProfile, type ModelProtocol, type ModelProvider, type ModelProviderBinding, type ModelRequest, type ModelRole, type ModelRouter, type NormalizedHistory, OpenAICompatibleProvider, type OpenAIProviderOptions, OpenAIResponsesProvider, type OpenAIResponsesProviderOptions, type ParentPolicySnapshot, PathSandbox, type PermissionAction, type PermissionDecision, PermissionPolicy, type PermissionRequest, type PermissionRule, type PluginCommandContribution, type PluginContext, type PluginContribution, PreDispatchError, type PreparedSkill, type PreparedTaskContext, type PreparedTaskResult, type PrimaryModelRole, type ProjectIdentity, PromptAssembler, type PromptAssemblerOptions, type PromptContentSource, type ProtocolItemMetadata, type ProtocolOrigin, type ProviderStateBlock, ROLE_PRESETS, type RedactedThinkingBlock, type RequestPreparation, type ResolvedContextWindow, type RolePresetDefinition, type RunCommandInput, type RunMetrics, SESSION_SCHEMA_VERSION, SESSION_SCHEMA_VERSION_V1, SESSION_SCHEMA_VERSION_V2, SKILL_LIMITS, SUMMARY_OUTPUT_BUFFER_MULTIPLIER, type SafeRegexMatchResult, type SandboxConfig, type SearchHit, type SearchOptions, type SearchResponse, SessionApprovalCache, SessionBusyError, type SessionCatalogEntry, type SessionConfig, type SessionEvent, type SessionHeader, SessionInbox, SessionLock, SessionManager, type SessionManagerOptions, type SessionMessageSink, type SessionMetadata, type SessionMode, type SessionRecord, type SessionRecordType, type SessionState, type SessionStats, SessionStore, type ShellDetectOptions, type ShellEnvironment, type ShellKind, type ShellPreference, type ShellScope, SimpleModelRouter, type SkillActivation, type SkillCatalog, type SkillContentSource, type SkillContextState, type SkillDefinition, type SkillDiagnostic, type SkillDocument, type SkillMetadata, type SkillOptions, type SkillQuery, type SkillQueryPage, SkillRegistry, type SkillResourceInput, type SkillResourcePage, type SkillRoot, SkillRuntime, type SkillScanResult, type SkillScope, type SpawnAgentParams, type SpawnAgentReceipt, type SpawnContext, type StatefulMessageStore, type StepLogEntry, type StepLogStage, StructuredLogger, SubagentOutbox, type SubagentOutboxOptions, type SubagentRole, type SubagentSessionRunner, type SubagentSourceMetadata, type SummaryCandidate, SummaryService, type SummaryServiceOptions, type TextBlock, type ThinkingBlock, type TokenEstimate, type TokenEstimator, type Tool, type ToolContext, type ToolDecision, type ToolDefinition, ToolError, type ToolExecutionIdentity, type ToolExecutionResult, ToolExecutor, type ToolHardDenial, type ToolInputValidation, type ToolMetadata, ToolNotFound, ToolRegistry, type ToolRegistrySnapshot, type ToolResultBlock, type ToolResultExecution, type ToolUseBlock, TransportError, type TurnMetrics, UnicodeTokenEstimator, type Usage, type WorkspaceContext, WorkspaceLeaseCoordinator, type WorkspaceResolutionInput, type WorkspaceWriteLease, assembleCanonicalToolResults, assertClosedToolTransaction, builtinTools, classifyBashOutput, cleanupCommandResults, commandAuditSummary, compareSkillPaths, computeProjectKey, createAgentTools, createCancelAgentTool, createContextBudget, createDefaultLogSinks, createListAgentsTool, createLogId, createMessageId, createRunCommandTool, createSpawnAgentTool, createWaitAgentTool, defineTool, deriveChildPolicy, describeModelError, detectShell, editFileTool, escapeSkillXml, estimateSkillTokens, executionFingerprint, extractFileDetails, findSkillContent, formatNotificationContent, formatSkillCatalog, getRolePreset, globTool, grepTool, identifyHistory, indexInteractions, inspectSkillContent, intersectSkillTools, isActiveTaskStatus, isGlobalControlRecordType, isPathInside, isSamePath, isSkillName, isTerminalTaskStatus, isTextBlock, isThinkingBlock, isToolResultBlock, isToolUseBlock, isWithinSkillRoot, isWriteOperation, listSkillResources, loadInstructions, normalizeDriveLetter, normalizeHistory, normalizeSkillTools, normalizedProjectRoot, parseSkillDocument, projectSafeFields, readBoundedSkillText, readFileTool, readSkillResource, recoverIncompleteAudit, renderFileDetails, renderSkillReloads, requestFingerprint, resolveContextWindow, resolveSessionProject, resolveWorkspaceContext, safeRegexMatch, sanitizeModelErrorMessage, sanitizeSessionTitle, scanSkillRoot, sharedWorkspaceLeaseCoordinator, skillDigest, skillFailure, skillPathKey, stableJsonStringify, stableSerialize, supportsSessionState, tightenMode, toNativePhysicalPath, toToolDefinition, truncateToolOutput, validateModelBinding, validatePermissionRules, validateSummary, visibleTools, writeFileTool };