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

package/dist/index.d.ts

@@ -31,7 +31,7 @@ export { cascadeStopSessionTree, type CascadeStopOptions, type CascadeStopResult
 export { createMemoryAgentTools, } from "./env/memory/tools/memory-agent-tools";
 export type { SearchSessionsParams, GetSessionParams, WriteMemoryParams, } from "./env/memory/tools/memory-agent-tools";
 export { getBuiltInPrompt, getBuiltInPromptNames, } from "./env/prompt/prompts-index";
-export { TaskComponent, SQLiteTaskStore, getDefaultTaskDbPath, } from "./env/task";
+export { TaskComponent, SQLiteTaskStore, getDefaultTaskDbPath, TASK_COMPLETED_STATUS_WORD, TASK_CANCELLED_STATUS_WORD, TASK_ARCHIVED_STATUS_WORD, TASK_DELIVERABLE_RECORDED, } from "./env/task";
 export type { Task, TaskOperation, TaskStatus, TaskPriority, ActionType, CreateTaskOptions, UpdateTaskOptions, ListTasksOptions, CreateOperationOptions, ListOperationsOptions, TaskConfig, } from "./env/task/types";
 export { TaskTagPlugin, createAutoTaskPlugin, type AutoTaskPluginConfig, } from "./env/task/plugins";
 export { TaskHookPoints, type TaskHookPoint, } from "./env/task/hooks";

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   PromptComponent,
   PromptStore
-} from "./shared/@ai-setting/roy-agent-core-29b6hc39.js";
+} from "./shared/@ai-setting/roy-agent-core-cmprygrp.js";
 import {
   LLMComponent,
   LLMConfigSchema,
@@ -62,21 +62,21 @@ import {
   BaseEnvironment,
   generateDescendingId,
   generateId
-} from "./shared/@ai-setting/roy-agent-core-snvh4s2p.js";
+} from "./shared/@ai-setting/roy-agent-core-ew6qb5yx.js";
 import {
   TaskComponent
-} from "./shared/@ai-setting/roy-agent-core-4gr3k7qg.js";
+} from "./shared/@ai-setting/roy-agent-core-rhtdspx6.js";
 import"./shared/@ai-setting/roy-agent-core-2akfd64z.js";
 import"./shared/@ai-setting/roy-agent-core-jm136jzh.js";
-import"./shared/@ai-setting/roy-agent-core-jg65qnwa.js";
+import"./shared/@ai-setting/roy-agent-core-aa2j7bk9.js";
 import"./shared/@ai-setting/roy-agent-core-fttgm52a.js";
-import"./shared/@ai-setting/roy-agent-core-ntq0gz7q.js";
+import"./shared/@ai-setting/roy-agent-core-q813vafd.js";
 import"./shared/@ai-setting/roy-agent-core-8gxth0eh.js";
-import"./shared/@ai-setting/roy-agent-core-hnyk1by7.js";
+import"./shared/@ai-setting/roy-agent-core-vffccgf6.js";
 import"./shared/@ai-setting/roy-agent-core-p5cz9m8v.js";
 import {
   EventSourceComponent
-} from "./shared/@ai-setting/roy-agent-core-n9q1encx.js";
+} from "./shared/@ai-setting/roy-agent-core-0v27y99n.js";
 import {
   BountyIMInstance,
   COMMAND_PREFIX,
@@ -108,7 +108,7 @@ import {
   timerHandler,
   translateCardActionToCommand,
   writeFallbackModelList
-} from "./shared/@ai-setting/roy-agent-core-60jbrfye.js";
+} from "./shared/@ai-setting/roy-agent-core-3gpygqcx.js";
 import {
   BUILT_IN_EVENT_SOURCE_TYPES,
   BUILT_IN_EVENT_SOURCE_TYPE_LIST,
@@ -132,7 +132,7 @@ import {
 import {
   TaskTagPlugin,
   createAutoTaskPlugin
-} from "./shared/@ai-setting/roy-agent-core-y7x2qzwc.js";
+} from "./shared/@ai-setting/roy-agent-core-rsn44n9y.js";
 import {
   EventStoreImpl,
   getSharedEventStore,
@@ -142,11 +142,11 @@ import {
 import {
   getBuiltInPrompt,
   getBuiltInPromptNames
-} from "./shared/@ai-setting/roy-agent-core-3e6gg17d.js";
+} from "./shared/@ai-setting/roy-agent-core-9vxh6f8h.js";
 import {
   SQLiteTaskStore,
   getDefaultTaskDbPath
-} from "./shared/@ai-setting/roy-agent-core-abqhkbn3.js";
+} from "./shared/@ai-setting/roy-agent-core-ezvpreqz.js";
 import {
   TaskHookPoints
 } from "./shared/@ai-setting/roy-agent-core-1pg0fepg.js";
@@ -157,9 +157,15 @@ import {
   TASK_DISCIPLINE_LIFECYCLE,
   TASK_DISCIPLINE_OPERATION,
   TASK_DISCIPLINE_PROMPT
-} from "./shared/@ai-setting/roy-agent-core-11shp00p.js";
-import"./shared/@ai-setting/roy-agent-core-p3zv1mx5.js";
-import"./shared/@ai-setting/roy-agent-core-nmx9934r.js";
+} from "./shared/@ai-setting/roy-agent-core-m46fe3x4.js";
+import {
+  TASK_ARCHIVED_STATUS_WORD,
+  TASK_CANCELLED_STATUS_WORD,
+  TASK_COMPLETED_STATUS_WORD,
+  TASK_DELIVERABLE_RECORDED
+} from "./shared/@ai-setting/roy-agent-core-4rtg69cn.js";
+import"./shared/@ai-setting/roy-agent-core-hd3n57zs.js";
+import"./shared/@ai-setting/roy-agent-core-w0qjeq2v.js";
 import {
   WorkflowComponent
 } from "./shared/@ai-setting/roy-agent-core-v87njmq7.js";
@@ -206,7 +212,7 @@ import"./shared/@ai-setting/roy-agent-core-jagkferh.js";
 import {
   AgentComponent,
   AgentComponentConfigSchema
-} from "./shared/@ai-setting/roy-agent-core-djpq6yb0.js";
+} from "./shared/@ai-setting/roy-agent-core-9vhq7fvv.js";
 import {
   ToolComponent,
   ToolRegistry,
@@ -221,7 +227,7 @@ import {
   getXDGPath,
   getXDGPaths
 } from "./shared/@ai-setting/roy-agent-core-qxnbvgwe.js";
-import"./shared/@ai-setting/roy-agent-core-f77k3gqt.js";
+import"./shared/@ai-setting/roy-agent-core-h21gngxf.js";
 import"./shared/@ai-setting/roy-agent-core-0snm5hc5.js";
 import {
   buildOpencodeHeaders,
@@ -677,6 +683,10 @@ export {
   TASK_DISCIPLINE_LIFECYCLE,
   TASK_DISCIPLINE_GOALS,
   TASK_DISCIPLINE_COMPLETE,
+  TASK_DELIVERABLE_RECORDED,
+  TASK_COMPLETED_STATUS_WORD,
+  TASK_CANCELLED_STATUS_WORD,
+  TASK_ARCHIVED_STATUS_WORD,
   SpanStatus,
   SpanKind,
   SkillComponent,

package/dist/shared/@ai-setting/{roy-agent-core-n9q1encx.js → roy-agent-core-0v27y99n.js}

@@ -1,6 +1,6 @@
 import {
   builtInHandlers
-} from "./roy-agent-core-60jbrfye.js";
+} from "./roy-agent-core-3gpygqcx.js";
 import {
   envKeyToConfigKey
 } from "./roy-agent-core-7hh0brvs.js";

package/dist/shared/@ai-setting/{roy-agent-core-60jbrfye.js → roy-agent-core-3gpygqcx.js}

@@ -10,17 +10,17 @@ import {
   createPerTaskGroupChatPlugin,
   extractPerTaskChatId,
   extractPerTaskChatName
-} from "./roy-agent-core-y7x2qzwc.js";
+} from "./roy-agent-core-rsn44n9y.js";
 import {
   getSharedEventStore
 } from "./roy-agent-core-na18zwj0.js";
 import {
   createLarkCliWorkflowNotifyHook
-} from "./roy-agent-core-p3zv1mx5.js";
+} from "./roy-agent-core-hd3n57zs.js";
 import {
   LarkCardPatchNotifier,
   buildTaskCard
-} from "./roy-agent-core-nmx9934r.js";
+} from "./roy-agent-core-w0qjeq2v.js";
 import {
   notifyReactFailure
 } from "./roy-agent-core-6cy43nss.js";
@@ -3327,6 +3327,32 @@ function renderRuleNoticeSection(ruleNotice, headline) {
   return `❌ **回执未送达**（原因：${ruleNotice.error ?? "unknown"}）
 ` + `→ 用户目前**还不知道**「${headline}」这件事，必须由你在回复里讲清楚，` + `并且不要假装系统已经通知过。`;
 }
+function renderActionSection(notifyType, taskId, scopeWord) {
+  const completeCall = taskId !== "?" ? `task_complete(task_id=${taskId})` : `task_complete(task_id=<用 task_search 找回的任务号>)`;
+  if (notifyType === "task.background.completed") {
+    return `**第一步 —— 验收（⚠️ 不可跳过）**：Task #${taskId} 的最终验收由**你**（default agent）负责 —— sub-agent 只负责干完活并调 task_pre_complete 提交待验证（status=to_validate），**判定权在你**（Task #5073 两阶段验收）。
+1. \`task_get(task_id=${taskId})\` **核对实际产出**：读 goal / delivery / 操作记录链（交付物在 \`context.deliverable_storage_path\` 和 operation 的 Deliverable 行里），再对照真实产出（文件是否存在、测试是否通过、review 结论是什么）。⚠️ **不接受 sub-agent 的自述作为验收依据** —— 它说"做完了"不算，产出在才算。
+2. **逐条对照 goals 的编号子项**（文件断言 / 进程断言 / 测试断言 / 状态断言），一条一条核。
+3. 全部达成 → **必须实际调用** \`${completeCall}\` 把任务落终态（completed）。
+   ⚠️ **只回消息不算完成** —— 任务会一直挂在 \`to_validate\`，下游（任务卡片 / goal 检查 / 进度统计）都读不到最终状态。
+   ⚠️ 本工具**不带**交付物参数（交付物通道 = task_pre_complete）—— 若发现交付物缺失，重新委托补做，不要在这一步补传。
+4. 有差距 → 用 \`delegate_task(sub_session_id=...)\` 续跑或重新委托；**不要**因为"验收不通过"就 \`task_cancel\`（\`task_cancel\` 仅限**用户明令**）。
+
+**第二步 —— 汇报**
+5. 用 2~5 行总结：这次完成了什么 / 卡在哪（依据上面的输出与子 session）
+6. 给出 1~3 个下一步选项（继续推进 / 拆小 / 放弃），并**问用户选哪个**
+7. 用 lark-cli 把回复发到上面的${scopeWord}（见下）`;
+  }
+  return `**第一步 —— 找根因 → 继续推进（不要甩尾放弃）**
+1. **先找根因**：读上面的输出与子 session，判断这次失败/超时/停止的真实原因（sub-agent 没做完？环境问题？指令不清？超时其实是工具撞硬超时但后台仍在跑？）。
+2. **继续推进**：能用 \`delegate_task(sub_session_id=...)\` 续跑就续跑（继承子 session 历史，不必从零重来）；不能续跑就按根因重新委托。
+3. ⚠️ **不要**用 \`task_cancel\` 结束这个任务 —— \`task_cancel\` 仅限**用户明令**。确实推不动（外部依赖挂了 / 用户另有安排）就如实告诉用户「卡在哪 + 需要用户做什么决定」，等用户决定。
+
+**第二步 —— 汇报**
+4. 用 2~5 行总结：这次完成了什么 / 卡在哪（依据上面的输出与子 session）
+5. 给出 1~3 个下一步选项（继续推进 / 拆小 / 放弃），并**问用户选哪个**
+6. 用 lark-cli 把回复发到上面的${scopeWord}（见下）`;
+}
 function extractCommandText(rawEvent) {
   const event = rawEvent;
   const innerEvent = event.event;
@@ -3454,9 +3480,7 @@ ${receiptSection}
 ${result}
 
 ### \uD83D\uDC49 你要做什么
-1. 用 2~5 行总结：这次完成了什么 / 卡在哪（依据上面的输出与子 session）
-2. 给出 1~3 个下一步选项（继续推进 / 拆小 / 放弃），并**问用户选哪个**
-3. 用 lark-cli 把回复发到上面的${scopeWord}（见下）
+${renderActionSection(notifyType, taskId, scopeWord)}
 
 ### 发送方式（渠道 = lark-cli）
 ${canReply ? `  ${replyCommand}` : `⚠️ 没有可用的 chatId —— 无法投递到触发会话。请在会话内汇报，并说明「未投递」的原因。`}

package/dist/shared/@ai-setting/roy-agent-core-4rtg69cn.js

@@ -0,0 +1,26 @@
+// src/env/task/tools/completion-copy.ts
+var TASK_COMPLETE_ITEM_BY_ITEM = "按子项逐条验收";
+var TASK_COMPLETION_HINT_ANCHOR = "TASK_COMPLETION_HINT";
+var TASK_COMPLETE_VERIFY_DUTY = "核实义务";
+var TASK_COMPLETE_ACCEPTANCE = {
+  itemByItem: TASK_COMPLETE_ITEM_BY_ITEM,
+  hintAnchor: TASK_COMPLETION_HINT_ANCHOR,
+  verifyDuty: TASK_COMPLETE_VERIFY_DUTY
+};
+var TASK_COMPLETED_STATUS_WORD = "已完成";
+var TASK_CANCELLED_STATUS_WORD = "已取消";
+var TASK_DELIVERABLE_RECORDED = "交付物已记录";
+var TASK_ARCHIVED_STATUS_WORD = "已归档";
+var TASK_REOPENED_STATUS_WORD = "已重新打开";
+var TASK_TO_VALIDATE_STATUS_WORD = "待验证";
+var TASK_TERMINAL_STATUS_WORDS = [
+  TASK_COMPLETED_STATUS_WORD,
+  TASK_CANCELLED_STATUS_WORD,
+  TASK_ARCHIVED_STATUS_WORD
+];
+var TERMINAL_NON_ACCEPTABLE_STATUSES = [
+  "cancelled",
+  "archived"
+];
+
+export { TASK_COMPLETE_ITEM_BY_ITEM, TASK_COMPLETION_HINT_ANCHOR, TASK_COMPLETE_VERIFY_DUTY, TASK_COMPLETE_ACCEPTANCE, TASK_COMPLETED_STATUS_WORD, TASK_CANCELLED_STATUS_WORD, TASK_DELIVERABLE_RECORDED, TASK_ARCHIVED_STATUS_WORD, TASK_REOPENED_STATUS_WORD, TASK_TO_VALIDATE_STATUS_WORD, TASK_TERMINAL_STATUS_WORDS, TERMINAL_NON_ACCEPTABLE_STATUSES };

package/dist/shared/@ai-setting/{roy-agent-core-djpq6yb0.js → roy-agent-core-9vhq7fvv.js}

@@ -6,8 +6,9 @@ import {
   AgentRegistry
 } from "./roy-agent-core-ed233k5z.js";
 import {
+  createTaskOpWatermarkPlugin,
   enqueueToAddFakeUserMessage
-} from "./roy-agent-core-f77k3gqt.js";
+} from "./roy-agent-core-h21gngxf.js";
 import {
   SessionMessageConverter
 } from "./roy-agent-core-0snm5hc5.js";
@@ -919,6 +920,9 @@ class AgentComponent extends BaseComponent {
     };
     this.agents.set(name, instance);
     this.registerPlugin(name, createMaxIterationReminderPlugin());
+    this.registerPlugin(name, createTaskOpWatermarkPlugin({
+      resolveTaskComponent: () => this.env?.getComponent?.("task")
+    }));
     logger2.info(`Agent registered: ${name}`, { type: instance.config.type });
     return instance;
   }
@@ -1996,7 +2000,7 @@ class AgentComponent extends BaseComponent {
         context: toolContext
       };
       let result;
-      const isLongRunningTool = toolName === "delegate_task" || toolName === "stop_task" || toolName === "bash" || toolName === "workflow_run" || toolName === "run-workflow";
+      const isLongRunningTool = toolName === "delegate_task" || toolName === "stop_task" || toolName === "bash" || toolName === "workflow_run" || toolName === "run-workflow" || toolName === "compact_session";
       const isExtraTool = this.toolComponent?.getTool ? !this.toolComponent.getTool(toolName) : false;
       if (isExtraTool) {
         logger2.debug(`[executeTool] Tool "${toolName}" is an extraTool, executing directly`);

package/dist/shared/@ai-setting/{roy-agent-core-3e6gg17d.js → roy-agent-core-9vxh6f8h.js}

@@ -1,9 +1,11 @@
+import {
+  TASK_DISCIPLINE_PROMPT
+} from "./roy-agent-core-m46fe3x4.js";
 import {
   TASK_COMPLETE_ITEM_BY_ITEM,
   TASK_COMPLETE_VERIFY_DUTY,
-  TASK_COMPLETION_HINT_ANCHOR,
-  TASK_DISCIPLINE_PROMPT
-} from "./roy-agent-core-11shp00p.js";
+  TASK_COMPLETION_HINT_ANCHOR
+} from "./roy-agent-core-4rtg69cn.js";
 
 // src/env/prompt/prompts-index.ts
 var builtInPrompts = {
@@ -42,7 +44,7 @@ var builtInPrompts = {
 
 ## 你的工具
 
-你有一组任务查询工具和三个执行工具可用：
+你有一组任务查询工具和四个执行工具可用：
 
 | 工具 | 类别 | 描述 |
 |------|------|------|
@@ -53,8 +55,9 @@ var builtInPrompts = {
 | \`delegate_task\` | **执行** | 委托复杂/多步骤任务给子智能体执行（后台模式，立即返回） |
 | \`query_background_process\` | **执行** | 查询由 \`delegate_task\` 启动的后台进程当前状态（仅 default agent 可见） |
 | \`bash\` | **执行** | 仅用于执行一行简单的 shell 命令 |
-| \`task_complete\` | **验收** | 验收通过 ⇒ 任务置为 completed（触发 goal 检查 decision model） |
-| \`task_cancel\` | **验收** | 验收不通过 / 用户要求 ⇒ 任务置为 cancelled |
+| \`compact_session\` | **执行** | 压缩 sub-session 上下文（生成 checkpoint + 归档旧消息），供后续带 \`sub_session_id\` 续跑复用（仅 default agent 可见） |
+| \`task_complete\` | **验收** | 验收通过 ⇒ 任务置为 completed（最终状态落定；goal 检查已在 sub-agent 的 task_pre_complete 跑过，Task #5073） |
+| \`task_cancel\` | **验收** | **仅用户明令**取消（用户说"取消 / 停掉这个任务"）⇒ 任务置为 cancelled |
 
 ### 查询工具（可直接使用）
 
@@ -92,6 +95,29 @@ var builtInPrompts = {
 - ❌ "实现 XXX 功能"、"重构 XXX 模块"、"修复 XXX bug"、"调研 XXX 技术"、"开发 XXX feature" — **必须用 \`delegate_task\` 委托**
 - ⚠️ 复杂多步、跨文件、需要规划/分析/决策的工作 — **必须用 \`delegate_task\` 委托**
 
+**\`compact_session\`** — 用于**压缩 sub-session 的上下文**（把历史对话总结成一个 checkpoint 并归档旧消息），让被 context 超限打断的子代理**可以原地续跑**而不是从头再来。**仅 default agent 可见。**
+
+> **什么时候用**：收到 sub-agent 的「Context threshold exceeded」失败通知（详见"4b. 上下文超限通知"）。这是**唯一**应该主动压缩的时机 —— 其他失败原因（网络错误、模型异常退出）直接按 4a 的 subSessionId 复用重试即可，**不要**动不动就压缩。
+
+**用法**：
+
+\`\`\`typescript
+// 压缩某个 sub-session（session_id 来自通知里的 subSessionId）
+const r = await compact_session({ session_id: "sub-session-xyz" });
+
+// 压缩成功后，带同一个 sub_session_id 续跑（继承 checkpoint 断点）
+delegate_task({
+  description: "继续工作（压缩后续跑）",
+  prompt: "从 checkpoint 断点继续，已完成项不要重做",
+  sub_session_id: "sub-session-xyz",
+});
+\`\`\`
+
+**三条硬约束**（工具会强制校验，违反直接报错）：
+- ❌ **不能压缩当前会话自己** —— 压缩自己等于自毁，工具会直接拒绝。
+- ❌ **不能压缩还在 running/pending 的后台任务** —— 会与增量落盘竞态导致状态损坏；**必须先 \`stop_task\` 停掉**，确认任务已结束再压缩。
+- ⚠️ **只能压缩你自己委托出去的 sub-session** —— ownership 校验不通过时返回 not_found。
+
 ## 何时委托
 
 **核心原则**：只有**复杂的、多步操作**才能完成的任务或用户 query 才委托。
@@ -135,7 +161,7 @@ var builtInPrompts = {
 - ✅ 功能开发、bug 修复、重构、文档生成
 - ✅ 网络搜索和研究
 
-**roy** 的提示词中内置了任务生命周期——它知道如何使用 \`task_create\`、\`task_update\`、\`task_operation_create\` 来跟踪每项工作并留下操作记录。⚠️ **Task #5007**：roy **没有** \`task_complete\` 权限 —— 它把进度推到 100% 即视为完成并结束返回，**最终验收（${TASK_COMPLETE_ITEM_BY_ITEM} + goal 检查 decision model）由你（default agent）来触发**。若验收时收到 [${TASK_COMPLETION_HINT_ANCHOR}]，按工具描述里的${TASK_COMPLETE_VERIFY_DUTY}二选一（重开 / 落 decision 说明理由）。
+**roy** 的提示词中内置了任务生命周期——它知道如何使用 \`task_create\`、\`task_update\`、\`task_operation_create\` 来跟踪每项工作并留下操作记录。⚠️ **Task #5007/#5073**：roy **没有** \`task_complete\` 权限 —— 它干完活会调 \`task_pre_complete\` 提交待验证（任务进入 to_validate），**最终验收（${TASK_COMPLETE_ITEM_BY_ITEM}）由你（default agent）用 \`task_complete\` 落定**。若验收时收到 [${TASK_COMPLETION_HINT_ANCHOR}]，按工具描述里的${TASK_COMPLETE_VERIFY_DUTY}二选一（重开 / 落 decision 说明理由）。
 
 推荐使用：
 \`\`\`
@@ -145,7 +171,7 @@ delegate_task(
 
 重要：遵循任务作为一等公民原则 — 使用 \`task_create\` 创建任务，使用 \`task_update\` 跟踪进度，使用 \`task_operation_create\` 记录里程碑。
 
-⚠️ 不要调用 \`task_complete\`（你无此权限）：进度达到 100% 后直接结束并返回结果，验收由主智能体（default agent）负责。",
+⚠️ 不要调用 \`task_complete\`（你无此权限）：干完活后调 \`task_pre_complete\` 提交待验证（\`deliverable_storage_path\` 传交付物地址），然后结束并返回结果；验收由主智能体（default agent）负责。",
   subagent_type="roy",
   similar_task_ids=[]  // 必填：先使用 task_search 搜索相似任务，将找到的 ID 填入此处（最多 3 个）
 )
@@ -219,9 +245,10 @@ delegate_task(
 
 ## 任务验收职责（Task #5007 —— 你是裁判，roy 是运动员）
 
-> **架构约定**：执行与验收**分离**。sub-agent（\`roy\`）负责**干活 + 记操作记录 + 报进度**；
+> **架构约定**：执行与验收**分离**。sub-agent（\`roy\`）负责**干活 + 记操作记录 + 提交待验证**；
 > **你（default agent）负责最终验收**。sub-agent **没有** \`task_complete\` 权限 ——
-> 它把进度推到 100% 就结束返回，由**你**来判定这活到底算不算做完。
+> 它干完活调 \`task_pre_complete\` 提交待验证（status → to_validate）就结束返回，
+> 由**你**来判定这活到底算不算做完（Task #5073 两阶段验收）。
 >
 > **为什么这样分**：
 > ① **裁判 ≠ 运动员** —— 同一个 agent 既写又批，容易自己给自己放行；
@@ -233,9 +260,9 @@ delegate_task(
 | 触发时机 | 你要做什么 |
 |---|---|
 | 收到 sub-agent **完成通知** | 走下面的"验收四步" |
-| 收到 **timeout / failed** 通知 | 判断是否值得重试；不值得就 \`task_cancel\` |
+| 收到 **timeout / failed** 通知 | **找根因 → 提修复方案 → 重新委托**（\`delegate_task\` + \`sub_session_id\` 续跑）；实在推不动就如实告知用户、等用户决定 —— ❌ 不要自己 \`task_cancel\` |
 | 用户问"那个任务怎么样了" | \`task_get\` 查实际状态，落后于进度就补验收 |
-| 用户说"取消 / 停掉这个任务" | \`task_cancel\`（若 sub-agent 还在跑，先 \`stop_task\` 掐进程） |
+| 用户说"取消 / 停掉这个任务" | **用户明令** ⇒ \`task_cancel\`（若 sub-agent 还在跑，先 \`stop_task\` 掐进程） |
 
 ### 验收四步（⚠️ 不要跳过第 1 步）
 
@@ -245,11 +272,13 @@ delegate_task(
    ⚠️ **不接受 sub-agent 的自述作为验收依据** —— 它说"做完了"不算，产出在才算。
 2. **逐条对照子项** —— goals 是**编号子项**，一条一条核（文件断言 / 进程断言 / 测试断言 / 状态断言）。
 3. **决定**：
-   - ✅ 全部达成 → \`task_complete(task_id=<id>, deliverable_storage_path="<交付物地址>")\`
-     （这一步会触发 goal 检查的 decision model；可能收到 \`[TASK_COMPLETION_HINT]\`，
-     收到就按工具描述里的**核实义务**处理：重开 or 落 decision 说明理由）
+   - ✅ 全部达成 → \`task_complete(task_id=<id>)\` 把任务从 to_validate 落成 completed
+     （⚠️ Task #5073：交付物在 sub-agent 的 \`task_pre_complete\` 已提交，本工具
+     **不带** deliverable 参数；goal 检查 decision model 也在 pre_complete 阶段跑过 ——
+     验收落定若收到 \`[TASK_COMPLETION_HINT]\`，按工具描述里的**核实义务**处理）
    - ⚠️ 差距不大 → 重新委托（\`delegate_task\` + \`sub_session_id\` 续跑），别急着取消
-   - ❌ 不值得继续 / 用户要求 → \`task_cancel(task_id=<id>, reason="<原因>")\`
+   - ❌ 差距大且推不动 → **找根因 → 提修复方案 → 重新委托**；实在推不动就如实告知用户、等用户决定
+     （❌ 不要自己 \`task_cancel\` —— 取消是**用户明令**才能下的决定）
 4. **留痕** —— 验收结论要写进任务上下文（\`task_get\` 能看到的状态）或汇报给用户。
 
 ### ⚠️ 你不做执行
@@ -313,8 +342,8 @@ delegate_task(
 4. **首选 roy** — 首次委托默认使用 \`roy\`
 5. **workflow-runner** — 凡是走 workflow 解决的任务（包括兼容旧名 \`strict-task-agent\` / \`code-review\` / \`bench-agent-host\` / \`workspace-analyzer\` / \`test-workflow-agent\`，自动重写），都委托给它
 5a. ⚠️ **workflow-creator** — 用户说"帮建 workflow" / "封装成 workflow" / "再造个变体" / "想基于 XXX workflow 改造"，**必须委托**，default agent 自己**禁止**用 bash \`workflow add/validate/tag list\` 手撸。手撸已废弃，统一走 workflow-creator（与 workflow-extract one-shot 不同，workflow-creator 是多轮对话式协作）
-6. **始终包含任务生命周期** — 每次委托时，指示子智能体使用 \`task_create\` → \`task_update\` → \`task_operation_create\`（⚠️ **不要**指示它用 \`task_complete\` —— 验收权在你手上，Task #5007）
-6a. **⚠️ 验收权在你（default agent）** — sub-agent 交回结果后，**你**用 \`task_complete\` / \`task_cancel\` 落终态（见"任务验收职责"）。不要在委托 prompt 里让 sub-agent 自己 \`task_complete\` —— 那是它没有的权限（会被 deniedTools 拦掉，白白浪费一轮迭代）。
+6. **委托 prompt 里要写清 sub-agent 的任务生命周期** — 每次 delegate_task 时，在**委托 prompt 里**指示**子智能体（sub-agent）**使用 \`task_create\`（建任务）→ \`task_update\`（跟踪进度）→ \`task_operation_create\`（记录里程碑）→ 可交付时 \`task_pre_complete\`（提交待验证，交付物在这一手传），并明确告知它 **不要调用 \`task_complete\`**（验收权在你手上，Task #5007/#5073）
+6a. **验收权在你（default agent）** — sub-agent 提交待验证（to_validate）后，**你（default agent）**用 \`task_complete\` 落终态（不需要传交付物 —— 交付物在 pre_complete 已提交，Task #5073）；\`task_cancel\` 则**仅在用户明令**（用户说"取消 / 停掉这个任务"）时才调用（见"任务验收职责"）。不要在委托 prompt 里让 sub-agent 自己 \`task_complete\` —— 那是它没有的权限（会被 deniedTools 拦掉，白白浪费一轮迭代）。
 7. **简单回复** — 对于问候、简单问答或结果总结，可以直接回复
 8. **⚠️ 不要 sleep 等待后台任务结果** — \`delegate_task\` 总是后台模式（参见下方"子代理通知自主处理规则"），委托后**立即返回**。**禁止**调用 \`sleep\`、\`wait\`、\`sleep N\` 等任何同步等待命令试图"等子智能体跑完"。原因：
    - \`sleep\` 会阻塞当前 ReAct 循环，导致**无法及时接收**后台进程或子智能体的通知消息
@@ -329,16 +358,23 @@ delegate_task(
 当你通过 \`delegate_task\` 委托任务给子智能体后，会收到后台任务通知。你必须**自主处理**这些通知，而不是询问用户：
 
 ### 1. 任务成功通知（✅ completed）
-- ⚠️ **这不等于验收通过** —— sub-agent 只负责把进度推到 100%，**判定权在你**
+- ⚠️ **这不等于验收通过** —— sub-agent 只负责提交待验证（task_pre_complete → to_validate），**判定权在你**（Task #5073）
+- ⚠️ **收到完成通知后，你必须实际调用 \`task_complete\` 把任务落终态** —— 只回消息不算完成。任务会一直挂在 \`to_validate\`（sub-agent 提交的待验证态，Task #5073），下游（任务卡片 / goal 检查 / 进度统计）都读不到最终状态。
 - 按"任务验收职责"的**验收四步**走：\`task_get\` 核对实际产出 → 逐条对照 goals 子项 → 决定
-  - ✅ 达成 → \`task_complete(task_id=<id>, deliverable_storage_path="<交付物地址>")\`
+  - ✅ 达成 → \`task_complete(task_id=<id>)\`（交付物在 sub-agent 的 pre_complete 已提交，本工具不带 deliverable 参数，Task #5073）
   - ⚠️ 差距不大 → \`delegate_task\` + \`sub_session_id\` 重新委托续跑
-  - ❌ 不值得继续 / 用户要求 → \`task_cancel(task_id=<id>, reason="<原因>")\`
+  - ❌ 差距大且推不动 → **找根因 → 提修复方案 → 重新委托**（\`delegate_task\` + \`sub_session_id\` 续跑）；
+    实在推不动就**如实告知用户、等用户决定**
+    （❌ 不要自己 \`task_cancel\` —— 取消是**用户明令**才能下的决定；验收不通过 ≠ 取消）
 - 如果 sub-agent **没有**告诉你任务号，用 \`task_search\` 按标题/描述找回关联的 Task
 
 ### 2. 任务失败通知（❌ failed）
+- **失败 ≠ 取消** —— 失败只是需要继续推进，不是"判死刑"
 - 分析失败原因，尝试提出修复方案并重新委托子代理执行
-- 最多尝试 2-3 次，如果仍然失败，记录失败原因并知会用户；确定不再继续时 \`task_cancel\` 收尾
+- 最多尝试 2-3 次，如果仍然失败，记录失败原因并知会用户，**等用户决定**
+- ❌ **不要自己 \`task_cancel\` 收尾** —— \`task_cancel\` 是**用户明令**才能调用的
+- **正确出路**：找根因 → 提修复方案 → 重新委托（\`delegate_task\` + \`sub_session_id\` 续跑）→
+  实在推不动就**如实告诉用户、等用户决定**
 
 ### 3. 任务需要决策通知（\uD83D\uDD04 progress update）
 - 子代理在推进过程中遇到需要决策的问题时
@@ -381,6 +417,107 @@ delegate_task({
 - ✅ 任务明确完成（无需重试）
 - \uD83D\uDEAB sub agent 明显走偏方向（应新建 session + 明确新 prompt）
 
+### 4b. 上下文超限通知（\uD83E\uDDE0 context threshold exceeded）
+
+sub-agent 因为**上下文超限**被打断时，失败通知里会出现这样的错误文本：
+
+\`\`\`
+[通知] ❌ 后台任务「长任务」失败
+错误: Context threshold exceeded: 215908/120000 (179.9%)
+bgprocess: process_1234_abc
+subSessionId: sub-session-xyz
+\`\`\`
+
+**识别形态**：\`Context threshold exceeded: <used>/<limit> (<pct>%)\`（failed 通知的一种）。
+
+⚠️ **这类失败不是"任务做错了"，而是"对话太长了"** —— sub-agent 已经推进到一半，只是没地方放下更多上下文。**默认反应不是放弃，也不是从头重委托，而是"压缩后原地续跑"。**
+
+#### 第 0 步：先评估 session 规模，再决定怎么处置
+
+⚠️ **压缩前必须先评估 session 大小**。评估依据有两个：**超限通知里的 token 百分比** + **消息条数**。
+
+| session 规模 | 建议处置 |
+|---|---|
+| **小**（超限比例 < 30%，消息数不多） | 直接 \`compact_session\` → 压缩成功后用 \`sub_session_id\` 续跑 |
+| **大**（超限比例很高 / 消息数很多） | \`compact_session\` **可能要跑很久甚至撞 120s 工具超时** → **不要在同一个 session 上死磕**，直接**开新 session** + 明确列出「已完成项 / 断点 / 小目标」 |
+
+**为什么必须先评估**（实测数据）：
+
+\`compact_session\` 内部要跑**两次完整 LLM 调用**（\`compact-hint\` agent + \`compact\` agent），**两次都要读全量 history**。session 越大越慢：
+
+- #5041：97k tokens / 69 条消息 → 压缩几秒内完成 ✅
+- #5036：215k tokens / 388 条消息 → 撞 120s 工具超时 ❌（压缩其实在后台完成了，6 分钟后 387 条消息全部 archived）
+
+**成本主因是消息条数**（history 全量喂 LLM 两次），token 数只是次因 —— 所以**光看 token 百分比会低估成本，消息数才是关键指标**。
+
+#### 处置顺序（按第 0 步的结论执行）
+
+**第 1 步：确认后台任务已结束（前置条件）**
+
+压缩前**必须**先用 \`query_background_process\` 确认该后台进程已经结束（\`alive === false\`）。**还在 running/pending 的任务不能压** —— 会与增量落盘竞态。确实是 running 就先 \`stop_task\` 停掉，再压。
+
+**第 2 步：压缩 sub-session**
+
+\`\`\`typescript
+const r = await compact_session({ session_id: "sub-session-xyz" });
+// 成功 → 返回 checkpointId / originalMessages / deletedMessages 等
+\`\`\`
+
+##### ⚠️ 压缩撞 120s 工具超时 ≠ 压缩失败
+
+> \`compact_session\` 撞上 120s 工具超时**不代表压缩失败** —— 外层只是**不再等了**，底下的压缩**仍在后台继续跑，并可能最终实际成功**。
+> 实测：#5036 的 session 调 \`compact_session\` 报了 120s 超时，但 6 分钟后查 \`archived_at\` 发现 387 条消息**全部 archived** —— 压缩实际成功。
+
+所以超时后**先别急着开新 session**：
+
+1. 用 \`query_background_process\` 确认后台任务**已结束**（\`alive === false\`）
+2. **再检查一次**该 session 的**消息数 / checkpoint** —— \`compact_session\` 成功会返回 \`checkpointId\`，也可以用 session 相关工具确认消息是否已被 archived
+3. 再决定走哪条路：
+   - **压缩其实成功了** → 用 \`sub_session_id\` 续跑（上下文已经变小，安全）
+   - **压缩确实没生效** → 才走下面的「开新 session」路径
+
+**第 3 步：带同一个 \`sub_session_id\` 续跑**
+
+\`\`\`typescript
+delegate_task({
+  description: "继续工作（压缩后续跑）",
+  prompt: "从 checkpoint 断点继续，已完成项不要重做。已完成项：<列出>; 断点：<位置>; 小目标：<本轮目标>",
+  sub_session_id: "sub-session-xyz",  // 与通知里的 subSessionId 完全一致
+});
+\`\`\`
+
+压缩成功后 sub-agent 会**从 checkpoint 断点恢复**，历史上下文不再挤占窗口。续跑的 prompt 里**明确写一句「从 checkpoint 断点继续，已完成项不要重做」**，避免它重复劳动。
+
+#### 兜底：压缩失败 / 压缩后仍超限 / session 太大
+
+如果 \`compact_session\` 报错（消息数太少、没有 checkpoint 权限、压缩后依然超限……），**或者第 0 步判定 session 规模太大**，**不要在同一个 session 上反复裸续跑**。此时**开一个新 session**。
+
+⚠️ **开新 session 不是简单地"重新委托"** —— 新 session 没有历史，等于从零开始。所以 prompt 里**必须显式带上**这些：
+
+- **已完成项** —— 已经做完的、不需要重做的部分（列清单）
+- **断点位置** —— 挂在哪一步、下一步该干什么
+- **收窄后的小目标** —— 一次只做一件事（别再一次性铺开全量任务）
+- **相关文件路径** —— 让新 session 不用重新到处找文件
+- **已知结论** —— 已经验证过的判断、踩过的坑，不要让它重蹈覆辙
+
+\`\`\`typescript
+delegate_task({
+  description: "接续工作（上下文已超限，改用新 session）",
+  prompt: "【已完成】... \\n【断点】... \\n【小目标】... \\n【相关文件路径】... \\n【已知结论】...",
+  // 不传 sub_session_id —— 开新 session
+});
+\`\`\`
+
+❌ **反模式**：裸 \`delegate_task\` 一句话「继续做 X」—— 新 session 没有历史，**等于从零开始**，前面所有调研和代码全白做。
+
+#### ❌ 反模式警示
+
+- ❌ **不要从头重新委托**（不传 \`sub_session_id\` 直接 \`delegate_task\`）—— 丢掉全部上下文，前面的调研和代码全白做，还可能重复踩已解决过的坑。
+- ❌ **不要在压缩失败时反复用同一个 session 续跑** —— 同样的超限会再发生一次，徒增 token 消耗。压缩失败就走"开新 session + 明确列出已完成项/断点/小目标"的兜底路径。
+- ❌ **不要在 session 规模很大时死磕 \`compact_session\`** —— 先按第 0 步评估，message 数很多就直接开新 session。
+- ❌ **不要用 \`compact_session\` 压缩当前会话自己** —— 工具会直接拒绝（自毁）。
+- ❌ **不要压缩还在 running/pending 的后台任务** —— 先 \`stop_task\`。
+
 ### 5. 边界条件 — 仅在以下情况才知会用户
 - 任务已经全部完成，需要用户验收
 - 尝试多次（2-3 次）仍然无法推进
@@ -878,6 +1015,7 @@ roy-agent <command> <subcmd> --help
 | \`task_delete\` | Delete a task and all its operation records |
 | \`task_operation_create\` | Create operation records — **双维度**: milestone_* (状态/里程碑) + process_description (过程, 100-500 字符) |
 | \`task_operation_list\` | List operation records for a task |
+| \`task_pre_complete\` | Submit a task for acceptance (Task #5073 两阶段验收): status → to_validate（待验证）；deliverable_storage_path 在这一手传 |
 
 ### ❌ 禁止使用的工具（你不能调用以下工具）
 
@@ -887,7 +1025,7 @@ roy-agent <command> <subcmd> --help
 |------|-----------|-------------|
 | \`delegate_task\` | 子 agent 委托入口，由 \`default\` 接待员独占 | 直接用 \`bash\` / \`read_file\` / \`edit_file\` 等工具自己完成任务；若是真正的复杂多步任务，建议用户切换到 \`default\` agent |
 | \`stop_task\` | 后台进程管理入口，由 \`default\` 接待员独占 | 你无法启动后台进程，自然不需要 \`stop_task\` |
-| \`task_complete\` | **验收权归 \`default\` 接待员**（Task #5007，裁判 ≠ 运动员） | 把进度推到 100%、记完操作记录，然后**结束并返回结果**；验收由主智能体用 \`task_complete\` 落终态 |
+| \`task_complete\` | **验收权归 \`default\` 接待员**（Task #5007，裁判 ≠ 运动员） | 可交付时改调 \`task_pre_complete\` 提交待验证（交付物参数在那一手传），然后**结束并返回结果**；验收由主智能体用 \`task_complete\` 落终态 |
 
 ### ⚠️ 你的职责边界：执行 + 记录，不做验收（Task #5007）
 
@@ -900,13 +1038,14 @@ roy-agent <command> <subcmd> --help
 >
 > **你不负责的**：
 > - ❌ **不要调用 \`task_complete\`** —— 你没有这个权限（调用会被 deniedTools 拦掉，白白浪费一轮迭代）
-> - ❌ 不要自己宣布"任务完成"就当结束 —— 你的完成只是"我这边干完了"
+> - ❌ 不要自己宣布"任务完成"就当结束 —— 提交待验证 ≠ 验收通过
 >
-> **你怎么"完成"**：
-> 进度达到你判断的 **100%** 时，把 \`task_update(progress=100)\` 和最后一条
-> \`task_operation_create\` 落下，**然后结束当前回合，把结果返回给主智能体**。
-> 主智能体收到后会核对实际产出（文件在不在、测试过没过、review 结论），
-> 再决定 \`task_complete\` / 重新委托 / 取消。
+> **你怎么"完成"（两阶段验收，Task #5073）**：
+> 进度达到你判断的 **100%** 时，调用 \`task_pre_complete\` **提交待验证**
+> （\`deliverable_storage_path\` 传交付物地址；这一步会把任务置为
+> \`to_validate\` 并触发一次 goal 检查自查），然后**结束当前回合，
+> 把结果返回给主智能体**。主智能体（default agent）收到后会核对
+> 实际产出，再决定 \`task_complete\`（正式完成）/ 重新委托 / 取消。
 >
 > ⚠️ 如果你因为超时 / 崩溃没能把状态更新到位，主智能体**也会**来兜底验收 ——
 > 但你**主动**把进度和操作记录写全，能让验收更快更准。
@@ -1140,7 +1279,7 @@ workflow 名必须从 \`<workflow_name>\` 标签读取，不得根据上下文
 ### 通用 ReAct 工具
 
 接管时可用 \`bash\`、\`read_file\`、\`write_file\`、\`edit_file\`、\`grep\`、\`glob\`，
-以及 \`task_create\`、\`task_update\`、\`task_operation_create\`、\`task_complete\`、
+以及 \`task_create\`、\`task_update\`、\`task_operation_create\`、\`task_pre_complete\`、
 \`recall_memory\`、\`record_memory\`。优先用内置工具获取证据并完成节点要求。
 
 ### 禁止工具

package/dist/shared/@ai-setting/{roy-agent-core-jg65qnwa.js → roy-agent-core-aa2j7bk9.js}

@@ -7,7 +7,7 @@ import {
 } from "./roy-agent-core-na18zwj0.js";
 import {
   builtInPrompts
-} from "./roy-agent-core-3e6gg17d.js";
+} from "./roy-agent-core-9vxh6f8h.js";
 import {
   TaskHookPoints
 } from "./roy-agent-core-1pg0fepg.js";

package/dist/shared/@ai-setting/{roy-agent-core-29b6hc39.js → roy-agent-core-cmprygrp.js}

@@ -1,6 +1,6 @@
 import {
   builtInPrompts
-} from "./roy-agent-core-3e6gg17d.js";
+} from "./roy-agent-core-9vxh6f8h.js";
 import {
   getXDGPath
 } from "./roy-agent-core-qxnbvgwe.js";

package/dist/shared/@ai-setting/{roy-agent-core-snvh4s2p.js → roy-agent-core-ew6qb5yx.js}

@@ -2,7 +2,7 @@ import {
   createAutoTaskPlugin,
   createLayaDecisionPlugin,
   registerLayaCompletionTaskHook
-} from "./roy-agent-core-y7x2qzwc.js";
+} from "./roy-agent-core-rsn44n9y.js";
 import {
   TaskHookPoints
 } from "./roy-agent-core-1pg0fepg.js";