@ai-setting/roy-agent-core 1.7.77 → 1.7.88

package/dist/env/session/group-session-link.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview 关联建群：群 session 的初始化（Task #5403）
+ *
+ * ## 为什么不再用 alias / linkedTo
+ *
+ * #5369 的实现让「群 session」成为原 sub-session 的 **alias** —— 消息读写全部
+ * 透传到原会话，两个 session 看到同一份 history。用户实测（#5396）后否决：
+ *
+ *  1. **LLM prefix cache 失效**：群 session 由 **default agent** 的 system
+ *     prompt 驱动，原 sub session 由 **sub agent** 驱动。system prompt 一变，
+ *     prefix 就不一样，history 全部得重新 prefill。
+ *  2. **语义污染**：sub agent 的 delegate prompt 里有「不要发飞书消息（回复由
+ *     主 agent 负责）」这类硬约束。这些约束在新群的历史里被当成**当前生效
+ *     指令**，于是群里的 agent 真的不回复（#5396 实测 0 出站）。
+ *
+ * ## 新方案（用户定稿）
+ *
+ * 建群成功 ⇒ 群 session 是**完全独立的 session**，只注入 **1 条 user role
+ * 消息**（不是 system，不是 assistant —— 与 notify event / 飞书 event 的注入
+ * 方式一致），说明：
+ *
+ *  - 本群由哪个 session 关联建群而来（溯源）
+ *  - 需要背景时怎么读（`roy-agent sessions messages <id> -n 50`，按需拉取）
+ *  - 明确「历史不在本群上下文中」——避免模型凭空脑补
+ *
+ * 关联关系本身写进群 session 的 metadata（`linkedFromSessionId` /
+ * `groupCreatedAt`），用于重复建群保护 / 卡片显示群链接 / 解绑。
+ *
+ * 本文件只放**纯函数**（无 IO），便于单测与复用。
+ */
+/** 注入事件的内容里，建议模型按需读取的历史条数 */
+export declare const GROUP_LINK_READ_HINT_LIMIT = 50;
+/**
+ * 群 session metadata 里的溯源字段。
+ *
+ * 这些字段取代了已废弃的 `Session.linkedTo`：
+ *  - `linkedFromSessionId` —— 本群由哪个 session 关联建群而来
+ *  - `groupCreatedAt`      —— 关联建群时间（ISO 8601）
+ *  - `groupDisbandedAt`    —— 解绑时间（ISO 8601）；存在即视为「已解散」
+ */
+export declare const GROUP_LINK_METADATA_KEYS: {
+    readonly linkedFromSessionId: "linkedFromSessionId";
+    readonly groupCreatedAt: "groupCreatedAt";
+    readonly groupDisbandedAt: "groupDisbandedAt";
+};
+/**
+ * 构造「关联建群」注入事件的消息体。
+ *
+ * 设计约束（用户明令）：
+ *  - **role = user**：与 notify event / 飞书 event 的注入方式保持一致，
+ *    不用 system（system prompt 有自己的组装链路，混进去会破坏 cache）。
+ *  - **不复制历史**：只有这一条，模型要看细节自己去读。
+ *  - **明确可执行路径**：给出 `sessions messages` 命令，让模型知道怎么取。
+ *  - **明确边界**：告诉模型「历史上那些任务型约束（如不要发飞书消息）
+ *    只对当时那轮生效」，避免 #5396 的污染复发。
+ *
+ * @param originSessionId 原 session id（群是由它关联建出来的）
+ * @param chatId 飞书群 chat id（群 session 的 id）
+ * @param createdAt 建群时间（默认 now）
+ */
+export declare function buildGroupLinkEventMessage(args: {
+    originSessionId: string;
+    chatId?: string;
+    createdAt?: Date | string;
+}): {
+    role: "user";
+    content: string;
+};
+/**
+ * 构造群 session 的 metadata（合并到已有 metadata 上）。
+ *
+ * 保留已有的 `chatId` / `type` 等识别键 —— 事件层 `ensureChatSession` 靠
+ * `metadata.chatId + type:'lark-chat'` 找群 session，不能被覆盖掉。
+ */
+export declare function buildGroupSessionMetadata(args: {
+    chatId: string;
+    originSessionId: string;
+    createdAt?: Date | string;
+    base?: Record<string, unknown>;
+}): Record<string, unknown>;
+/**
+ * 判断一个 session 的 metadata 是否标记为「群已解散」。
+ *
+ * 解绑后群在飞书侧已删，反查不该再把它当成「这个会话的群」（否则卡片永远
+ * 显示「解散该群」、下次建群幂等命中死群）。
+ */
+export declare function isGroupDisbanded(metadata: Record<string, unknown> | undefined): boolean;
+/**
+ * 判断一个 session 是否是「某个 session 的关联群 session」。
+ *
+ * 三个标记必须同时齐备（沿用 #5397 CV R2 的三条 marker 思路）：
+ *  1. `metadata.type === 'lark-chat'`
+ *  2. `metadata.chatId` 非空
+ *  3. `metadata.linkedFromSessionId` 非空
+ *
+ * 缺一条就不认 —— 避免把普通的飞书 chat session / 别的写入方造的脏数据
+ * 误判成群 session。
+ */
+export declare function isGroupSessionOf(metadata: Record<string, unknown> | undefined, originSessionId: string): boolean;

package/dist/env/session/index.js

@@ -3,24 +3,25 @@ import {
   MIN_SESSION_ID_LENGTH,
   SessionComponent,
   isValidSessionId
-} from "../../shared/@ai-setting/roy-agent-core-ddyk1rc0.js";
+} from "../../shared/@ai-setting/roy-agent-core-cre2y2ct.js";
 import {
   MemorySessionStore
-} from "../../shared/@ai-setting/roy-agent-core-0qyrk5k0.js";
+} from "../../shared/@ai-setting/roy-agent-core-ds6qzmf8.js";
 import"../../shared/@ai-setting/roy-agent-core-rvxg1wps.js";
 import {
   SessionMessageConverter
-} from "../../shared/@ai-setting/roy-agent-core-0snm5hc5.js";
-import"../../shared/@ai-setting/roy-agent-core-fghc2m8z.js";
+} from "../../shared/@ai-setting/roy-agent-core-y6shd91r.js";
+import"../../shared/@ai-setting/roy-agent-core-aa8kv18f.js";
+import"../../shared/@ai-setting/roy-agent-core-wxrkcb17.js";
 import"../../shared/@ai-setting/roy-agent-core-zjdzk1gg.js";
 import"../../shared/@ai-setting/roy-agent-core-ntn32q7j.js";
 import"../../shared/@ai-setting/roy-agent-core-7hh0brvs.js";
-import"../../shared/@ai-setting/roy-agent-core-pgvcf91v.js";
-import"../../shared/@ai-setting/roy-agent-core-ax9e9szb.js";
-import"../../shared/@ai-setting/roy-agent-core-cpcd24n2.js";
-import"../../shared/@ai-setting/roy-agent-core-qqaak24r.js";
-import"../../shared/@ai-setting/roy-agent-core-7cbpmk4q.js";
-import"../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";
+import"../../shared/@ai-setting/roy-agent-core-m39v7qpx.js";
+import"../../shared/@ai-setting/roy-agent-core-smf94h73.js";
+import"../../shared/@ai-setting/roy-agent-core-yet36q5k.js";
+import"../../shared/@ai-setting/roy-agent-core-tkpp1ba0.js";
+import"../../shared/@ai-setting/roy-agent-core-p31ftgq9.js";
+import"../../shared/@ai-setting/roy-agent-core-5s2t8z00.js";
 import"../../shared/@ai-setting/roy-agent-core-7f7t9wwp.js";
 import"../../shared/@ai-setting/roy-agent-core-85xyctnb.js";
 import"../../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";

package/dist/env/session/session-component.d.ts

@@ -183,6 +183,95 @@ export declare class SessionComponent extends BaseComponent {
      * Delete a session
      */
     delete(id: string): Promise<boolean>;
+    /**
+     * ★ Task #5403：**会话 → 群** 反向查询（取代 #5397 的 alias 版）。
+     *
+     * ## 背景
+     *
+     * alias / linkedTo 能力已整体废弃（用户 2026-11-12 定稿）。建群后的群
+     * session 是**独立 session**，不再共享原会话的消息历史 —— 原因：
+     *  1. 群 session 由 default agent 的 system prompt 驱动，原 sub session 由
+     *     sub agent 驱动，复用同一份 history 会让 LLM prefix cache 失效；
+     *  2. sub agent 的 delegate prompt（如「不要发飞书消息」）会污染群对话。
+     *
+     * 新方案：建群时向新 session 注入 **1 条 user role 事件**说明「本群由
+     * session X 关联建群，需要背景时用 `roy-agent sessions messages X` 按需读取」，
+     * 关联关系本身记在 metadata（`linkedFromSessionId` / `groupCreatedAt`）。
+     *
+     * ## 用途（三处，与 #5397 一致）
+     * 1. 重复建群保护（同 session 已有群 ⇒ 返回已有链接，不新建）
+     * 2. 卡片显示已有群链接（session 卡渲染 `perTaskChatId`）
+     * 3. 解绑时定位要解散哪个群
+     *
+     * ## 实现
+     *
+     * 扫 `metadata.linkedFromSessionId === sessionId` 的 session 行，取它的
+     * chatId（来自 `metadata.chatId`，群 session 的识别键）。
+     *
+     * 走 store 的 metadata filter（SQLite 侧是 JSON1 `json_extract`，不扫全表
+     * 之外的额外成本；无 schema 变更、无新索引）。
+     *
+     * **自称命中**：入参本身是群 session 时，它自己就带
+     * `linkedFromSessionId`，此时直接返回自身 —— 因为 `list` 用
+     * `linkedFromSessionId = sessionId` 过滤，那个群 session 的
+     * `linkedFromSessionId` 指向的是**原会话**而不是自己，所以需要额外一次
+     * `get(sessionId)` 自身检查（见下方逻辑）。
+     */
+    findGroupChatForSession(sessionId: string): Promise<{
+        chatId: string;
+        aliasSessionId?: string;
+    } | undefined>;
+    /**
+     * ★ Task #5403：**关联建群** —— 建群成功后初始化群 session。
+     *
+     * 取代 #5369/#5397 的 `linkSession(aliasId, target)`。区别是**不共享历史**：
+     *
+     *  - 群 session 是独立 session（自己持有消息，读写不透明）
+     *  - 只注入 **1 条 user role** 事件，说明「本群由 session X 关联建群
+     *    而来，需要背景时执行 `roy-agent sessions messages X -n 50` 按需读取」
+     *  - 关联关系写进 metadata（`linkedFromSessionId` / `groupCreatedAt`），
+     *    供重复建群保护 / 卡片链接 / 解绑使用
+     *
+     * ## 幂等
+     *
+     * 若该 chatId 的 session 已存在且已登记 `linkedFromSessionId`，**不重复
+     * 注入**（只补齐缺失的 metadata），返回 `injected: false`。这让「重复点
+     * 建群」不会在群里堆一串说明消息。
+     *
+     * ## 失败语义
+     *
+     * 返回 `{ ok: false, reason }`，不抛。调用方（建群流程）拿到后只 warn ——
+     * 群已经建好了，不能因为初始化失败把结果翻成失败。
+     *
+     * @param chatId 飞书群 chat id（同时是群 session 的 id）
+     * @param originSessionId 原 session id（群是由它关联建出来的）
+     */
+    attachGroupSession(args: {
+        chatId: string;
+        originSessionId: string;
+        title?: string;
+    }): Promise<{
+        ok: true;
+        sessionId: string;
+        injected: boolean;
+    } | {
+        ok: false;
+        reason: "store_unavailable" | "invalid_args";
+        error?: string;
+    }>;
+    /**
+     * ★ Task #5403：**解绑关联群** —— 标记 metadata 为已解散。
+     *
+     * 取代 #5369 的 `unlinkSession(aliasId)`（原语义是把 linkedTo 置 null）。
+     * 新语义：群 session 本身是独立会话，解绑只是把「这个群还活着」的标记
+     * 打掉 —— 写入 `groupDisbandedAt`，让 `findGroupChatForSession` 不再命中它。
+     *
+     * 幂等：已经标记过直接返回 ok。
+     */
+    detachGroupSession(chatId: string): Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
     /**
      * 飞书 chat_id → task_id 反向绑定缓存（LRU + TTL）
      *

package/dist/env/session/storage/index.js

@@ -3,12 +3,13 @@ import {
   SQLiteSessionStore,
   getDefaultDataDir,
   getDefaultSessionDbPath
-} from "../../../shared/@ai-setting/roy-agent-core-0qyrk5k0.js";
-import"../../../shared/@ai-setting/roy-agent-core-0snm5hc5.js";
-import"../../../shared/@ai-setting/roy-agent-core-fghc2m8z.js";
+} from "../../../shared/@ai-setting/roy-agent-core-ds6qzmf8.js";
+import"../../../shared/@ai-setting/roy-agent-core-y6shd91r.js";
+import"../../../shared/@ai-setting/roy-agent-core-aa8kv18f.js";
+import"../../../shared/@ai-setting/roy-agent-core-wxrkcb17.js";
 import"../../../shared/@ai-setting/roy-agent-core-zjdzk1gg.js";
 import"../../../shared/@ai-setting/roy-agent-core-ntn32q7j.js";
-import"../../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";
+import"../../../shared/@ai-setting/roy-agent-core-5s2t8z00.js";
 import"../../../shared/@ai-setting/roy-agent-core-7f7t9wwp.js";
 import"../../../shared/@ai-setting/roy-agent-core-85xyctnb.js";
 import"../../../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";

package/dist/env/session/types.d.ts

@@ -172,6 +172,16 @@ export interface SessionMetadata extends Record<string, unknown> {
     checkpoints?: SessionCheckpointsMeta;
     checkpointDetails?: Record<string, SessionCheckpoint>;
     larkChat?: ChatTaskBinding;
+    /**
+     * 建群时登记：这个群 session 是由哪个 session「关联建群」而来的。
+     *
+     * ⚠️ 语义仅作**溯源标注**，不代表消息透传 / 共享历史。群 session 自己的
+     * 消息就是群里的实际对话；原会话历史需按需通过
+     * `roy-agent sessions messages <linkedFromSessionId>` 读取。
+     */
+    linkedFromSessionId?: string;
+    /** 关联建群时间（ISO 8601） */
+    groupCreatedAt?: string;
 }
 /**
  * 飞书群聊 → task 绑定关系

package/dist/env/skill/index.js

@@ -6,19 +6,19 @@ import {
   getSourcePriority,
   parseFrontmatter,
   parseSkillFile
-} from "../../shared/@ai-setting/roy-agent-core-5pr4zp88.js";
+} from "../../shared/@ai-setting/roy-agent-core-5kzhaap1.js";
 import {
   SkillToolSchema,
   buildSkillDescription,
   createSkillTool
 } from "../../shared/@ai-setting/roy-agent-core-psvxt4c9.js";
 import"../../shared/@ai-setting/roy-agent-core-7hh0brvs.js";
-import"../../shared/@ai-setting/roy-agent-core-pgvcf91v.js";
-import"../../shared/@ai-setting/roy-agent-core-ax9e9szb.js";
-import"../../shared/@ai-setting/roy-agent-core-cpcd24n2.js";
-import"../../shared/@ai-setting/roy-agent-core-qqaak24r.js";
-import"../../shared/@ai-setting/roy-agent-core-7cbpmk4q.js";
-import"../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";
+import"../../shared/@ai-setting/roy-agent-core-m39v7qpx.js";
+import"../../shared/@ai-setting/roy-agent-core-smf94h73.js";
+import"../../shared/@ai-setting/roy-agent-core-yet36q5k.js";
+import"../../shared/@ai-setting/roy-agent-core-tkpp1ba0.js";
+import"../../shared/@ai-setting/roy-agent-core-p31ftgq9.js";
+import"../../shared/@ai-setting/roy-agent-core-5s2t8z00.js";
 import"../../shared/@ai-setting/roy-agent-core-7f7t9wwp.js";
 import"../../shared/@ai-setting/roy-agent-core-85xyctnb.js";
 import"../../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";

package/dist/env/task/delegate/delegate-channel-hint.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Task #5423 — delegate_task sub-agent prompt 渠道特性提示。
+ *
+ * ## 背景（用户 2026-11-13 07:14 批准的方案）
+ *
+ * delegate_task 起的 sub-agent 的 prompt 里没有渠道特性提示：
+ * 用户在飞书发「帮我写调研文档」→ 主 agent delegate 给 sub-agent
+ * → sub-agent 不知道触发渠道 → 产出物落本地路径（`/tmp/x.md`）
+ * 而非飞书云盘，飞书用户根本打不开。
+ *
+ * 主 agent 的 system prompt 里**有**渠道规范（lark/wecom 渠道 prompt），
+ * 但那套 systemPrompt 只注入主 agent；sub-agent 走
+ * `ensureSubAgentRegistered(basePrompt)`，只拿到自己的 basePrompt，
+ * 拿不到任何渠道上下文。
+ *
+ * ## 方案
+ *
+ * 渠道信息来源：delegate 时刻的 `EnvContext.replyChannel.type`
+ * （`lark-cli` / `wecom-cli`），已由 `captureReplyChannelSnapshot()`
+ * 快照到 `task.replyChannel`（Task #4042 follow-up），
+ * 并在 `executeWithAbort` 里可从 sub-session metadata / EnvContext 取到。
+ *
+ * - 触发渠道是飞书 → 文档类产出用**飞书云盘**（`lark-cli docs +create`）
+ * - 触发渠道是企微 → 对应方式（`wecom-cli doc create` / `disk files upload`）
+ * - 无渠道（CLI / REPL / 定时器 / 未知渠道）→ 返回 undefined，**不注入**
+ *
+ * 纯函数叶子模块：不 import delegate-tool / event-source，
+ * 避免回向依赖（对标 sub-session-activity.ts 的叶子模块纪律）。
+ */
+/** 渠道提示段的章节标题（同时作为「无渠道不注入」的探针串） */
+export declare const DELEGATE_CHANNEL_HINT_TITLE = "## \u6E20\u9053\u4EA4\u4ED8\u63D0\u793A\uFF08\u5F53\u524D\u4F1A\u8BDD\u6765\u81EA\u5916\u90E8\u6E20\u9053\uFF09";
+/**
+ * 从 replyChannel.type 派生渠道特性提示段。
+ *
+ * @param channelType delegate 时刻 EnvContext.replyChannel.type
+ *   （`"lark-cli"` / `"wecom-cli"` / 其他 / undefined）
+ * @returns 提示段文本；无渠道或未知渠道返回 undefined（不注入）
+ */
+export declare function buildDelegateChannelHint(channelType: string | undefined): string | undefined;

package/dist/env/task/delegate/delegate-tool.d.ts

@@ -35,13 +35,31 @@ export declare const BackgroundTaskEventTypes: {
      *   - EventMessageFormatter 渲染 payload（含 question + subSessionId + rule-based hints）
      *   - handleEventMessageWithEnv → executeInternal 把消息喂给主 agent LLM
      *   - 主 agent 用 ask_user tool 展示问题、等用户答复
-     *   - 拿到答复后用 delegate_task(subagentType=..., existingSubSessionId=payload.subSessionId, ...)
+     *   - 拿到答复后用 delegate_task(subagent_type=..., sub_session_id=payload.subSessionId, ...)
      *     复用 sub-session 让 sub-agent 继承消息历史继续推进（无需 resume function）。
      *
      * 关键：hints 由 BackgroundTaskManager 在构造事件时 rule-based 填充（事件自带），
      * CLI 端 formatter 只渲染，handler 端零特殊化。
      */
     readonly ASK_USER: "task.background.ask_user";
+    /**
+     * ★ 补充需求（22:31）：sub-agent 启动、**但尚未建 task**。
+     *
+     * ## 为什么需要独立一个事件（不能复用 STARTED）
+     *
+     * `STARTED` 在 `createTask()` 里就发，此刻 `associatedTaskId` 还是
+     * `undefined`（sub-agent 还没跑、当然还没建 task）—— 所以它**无法**告诉
+     * 卡片层「这是 task 卡还是 session 卡」。
+     *
+     * 而用户要的是：**只要跑起来了、且没建 task，就应该有卡片可点刷新**。
+     *
+     * ⇒ 在 sub-agent 完成「是否建了 task」的判定之后（即 `COMPLETED` 时
+     *   反查 `associatedTaskId` 之后），若仍无 task，才补发本事件。
+     *
+     * 语义：`STARTED` = 「有后台任务在跑」（task 视角）；本事件 =
+     * 「这次执行挂不到 task 上」（session 视角）。两者互补，不重复。
+     */
+    readonly SESSION_STARTED: "task.background.session_started";
 };
 export interface BackgroundTaskStartedPayload {
     backgroundTaskId: string;
@@ -97,8 +115,8 @@ export interface BackgroundTaskCompletedPayload {
  *   - EventMessageFormatter 渲染 payload（question + subSessionId + hints）成消息
  *   - handleEventMessageWithEnv → executeInternal 把消息喂给主 agent LLM
  *   - 主 agent 用 ask_user tool 把 question 展示给用户
- *   - 拿到用户答复后用 delegate_task(subagentType=payload.subagentType,
- *     existingSubSessionId=payload.subSessionId, prompt=<用户答复>)
+ *   - 拿到用户答复后用 delegate_task(subagent_type=payload.subagentType,
+ *     sub_session_id=payload.subSessionId, prompt=<用户答复>)
  *     复用 sub-session 让 sub-agent 继承之前消息历史继续推进（无需 resume function）。
  *
  * hints 是 rule-based 提示数组，BackgroundTaskManager 在构造事件时填充。
@@ -162,6 +180,33 @@ export interface SubAgentSpec {
 }
 export declare const builtInSubAgents: SubAgentSpec[];
 export declare function getSubAgentSpec(id: string): SubAgentSpec | undefined;
+/**
+ * 确保 subAgent 已注册到 AgentComponent
+ *
+ * 对于 workflow type 的 agent，跳过注册（workflow agent 不需要 system prompt 和 runtime agent）。
+ *
+ * @param agentComponent AgentComponent 实例
+ * @param subagentType subAgent 类型（用作 agentName）
+ * @param basePrompt 基础 system prompt
+ * @param subAgent subAgent 配置（可能包含 allowedTools）
+ * @param deniedTools 拒绝的工具列表
+ * @returns 注册的 agent 实例，workflow agent 返回 null
+ */
+/**
+ * ★ Task #5333（DS review 第 2 轮 MINOR-4）— 把松散来源的 extendTools 归一。
+ *
+ * `ToolContext.metadata` 是 `Record<string, unknown>`，从里面取出的值理论上
+ * 可能是任意类型。`filterToolsByAgent` 用 `extendTools.includes(name)` 判断，
+ * 若传进来一个对象或含非字符串的数组，既不报错也永不命中 —— 表现为
+ * 「名单写了却不生效」的诡异静默失败。这里做一次运行时收敛：
+ *
+ * - 非数组 → undefined（视为未放行）
+ * - 数组 → 只保留非空字符串（trim 后），全被过滤掉则返回 undefined
+ *
+ * @param raw 来自 ToolContext.metadata 的原始值
+ * @returns 干净的字符串数组或 undefined
+ */
+export declare function normalizeExtendTools(raw: unknown): string[] | undefined;
 export declare const DelegateToolParameters: z.ZodObject<{
     description: z.ZodString;
     prompt: z.ZodString;
@@ -236,6 +281,24 @@ export interface BackgroundTask {
      * 顺序 = 优先级（主模型失败后逐个尝试）。
      */
     fallbackModels?: string[];
+    /**
+     * ★ Task #5217 fix 2 — 父 agent 本次 run 的 channel systemPrompt
+     * （context.metadata.systemPrompt，如 lean lark 渠道 prompt）。
+     * 透传给 sub-agent 的 AgentContext.metadata.systemPrompt，
+     * 使 AgentComponent._run 把它追加到 sub-agent 的 LLM system message。
+     *
+     * 注意：与 model 一样**不写进 sub-agent 的注册配置** —— per-run
+     * 透传天然每次都是最新值（channel prompt 是 per-event 的）。
+     */
+    systemPrompt?: string;
+    /**
+     * ★ Task #5333 — 父 run 的渠道专用工具放行名单（AgentContext.extendTools）。
+     *
+     * 企微事件驱动的父 agent 有 `["wecom_respond"]`；委派出去的 sub-agent
+     * 若拿不到这份名单，`wecom_respond`（channelOnly 工具）在 sub-agent 侧
+     * 不可见 → 子任务无法给企微用户回复。因此随 task 一起透传。
+     */
+    extendTools?: string[];
     /**
      * ★ Task #4552 (A1)：本任务被允许的运行时长（毫秒，createTask 时确定）。
      *
@@ -280,6 +343,16 @@ export interface BackgroundTask {
         profile?: string;
         params?: Record<string, unknown>;
     };
+    /**
+     * ★ Task #5265 — delegate 时刻的 pluginEnabled 快照。
+     *
+     * 后台任务通知轮（task.background.* 合成 envEvent）此前
+     * pluginEnabled={}（空）→ WecomTaskNotifyPlugin 等 ES 插件的
+     * pluginEnabled 守卫拦截 → 不发卡（用户只见纯文本）。
+     * createTask 时快照 parent EnvContext.pluginEnabled，
+     * publishBackgroundEvent 时写进 event.metadata.pluginEnabled。
+     */
+    pluginEnabledSnapshot?: Record<string, boolean>;
 }
 /**
  * Task #4794 — BackgroundTaskManager.dispose() 的行为选项。
@@ -347,6 +420,18 @@ export interface CreateBackgroundTaskOptions {
      * Task #4724 — 父 agent 的兜底模型**有序列表**，透传给 sub-agent。
      */
     fallbackModels?: string[];
+    /**
+     * ★ Task #5217 fix 2 — 父 agent 本次 run 的 channel systemPrompt
+     * （context.metadata.systemPrompt，如 lean lark 渠道 prompt）。
+     * 透传给 sub-agent 的 AgentContext.metadata.systemPrompt。
+     */
+    systemPrompt?: string;
+    /**
+     * ★ Task #5333 — 父 run 的渠道专用工具放行名单（AgentContext.extendTools）。
+     * 透传给 sub-agent 的 AgentContext.extendTools，使子 agent 也能看到
+     * 本渠道的 channelOnly 工具（如 wecom_respond）。
+     */
+    extendTools?: string[];
 }
 /**
  * 构建 entry-agent 调度的 prompt 包装 (Task #2164 beta-compare divergence #2)
@@ -578,7 +663,7 @@ export declare class BackgroundTaskManager {
      *
      * @internal 测试 / 集成用，普通调用方走 publishBackgroundEvent 私有方法
      */
-    publishBackgroundEventWithTrigger<T>(type: string, payload: T, parentSessionId: string | undefined, triggerEventId: string, replyChannel?: BackgroundTask["replyChannel"]): void;
+    publishBackgroundEventWithTrigger<T>(type: string, payload: T, parentSessionId: string | undefined, triggerEventId: string, replyChannel?: BackgroundTask["replyChannel"], pluginEnabledSnapshot?: Record<string, boolean>): void;
     /**
      * Task #3xxx — 解析 AskUserError 信息
      *
@@ -611,10 +696,10 @@ export declare class BackgroundTaskManager {
      *      保留 sub-session 并发布 `task.background.ask_user` 事件。
      *   2. CLI 收到事件后直接显示问题给用户（不送 LLM）。
      *   3. 用户答复后，主 agent（或用户命令）通过 `delegate_task` 工具调用
-     *      `subagentType=original.subagentType, existingSubSessionId=original.subSessionId`
+     *      `subagent_type=original.subagentType, sub_session_id=original.subSessionId`
      *      即可复用 sub-session（保留 message history）继续推进 sub-agent。
      *
-     * 因此本方法不再提供；续传是 delegate_task + existingSubSessionId 内建能力。
+     * 因此本方法不再提供；续传是 delegate_task + sub_session_id 参数内建能力。
      */
     private executeTask;
     /**
@@ -782,6 +867,34 @@ declare function _captureReplyChannelSnapshot(): BackgroundTask["replyChannel"]
  * traced 版 captureReplyChannelSnapshot（供 debug trace 观测 task 的回复目标快照）。
  */
 export declare const captureReplyChannelSnapshot: typeof _captureReplyChannelSnapshot;
+/**
+ * ★ Task #5265 — 把当前 EnvContext.pluginEnabled 拍成不可变快照。
+ *
+ * ## 为什么需要（生产故障 2026-11-10 12:45）
+ *
+ * 后台任务完成通知链路（task.background.completed → 通知会话）的
+ * 合成 envEvent **pluginEnabled={}（空）** →
+ * WecomTaskNotifyPlugin.execute 的 pluginEnabled 守卫
+ * （key=wecom-bot-2:WecomTaskNotifyPlugin）不通过 → 插件直接 return
+ * 不发卡（用户只看到纯文本）。
+ *
+ * 主会话（事件轮直发）pluginEnabled 由 event-source-handlers 构建
+ * （有 key）→ 有卡。合成事件（publishBackgroundEvent）此前不携带
+ * pluginEnabled，dispatcher 的重建逻辑依赖 metadata.plugins（也为空）
+ * → 守卫拦截。
+ *
+ * 修复：delegate 时刻快照 pluginEnabled，随 task 存
+ * `BackgroundTask.pluginEnabledSnapshot`，publishBackgroundEvent 时
+ * 写进 event.metadata.pluginEnabled —— 通知轮合成 envEvent 自带，
+ * dispatcher / buildRunEnvContext 透传 → 守卫放行。
+ *
+ * 返回 undefined 当没有 EnvContext / 没有 pluginEnabled（向后兼容）。
+ */
+declare function _capturePluginEnabledSnapshot(): Record<string, boolean> | undefined;
+/**
+ * traced 版 capturePluginEnabledSnapshot（供 debug trace 观测快照结果）。
+ */
+export declare const capturePluginEnabledSnapshot: typeof _capturePluginEnabledSnapshot;
 declare function handleBackgroundTask(backgroundTaskManager: BackgroundTaskManager, parentSessionId: string, description: string, prompt: string, subagentType: string, timeout?: number, similarTaskIds?: number[], 
 /**
  * ★ 2026-07-10 新增（Task #1752 subSessionId 复用机制）
@@ -804,5 +917,17 @@ model?: string, fallbackModel?: string,
  * Task #4724 — 父 agent 本次 run 的兜底模型**有序列表**。
  * 透传给 createTask → sub-agent 的 AgentContext（顺序 = 优先级）。
  */
-fallbackModels?: string[]): Promise<ToolResult>;
+fallbackModels?: string[], 
+/**
+ * ★ Task #5217 fix 2 — 父 agent 本次 run 的 channel systemPrompt
+ * （ToolContext.metadata.systemPrompt，per-event）。
+ * 透传给 createTask → sub-agent 的 AgentContext.metadata.systemPrompt。
+ */
+systemPrompt?: string, 
+/**
+ * ★ Task #5333 — 父 run 的渠道专用工具放行名单（AgentContext.extendTools）。
+ * 透传给 createTask → sub-agent 的 AgentContext.extendTools，使委派出去的
+ * 子任务仍能调用本渠道的 channelOnly 工具（如 wecom_respond）。
+ */
+extendTools?: string[]): Promise<ToolResult>;
 export { handleBackgroundTask };

package/dist/env/task/delegate/delegate-tool.js

@@ -7,34 +7,38 @@ import {
   WORKFLOW_COMPAT_ALIASES,
   buildEntryAgentPrompt,
   builtInSubAgents,
+  capturePluginEnabledSnapshot,
   captureReplyChannelSnapshot,
   createDelegateTool,
   deriveTriggerEventIdFromEnvContext,
   getSubAgentSpec,
-  handleBackgroundTask
-} from "../../../shared/@ai-setting/roy-agent-core-aa2j7bk9.js";
+  handleBackgroundTask,
+  normalizeExtendTools
+} from "../../../shared/@ai-setting/roy-agent-core-0sbmdz8d.js";
 import"../../../shared/@ai-setting/roy-agent-core-fttgm52a.js";
-import"../../../shared/@ai-setting/roy-agent-core-na18zwj0.js";
-import"../../../shared/@ai-setting/roy-agent-core-9vxh6f8h.js";
+import"../../../shared/@ai-setting/roy-agent-core-4t3yskp8.js";
+import"../../../shared/@ai-setting/roy-agent-core-y7fqtzk2.js";
 import"../../../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
 import"../../../shared/@ai-setting/roy-agent-core-m46fe3x4.js";
 import"../../../shared/@ai-setting/roy-agent-core-4rtg69cn.js";
-import"../../../shared/@ai-setting/roy-agent-core-ed233k5z.js";
+import"../../../shared/@ai-setting/roy-agent-core-v1n0106v.js";
 import"../../../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";
 import"../../../shared/@ai-setting/roy-agent-core-c1v263jn.js";
-import"../../../shared/@ai-setting/roy-agent-core-cpcd24n2.js";
-import"../../../shared/@ai-setting/roy-agent-core-qqaak24r.js";
-import"../../../shared/@ai-setting/roy-agent-core-7cbpmk4q.js";
-import"../../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";
+import"../../../shared/@ai-setting/roy-agent-core-yet36q5k.js";
+import"../../../shared/@ai-setting/roy-agent-core-tkpp1ba0.js";
+import"../../../shared/@ai-setting/roy-agent-core-p31ftgq9.js";
+import"../../../shared/@ai-setting/roy-agent-core-5s2t8z00.js";
 import"../../../shared/@ai-setting/roy-agent-core-7f7t9wwp.js";
 import"../../../shared/@ai-setting/roy-agent-core-85xyctnb.js";
 import"../../../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";
 export {
+  normalizeExtendTools,
   handleBackgroundTask,
   getSubAgentSpec,
   deriveTriggerEventIdFromEnvContext,
   createDelegateTool,
   captureReplyChannelSnapshot,
+  capturePluginEnabledSnapshot,
   builtInSubAgents,
   buildEntryAgentPrompt,
   WORKFLOW_COMPAT_ALIASES,

package/dist/env/task/delegate/index.js

@@ -5,20 +5,20 @@ import {
   BackgroundTaskEventTypes,
   BackgroundTaskManager,
   createDelegateTool
-} from "../../../shared/@ai-setting/roy-agent-core-aa2j7bk9.js";
+} from "../../../shared/@ai-setting/roy-agent-core-0sbmdz8d.js";
 import"../../../shared/@ai-setting/roy-agent-core-fttgm52a.js";
-import"../../../shared/@ai-setting/roy-agent-core-na18zwj0.js";
-import"../../../shared/@ai-setting/roy-agent-core-9vxh6f8h.js";
+import"../../../shared/@ai-setting/roy-agent-core-4t3yskp8.js";
+import"../../../shared/@ai-setting/roy-agent-core-y7fqtzk2.js";
 import"../../../shared/@ai-setting/roy-agent-core-1pg0fepg.js";
 import"../../../shared/@ai-setting/roy-agent-core-m46fe3x4.js";
 import"../../../shared/@ai-setting/roy-agent-core-4rtg69cn.js";
-import"../../../shared/@ai-setting/roy-agent-core-ed233k5z.js";
+import"../../../shared/@ai-setting/roy-agent-core-v1n0106v.js";
 import"../../../shared/@ai-setting/roy-agent-core-qxnbvgwe.js";
 import"../../../shared/@ai-setting/roy-agent-core-c1v263jn.js";
-import"../../../shared/@ai-setting/roy-agent-core-cpcd24n2.js";
-import"../../../shared/@ai-setting/roy-agent-core-qqaak24r.js";
-import"../../../shared/@ai-setting/roy-agent-core-7cbpmk4q.js";
-import"../../../shared/@ai-setting/roy-agent-core-qq96p0tj.js";
+import"../../../shared/@ai-setting/roy-agent-core-yet36q5k.js";
+import"../../../shared/@ai-setting/roy-agent-core-tkpp1ba0.js";
+import"../../../shared/@ai-setting/roy-agent-core-p31ftgq9.js";
+import"../../../shared/@ai-setting/roy-agent-core-5s2t8z00.js";
 import"../../../shared/@ai-setting/roy-agent-core-7f7t9wwp.js";
 import"../../../shared/@ai-setting/roy-agent-core-85xyctnb.js";
 import"../../../shared/@ai-setting/roy-agent-core-fs0mn2jk.js";