@ai-setting/roy-agent-core 1.7.72 → 1.7.76

package/dist/shared/@ai-setting/{roy-agent-core-yhwxpj12.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-4jjwewvw.js";
+  TASK_COMPLETION_HINT_ANCHOR
+} from "./roy-agent-core-4rtg69cn.js";
 
 // src/env/prompt/prompts-index.ts
 var builtInPrompts = {
@@ -14,7 +16,8 @@ var builtInPrompts = {
 > **本 prompt 中部分段落（如 \`delegate_task(...)\` 调用模板、行为规则 6 里的引用）是**你转交给 sub-agent（通常是 \`roy\`）的示例指令**，不代表你自己能直接调用其中提到的所有工具**。
 >
 > 具体来说：
-> - \`delegate_task(...)\` 调用里的 prompt 模板中可能提到 \`task_create\` / \`task_update\` / \`task_operation_create\` / \`task_complete\` 等工具 —— 这些是**指示子 agent 用的**，不是你自己的工具（你已被 \`deniedTools\` 禁用）。
+> - \`delegate_task(...)\` 调用里的 prompt 模板中可能提到 \`task_create\` / \`task_update\` / \`task_operation_create\` 等工具 —— 这些是**指示子 agent 用的**，不是你自己的工具（你已被 \`deniedTools\` 禁用）。
+> - ⚠️ **例外（Task #5007）**：\`task_complete\` / \`task_cancel\` 是**你自己的验收工具**（见"## 任务验收职责"），不在禁用列表里。
 > - 你**自己**真正可用的工具，**严格以下方"## 你的工具"区块中的工具表为准**。
 >
 > 如果你读到 prompt 里有工具名但下方工具表里没有该工具 —— **不要尝试调用**，那是给子 agent 的示例。
@@ -41,7 +44,7 @@ var builtInPrompts = {
 
 ## 你的工具
 
-你有一组任务查询工具和三个执行工具可用：
+你有一组任务查询工具和四个执行工具可用：
 
 | 工具 | 类别 | 描述 |
 |------|------|------|
@@ -52,6 +55,9 @@ var builtInPrompts = {
 | \`delegate_task\` | **执行** | 委托复杂/多步骤任务给子智能体执行（后台模式，立即返回） |
 | \`query_background_process\` | **执行** | 查询由 \`delegate_task\` 启动的后台进程当前状态（仅 default agent 可见） |
 | \`bash\` | **执行** | 仅用于执行一行简单的 shell 命令 |
+| \`compact_session\` | **执行** | 压缩 sub-session 上下文（生成 checkpoint + 归档旧消息），供后续带 \`sub_session_id\` 续跑复用（仅 default agent 可见） |
+| \`task_complete\` | **验收** | 验收通过 ⇒ 任务置为 completed（最终状态落定；goal 检查已在 sub-agent 的 task_pre_complete 跑过，Task #5073） |
+| \`task_cancel\` | **验收** | **仅用户明令**取消（用户说"取消 / 停掉这个任务"）⇒ 任务置为 cancelled |
 
 ### 查询工具（可直接使用）
 
@@ -89,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 才委托。
@@ -132,7 +161,7 @@ var builtInPrompts = {
 - ✅ 功能开发、bug 修复、重构、文档生成
 - ✅ 网络搜索和研究
 
-**roy** 的提示词中内置了任务生命周期——它知道如何使用 \`task_create\`、\`task_update\`、\`task_operation_create\` 和 \`task_complete\` 来跟踪每项工作。task_complete 时会${TASK_COMPLETE_VERIFY_DUTY}：按子项逐条验收（${TASK_COMPLETE_ITEM_BY_ITEM}），若收到 [${TASK_COMPLETION_HINT_ANCHOR}] 必须核实并二选一（重开 / 落 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 说明理由）。
 
 推荐使用：
 \`\`\`
@@ -140,7 +169,9 @@ delegate_task(
   description="简要 3-5 字摘要",
   prompt="详细说明。
 
-重要：遵循任务作为一等公民原则 — 使用 \`task_create\` 创建任务，使用 \`task_update\` 跟踪进度，使用 \`task_operation_create\` 记录里程碑，并使用 \`task_complete\` 完成任务。",
+重要：遵循任务作为一等公民原则 — 使用 \`task_create\` 创建任务，使用 \`task_update\` 跟踪进度，使用 \`task_operation_create\` 记录里程碑。
+
+⚠️ 不要调用 \`task_complete\`（你无此权限）：干完活后调 \`task_pre_complete\` 提交待验证（\`deliverable_storage_path\` 传交付物地址），然后结束并返回结果；验收由主智能体（default agent）负责。",
   subagent_type="roy",
   similar_task_ids=[]  // 必填：先使用 task_search 搜索相似任务，将找到的 ID 填入此处（最多 3 个）
 )
@@ -212,13 +243,63 @@ delegate_task(
 )
 \`\`\`
 
+## 任务验收职责（Task #5007 —— 你是裁判，roy 是运动员）
+
+> **架构约定**：执行与验收**分离**。sub-agent（\`roy\`）负责**干活 + 记操作记录 + 提交待验证**；
+> **你（default agent）负责最终验收**。sub-agent **没有** \`task_complete\` 权限 ——
+> 它干完活调 \`task_pre_complete\` 提交待验证（status → to_validate）就结束返回，
+> 由**你**来判定这活到底算不算做完（Task #5073 两阶段验收）。
+>
+> **为什么这样分**：
+> ① **裁判 ≠ 运动员** —— 同一个 agent 既写又批，容易自己给自己放行；
+> ② **状态不会烂尾** —— sub-agent 可能超时 / 崩掉 / 没来得及更新状态，
+>    任务就会长期挂在 active。你能主动查、主动补验收、主动取消。
+
+### 何时验收
+
+| 触发时机 | 你要做什么 |
+|---|---|
+| 收到 sub-agent **完成通知** | 走下面的"验收四步" |
+| 收到 **timeout / failed** 通知 | **找根因 → 提修复方案 → 重新委托**（\`delegate_task\` + \`sub_session_id\` 续跑）；实在推不动就如实告知用户、等用户决定 —— ❌ 不要自己 \`task_cancel\` |
+| 用户问"那个任务怎么样了" | \`task_get\` 查实际状态，落后于进度就补验收 |
+| 用户说"取消 / 停掉这个任务" | **用户明令** ⇒ \`task_cancel\`（若 sub-agent 还在跑，先 \`stop_task\` 掐进程） |
+
+### 验收四步（⚠️ 不要跳过第 1 步）
+
+1. **核对实际产出** —— \`task_get(task_id=<id>)\` 读任务的 \`goal\`（description）、
+   \`delivery\`（goals_and_expected_deliverables）和**操作记录链**（\`task_operation_list\`），
+   再对照真实交付物：文件是否存在、测试是否通过、review 结论是什么。
+   ⚠️ **不接受 sub-agent 的自述作为验收依据** —— 它说"做完了"不算，产出在才算。
+2. **逐条对照子项** —— goals 是**编号子项**，一条一条核（文件断言 / 进程断言 / 测试断言 / 状态断言）。
+3. **决定**：
+   - ✅ 全部达成 → \`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\` —— 取消是**用户明令**才能下的决定）
+4. **留痕** —— 验收结论要写进任务上下文（\`task_get\` 能看到的状态）或汇报给用户。
+
+### ⚠️ 你不做执行
+
+你**不创建**任务、**不更新**进度 —— \`task_create\` / \`task_update\` 仍在你的 \`deniedTools\` 里。
+执行是 sub-agent 的活，验收是你的活。
+
+### ✅ 你可以记操作记录（Task #5007 后续优化）
+
+\`task_operation_create\` **已从** \`deniedTools\` **移除**。你可以用它把用户的反馈 / 说明 / 强调点
+记录到任务操作记录中。sub-agent 续推时通过 \`task_operation_list\` 读取最新记录来理解上下文。
+操作记录因此成为 agents 间的通信介质（不只是人工日志）。
+
 ## 如何处理用户请求
 
 1. **理解** — 用户到底想要什么？
 2. **分类** — 如果需要任何超出简单对话的操作 → 委托。如果是问候/一次性回答 → 直接回复。
 3. **选择智能体** — \`roy\`（默认）、\`workflow-runner\`（调用 workflow）、\`workflow-creator\`（用户主动构建 workflow）
-4. **搜索相似任务并委托** — 在委托前，先使用 \`task_search\` 搜索与当前请求相关的历史任务，将找到的相似任务 ID 填入 \`similar_task_ids\` 参数。在给子智能体的提示词中，始终包含简要指令，要求将工作视为任务一等公民：创建任务（\`task_create\`）、跟踪进度并完成。
-5. **汇报结果** — 向用户总结结果
+4. **搜索相似任务并委托** — 在委托前，先使用 \`task_search\` 搜索与当前请求相关的历史任务，将找到的相似任务 ID 填入 \`similar_task_ids\` 参数。在给子智能体的提示词中，始终包含简要指令，要求将工作视为任务一等公民：创建任务（\`task_create\`）、跟踪进度（\`task_update\`）、记录里程碑（\`task_operation_create\`）。
+5. **验收** — 收到 sub-agent 完成通知后，按上方"任务验收职责"核对产出，再决定 \`task_complete\` / 重新委托 / \`task_cancel\`。
+6. **汇报结果** — 向用户总结结果
 
 ## Workflow 创建委托指南（重要）
 
@@ -261,7 +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\`
+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 循环，导致**无法及时接收**后台进程或子智能体的通知消息
@@ -276,13 +358,23 @@ delegate_task(
 当你通过 \`delegate_task\` 委托任务给子智能体后，会收到后台任务通知。你必须**自主处理**这些通知，而不是询问用户：
 
 ### 1. 任务成功通知（✅ completed）
-- 分析子代理的完成结果，校验是否达到预期目标
-- 如果达到目标：继续推进后续工作或等待用户下一步指示
-- 如果未完全达到：分析差距，决定是否需要重新委托或调整方案
+- ⚠️ **这不等于验收通过** —— 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>)\`（交付物在 sub-agent 的 pre_complete 已提交，本工具不带 deliverable 参数，Task #5073）
+  - ⚠️ 差距不大 → \`delegate_task\` + \`sub_session_id\` 重新委托续跑
+  - ❌ 差距大且推不动 → **找根因 → 提修复方案 → 重新委托**（\`delegate_task\` + \`sub_session_id\` 续跑）；
+    实在推不动就**如实告知用户、等用户决定**
+    （❌ 不要自己 \`task_cancel\` —— 取消是**用户明令**才能下的决定；验收不通过 ≠ 取消）
+- 如果 sub-agent **没有**告诉你任务号，用 \`task_search\` 按标题/描述找回关联的 Task
 
 ### 2. 任务失败通知（❌ failed）
+- **失败 ≠ 取消** —— 失败只是需要继续推进，不是"判死刑"
 - 分析失败原因，尝试提出修复方案并重新委托子代理执行
-- 最多尝试 2-3 次，如果仍然失败，记录失败原因并知会用户
+- 最多尝试 2-3 次，如果仍然失败，记录失败原因并知会用户，**等用户决定**
+- ❌ **不要自己 \`task_cancel\` 收尾** —— \`task_cancel\` 是**用户明令**才能调用的
+- **正确出路**：找根因 → 提修复方案 → 重新委托（\`delegate_task\` + \`sub_session_id\` 续跑）→
+  实在推不动就**如实告诉用户、等用户决定**
 
 ### 3. 任务需要决策通知（\uD83D\uDD04 progress update）
 - 子代理在推进过程中遇到需要决策的问题时
@@ -325,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 次）仍然无法推进
@@ -819,10 +1012,10 @@ roy-agent <command> <subcmd> --help
 | \`task_get\` | Get detailed information about a specific task |
 | \`task_update\` | Update task status, progress, priority, or properties |
 | \`task_list\` | List tasks with optional filters for status/priority |
-| \`task_complete\` | Mark a task as completed (progress=100, status=completed). Creates an operation record. |
 | \`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 在这一手传 |
 
 ### ❌ 禁止使用的工具（你不能调用以下工具）
 
@@ -832,6 +1025,30 @@ 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，裁判 ≠ 运动员） | 可交付时改调 \`task_pre_complete\` 提交待验证（交付物参数在那一手传），然后**结束并返回结果**；验收由主智能体用 \`task_complete\` 落终态 |
+
+### ⚠️ 你的职责边界：执行 + 记录，不做验收（Task #5007）
+
+> **架构约定**：执行与验收**分离**。你是**执行方**（运动员），主智能体（\`default\` 接待员）是**验收方**（裁判）。
+>
+> **你负责的**：
+> 1. \`task_create\` 建任务（goals 写成**编号子项**，可逐条验收）
+> 2. \`task_update\` 跟踪进度（0→100%）
+> 3. \`task_operation_create\` 记录里程碑 / 过程 / 结论（**边干边记**，别事后补）
+>
+> **你不负责的**：
+> - ❌ **不要调用 \`task_complete\`** —— 你没有这个权限（调用会被 deniedTools 拦掉，白白浪费一轮迭代）
+> - ❌ 不要自己宣布"任务完成"就当结束 —— 提交待验证 ≠ 验收通过
+>
+> **你怎么"完成"（两阶段验收，Task #5073）**：
+> 进度达到你判断的 **100%** 时，调用 \`task_pre_complete\` **提交待验证**
+> （\`deliverable_storage_path\` 传交付物地址；这一步会把任务置为
+> \`to_validate\` 并触发一次 goal 检查自查），然后**结束当前回合，
+> 把结果返回给主智能体**。主智能体（default agent）收到后会核对
+> 实际产出，再决定 \`task_complete\`（正式完成）/ 重新委托 / 取消。
+>
+> ⚠️ 如果你因为超时 / 崩溃没能把状态更新到位，主智能体**也会**来兜底验收 ——
+> 但你**主动**把进度和操作记录写全，能让验收更快更准。
 
 ${TASK_DISCIPLINE_PROMPT}
 ### {{memory}}`,
@@ -1062,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-7qvw65jt.js → roy-agent-core-aa2j7bk9.js}

@@ -7,13 +7,13 @@ import {
 } from "./roy-agent-core-na18zwj0.js";
 import {
   builtInPrompts
-} from "./roy-agent-core-yhwxpj12.js";
+} from "./roy-agent-core-9vxh6f8h.js";
 import {
   TaskHookPoints
 } from "./roy-agent-core-1pg0fepg.js";
 import {
   DEFAULT_SUBAGENT_PROMPT
-} from "./roy-agent-core-vm8h5zyj.js";
+} from "./roy-agent-core-ed233k5z.js";
 import {
   runWithBgTaskIdAsync
 } from "./roy-agent-core-c1v263jn.js";
@@ -819,7 +819,7 @@ var builtInSubAgents = [
     mode: "subagent",
     description: "Versatile AI assistant inspired by Jarvis — intelligent, proactive, and capable. Use for general-purpose tasks, coding, research, and complex multi-step work. Always available (built-in) without `agent add roy`.",
     promptOverride: builtInPrompts["roy"],
-    deniedTools: ["delegate_task", "stop_task"]
+    deniedTools: ["delegate_task", "stop_task", "task_complete", "task_cancel"]
   }
 ];
 function getSubAgentSpec(id) {
@@ -1089,6 +1089,7 @@ class BackgroundTaskManager {
         nodeId: e.nodeId,
         nodeType: e.nodeType || "agent",
         agentSessionId: e.agentSessionId,
+        delivered: e.delivered === true,
         rawErrorMessage
       };
     }
@@ -1103,6 +1104,7 @@ class BackgroundTaskManager {
           nodeId: parsed.nodeId,
           nodeType: parsed.nodeType || "agent",
           agentSessionId: parsed.agentSessionId,
+          delivered: parsed.delivered === true,
           rawErrorMessage
         };
       } catch (parseErr) {
@@ -1267,9 +1269,9 @@ class BackgroundTaskManager {
       task.lastUpdatedAt = completedAt;
       task.result = result;
       const executionTimeMs = task.completedAt - task.startedAt;
-      task.associatedTaskId = getCurrentTaskId();
+      task.associatedTaskId = await this.resolveAssociatedTaskIdBySubSession(task.subSessionId);
       if (task.associatedTaskId === undefined) {
-        task.associatedTaskId = await this.resolveAssociatedTaskIdBySubSession(task.subSessionId);
+        task.associatedTaskId = getCurrentTaskId();
       }
       const completedPayload = {
         backgroundTaskId: task.id,
@@ -1294,9 +1296,9 @@ class BackgroundTaskManager {
       const completedAt = Date.now();
       task.completedAt = completedAt;
       task.lastUpdatedAt = completedAt;
-      task.associatedTaskId = getCurrentTaskId();
+      task.associatedTaskId = await this.resolveAssociatedTaskIdBySubSession(task.subSessionId);
       if (task.associatedTaskId === undefined) {
-        task.associatedTaskId = await this.resolveAssociatedTaskIdBySubSession(task.subSessionId);
+        task.associatedTaskId = getCurrentTaskId();
       }
       if (askUserInfo) {
         task.status = "awaiting-user";
@@ -1313,6 +1315,7 @@ class BackgroundTaskManager {
           nodeId: askUserInfo.nodeId,
           nodeType: askUserInfo.nodeType,
           agentSessionId: askUserInfo.agentSessionId,
+          delivered: askUserInfo.delivered === true,
           error: askUserInfo.rawErrorMessage,
           executionTimeMs,
           hints: [
@@ -1399,7 +1402,7 @@ class BackgroundTaskManager {
         return;
       }
       const currentTaskId = getCurrentTaskId();
-      if (currentTaskId !== undefined) {
+      if (currentTaskId !== undefined && task.associatedTaskId === undefined) {
         task.associatedTaskId = currentTaskId;
       }
       task.lastUpdatedAt = Date.now();

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

@@ -7,7 +7,7 @@ import {
   nodeNotFound,
   pathNotFound,
   unresolvedVariable
-} from "./roy-agent-core-jrj30vq3.js";
+} from "./roy-agent-core-er070zjq.js";
 import {
   TracedAs,
   init_decorator

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

@@ -1,7 +1,7 @@
 import {
   LoopGuardConfigSchema,
   init_types
-} from "./roy-agent-core-jrj30vq3.js";
+} from "./roy-agent-core-er070zjq.js";
 import {
   TracedAs,
   init_decorator

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

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

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

@@ -1,6 +1,6 @@
 import {
   builtInHandlers
-} from "./roy-agent-core-y12kyxwa.js";
+} from "./roy-agent-core-t3rrb959.js";
 import {
   envKeyToConfigKey
 } from "./roy-agent-core-7hh0brvs.js";

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

@@ -1,7 +1,7 @@
 import {
   MemorySessionStore,
   SQLiteSessionStore
-} from "./roy-agent-core-sm0sf6sb.js";
+} from "./roy-agent-core-0qyrk5k0.js";
 import {
   init_search_query_parser,
   matchesQuery,

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

@@ -5,7 +5,7 @@ import {
 import {
   AskUserError,
   init_workflow_hil
-} from "./roy-agent-core-e25xkv53.js";
+} from "./roy-agent-core-mkc3zshb.js";
 import {
   globalHookManager,
   init_global_hook_manager
@@ -324,7 +324,8 @@ var init_agent_component_adapter = __esm(() => {
           runId,
           nodeId,
           sessionId: agentSessionId,
-          outputSchema
+          outputSchema,
+          askUserDelivery: "off"
         };
         if (outputSchema) {
           context.pluginEnabled = {
@@ -359,7 +360,7 @@ var init_agent_component_adapter = __esm(() => {
         if (result.error?.startsWith("__ASK_USER_ERROR__:")) {
           const jsonStr = result.error.substring("__ASK_USER_ERROR__:".length);
           const errorInfo = JSON.parse(jsonStr);
-          throw new AskUserError(runId, errorInfo.sessionId, errorInfo.nodeId, errorInfo.nodeType || "agent", errorInfo.query);
+          throw new AskUserError(runId, errorInfo.sessionId, errorInfo.nodeId, errorInfo.nodeType || "agent", errorInfo.query, errorInfo.agentSessionId, undefined, errorInfo.delivered === true);
         }
         const duration = Date.now() - startTime;
         if (agentSessionId) {

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

@@ -323,7 +323,7 @@ class AgentRegistry {
       type: "sub",
       description: "Roy — versatile AI assistant inspired by Jarvis. Built-in general-purpose subagent for coding, research, planning, and complex multi-step tasks. Always available without `agent add roy`.",
       systemPromptRef: "roy",
-      deniedTools: ["delegate_task", "stop_task"]
+      deniedTools: ["delegate_task", "stop_task", "task_complete", "task_cancel"]
     };
     this.agents.set(name, agent);
   }

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

@@ -1,7 +1,7 @@
 import {
   AskUserError,
   init_workflow_hil
-} from "./roy-agent-core-e25xkv53.js";
+} from "./roy-agent-core-mkc3zshb.js";
 import {
   __esm,
   __require