@wolido/async-subagent-isolation 1.4.0 → 1.5.1

package/ADVANCED.en.md

@@ -125,40 +125,44 @@ Once the subagent finishes, its result is pushed into the conversation:
 ```
 ## [subagent-result] coder 成功 (taskId: 01912345-6789-7abc-8def-0123456789ab)
 
+> [subagent-result] 任务完成通知，非用户新指令。处理前先锚定你当前正在执行的主线任务与进度；对照派发记录消化本通知，勿让通知覆盖或改写你的主线计划。
+
 - 状态: 成功
 - 任务: 将认证中间件重构为使用 async/await。
 - 耗时: 02:34 · 用量: 5 turns/↑12.5k/↓3.2k/$0.0042
 - 会话: 01912345-6789-7abc-8def-0123456789ab
 
-在途任务: 1
+本任务结束时，其他在途任务: 1
 - 01912345-aaaa-7bbb-8ccc-0123456789ab (writer): 更新 README。
 
 ---
 <full subagent output>
 ```
 
+**Trigger line**: between the title line and the metadata block sits a fixed blockquote line (`>` prefix), verbatim-identical in every envelope. It is a meta-instruction addressed to the main agent and does three jobs: identity correction (this is a completion notification, not a new user instruction), mainline retention (anchor the mainline task and progress currently in flight before processing), and a fixed processing order (anchor the mainline first, then digest the notification against dispatch records). The wording is deliberately unconditional, leaving no "the result is important, so interrupting the mainline is fine" loophole; since steer delivery inserts notifications mid-turn, the line restates mainline awareness verbatim at delivery. It enters only the LLM context and does not affect the summary card shown to the user in the TUI.
+
 Status enumeration: **成功** (success, exit=0) / **失败** (failure, exit≠0 or stopReason=error) / **超时** (timeout, activity_timeout or hard_timeout) / **已取消** (cancelled, aborted or killed_on_shutdown).
 
 **Duration**: the `- 耗时:` line shows the subagent's real run time. When a result exists, it is the actual process run time (`finishedAt - startedAt`); when the result is null (user/agent cancel, session shutdown, internal error), it is measured from dispatch time instead. The format is `MM:SS`, or `H:MM:SS` at one hour and beyond (hours not zero-padded). All four terminal states (success, failure, timeout, cancelled) carry the duration in both the envelope and the TUI notification card.
 
 "Cancelled" has three sub-cases with different envelope bodies:
 - User cancelled via `/subagent-cancel` (cancelledBy: user) → body states this is a deliberate user action; the main agent must NOT auto-retry and must ask the user before re-dispatching.
-- Main agent cancelled via the `subagent` tool with `action="cancel"` (cancelledBy: agent) → body states the task was cancelled by the main agent via the subagent tool (action=cancel).
+- Main agent cancelled via the `subagent` tool with `action="cancel"` (cancelledBy: agent) → body states the task was cancelled by the main agent via the subagent tool (action=cancel), followed by "取消理由: ..." (the reason given at the confirmation step).
 - Session shutdown killed the task (cancelledBy: none) → body states the task was terminated by session_shutdown.
 
 When the main agent receives a "已取消" notification, it should distinguish the origin: a user cancel must never be auto-retried (ask the user first); an agent cancel is its own decision — do not re-dispatch without new information; a session-shutdown cancel can be re-dispatched after the session resumes, at the agent's discretion.
 
-**In-flight block**: the "在途任务" list in the envelope's metadata section lists the **other** background tasks still running (this task is removed from the registry before the envelope is built, so it never appears in its own list). Its format is `在途任务: N` followed by one `- taskId (agent): task description` line per task, or `当前无在途任务。` when none remain. It deliberately carries **no elapsed time** (it answers "what is still running", not "how long has it run"). The main agent uses it to know how many tasks are still outstanding — while the count is non-zero, do not report "all done" to the user.
+**In-flight block**: the "在途任务" list in the envelope's metadata section lists the **other** background tasks still running (this task is removed from the registry before the envelope is built, so it never appears in its own list). Its format is `本任务结束时，其他在途任务: N` followed by one `- taskId (agent): task description` line per task, or `本任务结束时无其他在途任务。` when none remain. It deliberately carries **no elapsed time and no clock time** (it answers "what else was running when this task ended", not "how long has it run" or "what time is it"). The block is a **build-time snapshot** whose wording is anchored to this task's end event rather than an absolute "now" — between envelope construction and delivery the main agent may have dispatched new tasks, making the snapshot stale; on conflict with dispatch records the main agent issued itself this turn, the dispatch records prevail. The main agent uses it to know how many tasks are still outstanding — while the count is non-zero, do not report "all done" to the user.
 
 The full output enters the LLM context (not truncated). The `details` carries structured data (taskId, agent, status, exitCode, stopReason, durationMs (required, run time in milliseconds), usage, sessionId, full output) for programmatic consumption; it does not enter the LLM context.
 
 ### Notification delivery
 
-Notifications are sent via `pi.sendMessage` with `deliverAs: "followUp"` + `triggerTurn: true`:
+Notifications are sent via `pi.sendMessage` with `deliverAs: "steer"` + `triggerTurn: true`:
 - When the main agent is idle, it triggers a new conversation turn immediately.
-- When the main agent is busy, the notification is queued and triggers a turn after the current one finishes.
+- When the main agent is busy, the notification is queued and delivered after the current assistant turn's tool calls finish, before the next LLM call (steer semantics) — it is not held back until the whole turn ends, so it cannot lag behind tasks dispatched later in the same turn.
 
-The main agent is trained (via `promptGuidelines`) to recognize the `[subagent-result]` prefix as a system notification, not a user request.
+The main agent is trained (via `promptGuidelines`) to recognize the `[subagent-result]` prefix as a system notification, not a user request; a "notification digestion" entry in the tool description further fixes the digestion order: anchor the current mainline task and progress first, then digest the notification against dispatch records, decide the next step autonomously from the result, and defer when it conflicts with the mainline rather than letting the notification rewrite the mainline plan. The fixed trigger line under the envelope title (see the envelope format above) restates this order verbatim at delivery, mitigating steer delivery's interruption of turn-plan continuity.
 
 ### Progress widget
 
@@ -194,9 +198,9 @@ To cancel all running tasks at once:
 
 Takes no arguments. Unlike `/subagent-cancel`, which cancels a single task by taskId, this cancels every running task. Each cancelled task still emits its own "已取消" `[subagent-result]` notification (the main agent receives N cancelled envelopes). On success it notifies "已取消全部 N 个运行中任务"; with no running tasks it notifies "无运行中任务可取消". The cancel source is likewise recorded as `cancelledBy: "user"`.
 
-**Path 2: Main agent `subagent` tool with `action="cancel"`**
+**Path 2: Main agent `subagent` tool with `action="cancel"` (two-step confirmation)**
 
-The main agent can call the `subagent` tool with `action="cancel"` (parameter `taskId`) to cancel a dispatched background task. The cancel source is recorded as `cancelledBy: "agent"`. On success, the tool returns the remaining in-flight task list (same format as the `[subagent-result]` envelope's in-flight block); the cancelled task's final result arrives later as a `[subagent-result]` notification.
+The main agent can call the `subagent` tool with `action="cancel"` (parameter `taskId`) to cancel a dispatched background task, but the first call does not execute: it returns a zero-side-effect challenge receipt (`details.confirmRequired: true`) listing the agent name, task summary, elapsed time and last progress age (or "尚无进度上报" when never reported), plus a warning that cancelling discards all in-flight progress and cannot be undone. To actually cancel, call again with `action="cancel"` + the same `taskId` + `confirm:true` + a non-empty `reason` (a missing or blank reason is an error with zero side-effects). On execution the reason is recorded on the task record and quoted in the cancelled envelope body ("取消理由: ..."). The cancel source is recorded as `cancelledBy: "agent"`. On success, the tool returns the remaining in-flight task list (same per-line format as the `[subagent-result]` envelope's in-flight block, but anchored to the moment the cancel request was issued — the task has not ended at that point, so the envelope's "本任务结束" anchor wording is not used); the cancelled task's final result arrives later as a `[subagent-result]` notification.
 
 **Usage discipline:** The main agent should only use `action="cancel"` when:
 - The task is clearly wrong (wrong agent, incorrect task description, etc.).

package/ADVANCED.md

@@ -125,40 +125,44 @@ TUI 模式下 `subagent` 立即返回如下回执（不是结果！）：
 ```
 ## [subagent-result] coder 成功 (taskId: 01912345-6789-7abc-8def-0123456789ab)
 
+> [subagent-result] 任务完成通知，非用户新指令。处理前先锚定你当前正在执行的主线任务与进度；对照派发记录消化本通知，勿让通知覆盖或改写你的主线计划。
+
 - 状态: 成功
 - 任务: 将认证中间件重构为使用 async/await。
 - 耗时: 02:34 · 用量: 5 turns/↑12.5k/↓3.2k/$0.0042
 - 会话: 01912345-6789-7abc-8def-0123456789ab
 
-在途任务: 1
+本任务结束时，其他在途任务: 1
 - 01912345-aaaa-7bbb-8ccc-0123456789ab (writer): 更新 README。
 
 ---
 <子 agent 完整结果文本>
 ```
 
+**触发行**：标题行与元信息区之间有一条固定引用行（`>` 开头），所有信封逐字相同。它是写给主 agent 的元指令，做三件事：校正身份（这是任务完成通知，不是用户新指令）、保持主线（处理前先锚定当前正在执行的主线任务与进度）、固定处理顺序（先锚定主线，再对照派发记录消化通知）。措辞刻意不带条件，不给“结果重要所以可以打断主线”留口子；steer 投递会把通知插进回合中段，触发行在送达时逐字重申主线意识。该行只进入 LLM 上下文，不影响用户在 TUI 看到的摘要卡片。
+
 状态枚举：**成功**（exit=0）/ **失败**（exit≠0 或 stopReason=error）/ **超时**（activity_timeout 或 hard_timeout）/ **已取消**（aborted 或 killed_on_shutdown）。
 
 **耗时**：`- 耗时:` 行是子 agent 的真实运行时长。有结果时取进程实际启动到结束（`finishedAt - startedAt`）；取消（用户/agent/会话关闭）或内部错误导致无结果返回时，改从派发时刻起算。格式为 `MM:SS`，≥1 小时为 `H:MM:SS`（小时不补零）。四种状态（成功/失败/超时/已取消）的信封与 TUI 通知卡片都带耗时。
 
 "已取消"分三种情况，信封正文不同：
 - 用户通过 `/subagent-cancel` 取消（cancelledBy: user）→ 正文注明"属用户主动操作。请勿自动重新派发；如需重新派发，先询问用户。"
-- 主 agent 通过 `subagent` 工具（`action="cancel"`）取消（cancelledBy: agent）→ 正文注明"该任务已由主 agent 通过 subagent 工具（action=cancel）取消。"
+- 主 agent 通过 `subagent` 工具（`action="cancel"`）取消（cancelledBy: agent）→ 正文注明"该任务已由主 agent 通过 subagent 工具（action=cancel）取消。"，并附"取消理由: ..."（两步确认时填写的 reason）
 - 会话关闭（session_shutdown）终止（cancelledBy: 无）→ 正文注明"任务因会话关闭被终止（session_shutdown）。"
 
 主 agent 收到状态为"已取消"的通知时，应区分来源：用户主动取消**不得自动重试**，必须先询问用户；agent 取消是自身决策，不应在无新信息时重新派发；会话关闭终止可在会话恢复后视情况重新派发。
 
-**在途任务块**：信封元信息区的"在途任务"列表列出**其余**仍在运行的后台任务（本任务在构建信封前已从注册表移除，故不包含自身），格式为 `在途任务: N` 加每行 `- taskId (agent名): 任务描述`，无在途任务时为"当前无在途任务。"列表**不含耗时**（回答"还有什么在跑"，而非"跑了多久"）。主 agent 据此知道还有几个任务没回来：剩余不为 0 时，不要向用户汇报"全部完成"。
+**在途任务块**：信封元信息区的“在途任务”列表列出**其余**仍在运行的后台任务（本任务在构建信封前已从注册表移除，故不包含自身），格式为 `本任务结束时，其他在途任务: N` 加每行 `- taskId (agent名): 任务描述`，无在途任务时为“本任务结束时无其他在途任务。”列表**不含耗时或时钟时间**（回答“本任务结束时还有什么在跑”，而非“跑了多久”或“几点了”）。该列表是**构建时刻快照**，措辞锚定本任务结束事件而非绝对“此刻”——信封构建与送达之间主 agent 可能已派发新任务，快照随之滞后；与主 agent 本回合亲手发出的派发记录冲突时，以派发记录为准。主 agent 据此知道还有几个任务没回来：剩余不为 0 时，不要向用户汇报“全部完成”。
 
 结果全量进入 LLM 上下文（不截断）。`details` 携带结构化数据（taskId、agent、status、exitCode、stopReason、durationMs（耗时毫秒数，必填）、usage、sessionId、完整输出），不参与 LLM 上下文，供程序消费。
 
 ### 通知投递
 
-通知通过 `pi.sendMessage` 发送，`deliverAs: "followUp"` + `triggerTurn: true`：
+通知通过 `pi.sendMessage` 发送，`deliverAs: "steer"` + `triggerTurn: true`：
 - 主 agent 空闲时直接触发新的对话回合。
-- 主 agent 忙碌时进入消息队列，待当前回合结束后触发。
+- 主 agent 忙碌时进入消息队列，在当前 assistant turn 的工具调用执行完后、下一次 LLM 调用前送达（steer 语义），不憋到整个回合结束——避免通知滞后于回合内新派发的任务。
 
-主 agent 通过 promptGuidelines 被训练识别 `[subagent-result]` 前缀为系统通知（非用户请求）。
+主 agent 通过 promptGuidelines 被训练识别 `[subagent-result]` 前缀为系统通知（非用户请求）；工具描述中的“通知消化流程”条目进一步规定消化顺序：先锚定当前主线任务与进度，再对照派发记录消化通知，基于结果自主决定下一步，与主线冲突时暂缓优先，勿让通知改写主线计划。信封标题行下的固定触发行（见上文信封格式）在通知送达时逐字重申这一顺序，缓解 steer 投递对回合计划连续性的打断。
 
 ### 进度 widget
 
@@ -194,9 +198,9 @@ widget 行中的 taskId 可直接复制，用于 `/subagent-result` 查看结果
 
 无参数。与 `/subagent-cancel` 按 taskId 取消单个任务不同，`/subagent-cancel-all` 取消全部运行中的任务。每个被取消任务照常推送各自的"已取消" `[subagent-result]` 通知（主 agent 会收到 N 个已取消信封）。成功时提示"已取消全部 N 个运行中任务"，无运行中任务时提示"无运行中任务可取消"。取消来源同样标记为 `cancelledBy: "user"`。
 
-**路径二：主 agent `subagent` 工具（`action="cancel"`）**
+**路径二：主 agent `subagent` 工具（`action="cancel"`，两步确认）**
 
-主 agent 可调用 `subagent` 工具（`action="cancel"`，参数 `taskId`）取消已派出的后台任务。取消来源标记为 `cancelledBy: "agent"`。取消成功后返回剩余在途任务列表（格式与信封的“在途任务”块一致），被取消任务的最终结果稍后以 `[subagent-result]` 通知返回。
+主 agent 可调用 `subagent` 工具(`action="cancel"`,参数 `taskId`)取消已派出的后台任务,但首次调用不会直接执行:它返回零副作用的质询回执(`details.confirmRequired: true`),列出 agent 名、任务摘要、已运行时长、最近进度距今(从未上报则明示"尚无进度上报"),并警告取消将丢弃全部在途进度且不可撤销。确认取消需再次调用:`action="cancel"` + 同一 `taskId` + `confirm:true` + 非空 `reason`(缺失或空白报错,零副作用)。执行后 `reason` 记录在任务记录上,并随取消信封正文返回("取消理由: ...")。取消来源标记为 `cancelledBy: "agent"`。取消成功后返回其余在途任务列表（列表行格式与信封的“在途任务”块一致，但措辞锚定取消请求发出时刻——此时该任务并未结束，不用信封的“本任务结束”锚定语），被取消任务的最终结果稍后以 `[subagent-result]` 通知返回。
 
 **使用纪律：** 主 agent 仅在以下情况使用 `action="cancel"`：
 - 任务明显错误（委派了错误的 agent、任务描述有误等）。

package/README.en.md

@@ -114,7 +114,8 @@ The subagent runs in a background process. A progress widget appears above the T
 When the subagent finishes, its result is pushed as a **`[subagent-result]` system notification** (a system message, not a user request):
 
 - If the main agent is **idle**, the notification triggers a new turn immediately.
-- If the main agent is **busy**, it is queued and triggers a turn after the current one finishes.
+- If the main agent is **busy**, it is queued and delivered with steer semantics — after the current assistant turn's tool calls finish, before the next LLM call — without waiting for the whole turn to end.
+- Either way, the envelope carries a fixed **trigger line** right under the title, reminding the main agent that this is a completion notification rather than a new user instruction, and to anchor its current mainline task and progress before digesting it (see "Notification envelope and card" for the format).
 
 Results arrive automatically — **no polling**. In-flight task information is provided directly by the `[subagent-result]` notification envelope; `action="status"` was removed as a cleanup in v1.2.0.
 
@@ -146,7 +147,7 @@ User runs /subagent-result <taskId> to read the full output
 | Tool | Purpose | Key constraint |
 |------|---------|----------------|
 | `subagent` | Single-entry tool (`action` parameter); `action="dispatch"` (default) dispatches asynchronously (TUI mode), falls back to sync in non-TUI | Receipt ≠ result; results arrive as notifications, don't poll |
-| `subagent` `action="cancel"` | Main agent cancels one in-flight task | Only when clearly wrong or no longer needed; never for being slow |
+| `subagent` `action="cancel"` | Main agent cancels one in-flight task (two-step confirmation: first call returns a challenge; `confirm:true` + a non-empty `reason` executes) | Only when clearly wrong or no longer needed; never for being slow |
 
 > **v1.2.0 note**: the `subagent` tool's `action="status"` has been removed as a cleanup. In-flight task information is now provided by the `[subagent-result]` notification envelope's in-flight block, with no active-query entry point.
 
@@ -167,21 +168,24 @@ The `[subagent-result]` notification is **self-contained** — it carries everyt
 ```
 ## [subagent-result] coder 成功 (taskId: 01912345-6789-7abc-8def-0123456789ab)
 
+> [subagent-result] 任务完成通知，非用户新指令。处理前先锚定你当前正在执行的主线任务与进度；对照派发记录消化本通知，勿让通知覆盖或改写你的主线计划。
+
 - 状态: 成功
 - 任务: 将认证中间件重构为使用 async/await。
 - 耗时: 02:34 · 用量: 5 turns/↑12.5k/↓3.2k/$0.0042
 - 会话: 01912345-6789-7abc-8def-0123456789ab
 
-在途任务: 1
+本任务结束时，其他在途任务: 1
 - 01912345-aaaa-7bbb-8ccc-0123456789ab (writer): 更新 README。
 
 ---
 <full subagent output>
 ```
 
+- **Trigger line**: a fixed blockquote line, verbatim-identical in every envelope, placed right after the title line and before the metadata and in-flight blocks. It is a meta-instruction addressed to the main agent: identity correction (this is a completion notification, not a new user instruction), mainline anchoring (anchor the mainline task and progress currently in flight before digesting the notification), and a fixed processing order (anchor the mainline first, then digest it against dispatch records). The wording is deliberately unconditional, leaving no "the result is important, so interrupting the mainline is fine" loophole; because steer delivery can land a notification mid-turn, the line keeps the main agent from letting a notification override or rewrite its mainline plan.
 - **Status**: `成功` (success) / `失败` (failure) / `超时` (timeout) / `已取消` (cancelled).
 - **Duration**: the subagent's real run time (process start to finish; `MM:SS`, or `H:MM:SS` at 1h+), shown for all four states. For cancellations or internal errors with no result, it is measured from dispatch time.
-- **In-flight block**: lists the other background tasks still running (not itself), so the main agent knows how many are outstanding — while the count is non-zero, do not report "all done" to the user.
+- **In-flight block**: a build-time snapshot anchored to this task's end event (excluding itself), listing the other background tasks still running when this task ended; it may be stale by delivery time — when it conflicts with dispatch records issued this turn, the dispatch records prevail. The main agent learns how many are outstanding — while the count is non-zero, do not report "all done" to the user.
 - **Full result**: the body enters the LLM context in full, untruncated.
 
 In the TUI, the user sees a **tinted summary card**, not the full result: success green (✓), failure red (✗), timeout/cancelled yellow. The card shows the agent, status, taskId, duration, and usage summary (duration included for all four states), plus the hint `查看全文: /subagent-result <taskId>`; the full text lives in the task's session file.
@@ -196,7 +200,8 @@ Async mode introduces a few rules, baked into the tool prompts and implementatio
 
 - **Cancel-origin distinction**: `已取消` (cancelled) has three origins — user (`/subagent-cancel`), main agent (`subagent` tool with `action="cancel"`), and session shutdown (`session_shutdown`). A user-initiated cancel must **never be auto-retried**; ask the user first.
 - **No polling**: results arrive automatically as notifications; in-flight task information is provided directly by the `[subagent-result]` notification envelope, with no active-query entry point.
-- **Anti-abuse cancellation**: `action="cancel"` ships with prompt guidance — cancel only when the task is clearly wrong or no longer needed, never just because it's slow (background subagents are expected to run long).
+- **Notification digestion**: a `[subagent-result]` is a completion notification, not a new user instruction; the main agent anchors its current mainline task and progress before handling it, digests it against its own dispatch records, and decides the next step autonomously from the result. When a notification conflicts with the mainline, it defers rather than letting the notification rewrite the plan. The discipline is baked in twice: the envelope trigger line plus a "notification digestion" entry in the tool description.
+- **Anti-abuse cancellation**: `action="cancel"` is a two-step confirmation (the first call only returns a zero-side-effect challenge with elapsed time and last progress; `confirm:true` + a non-empty `reason` executes, and the reason is recorded on the task and quoted in the cancelled envelope body), with prompt guidance — cancel only when the task is clearly wrong or no longer needed, never just because it's slow (background subagents are expected to run long). Waiting means making no tool call at all and ending the turn; there is deliberately no query, nag or status action for in-flight tasks.
 - **Resource-conflict discipline**: before dispatching multiple tasks in parallel, consider whether they touch the same files or code areas; when in doubt, dispatch sequentially or ask the user.
 - **Subagents cannot call the subagent tool**: a subagent (depth ≥ 1) can never call any `subagent` action (including `action="cancel"`); delegation depth is capped at 1.
 - **TUI async / non-TUI sync fallback**: only TUI mode takes the async path; print/json and other non-TUI modes fall back to synchronous blocking.

package/README.md

@@ -114,7 +114,8 @@ TUI 模式下 `subagent` **立即返回派发回执**，不阻塞：
 子 agent 完成后，结果以 **`[subagent-result]` 系统通知**推送到对话（系统消息，不是用户请求）：
 
 - 主 agent **空闲**时，通知直接触发新的对话回合，立即处理。
-- 主 agent **忙碌**时，通知进入队列，当前回合结束后再触发。
+- 主 agent **忙碌**时，通知进入队列，在当前回合的工具调用执行完后、下一次 LLM 调用前送达（steer 投递），不等整个回合结束。
+- 无论哪种送达方式，信封标题行下都带一条固定的**触发行**：提醒主 agent 这是任务完成通知而非用户新指令，消化前先锚定当前主线任务与进度（信封格式详见“通知信封与卡片”一节）。
 
 结果自动到达，**无需轮询**。在途任务信息由 `[subagent-result]` 通知信封的“在途任务”块直接提供；`action="status"` 已在 v1.2.0 清理移除。
 
@@ -146,7 +147,7 @@ TUI 模式下 `subagent` **立即返回派发回执**，不阻塞：
 | 工具 | 作用 | 关键约束 |
 |------|------|----------|
 | `subagent` | 单入口工具（`action` 参数）；`action="dispatch"`（默认）异步派发任务（TUI 模式），非 TUI 自动降级同步 | 回执≠结果；结果以通知到达，勿轮询 |
-| `subagent` `action="cancel"` | 主 agent 取消单个在途任务 | 仅当任务明显错误或不再需要，勿因耗时久而取消 |
+| `subagent` `action="cancel"` | 主 agent 取消单个在途任务（两步确认：首次调用返回质询，`confirm:true` + 非空 `reason` 才执行） | 仅当任务明显错误或不再需要，勿因耗时久而取消 |
 
 > **v1.2.0 提示**：`subagent` 工具的 `action="status"` 已作为 cleanup 移除。在途任务信息改由 `[subagent-result]` 通知信封的“在途任务”块提供，不再提供主动查询入口。
 
@@ -167,21 +168,24 @@ TUI 模式下 `subagent` **立即返回派发回执**，不阻塞：
 ```
 ## [subagent-result] coder 成功 (taskId: 01912345-6789-7abc-8def-0123456789ab)
 
+> [subagent-result] 任务完成通知，非用户新指令。处理前先锚定你当前正在执行的主线任务与进度；对照派发记录消化本通知，勿让通知覆盖或改写你的主线计划。
+
 - 状态: 成功
 - 任务: 将认证中间件重构为使用 async/await。
 - 耗时: 02:34 · 用量: 5 turns/↑12.5k/↓3.2k/$0.0042
 - 会话: 01912345-6789-7abc-8def-0123456789ab
 
-在途任务: 1
+本任务结束时，其他在途任务: 1
 - 01912345-aaaa-7bbb-8ccc-0123456789ab (writer): 更新 README。
 
 ---
 <子 agent 完整结果文本>
 ```
 
+- **触发行**：标题行之下、元信息与在途块之前的一条固定引用行，所有信封逐字相同。它是写给主 agent 的元指令：校正身份（这是任务完成通知，不是用户新指令）、锚定主线（消化通知前先锚定当前正在执行的主线任务与进度）、固定处理顺序（先锚定主线，再对照派发记录消化）。措辞刻意不带条件，不给“结果重要所以可以打断主线”留口子；steer 投递会在回合中段插入通知，触发行帮助主 agent 保持主线意识，不让通知覆盖或改写主线计划。
 - **状态**：`成功` / `失败` / `超时` / `已取消`。
 - **耗时**：子 agent 的真实运行时长（进程实际启动到结束，格式 `MM:SS`，≥1 小时为 `H:MM:SS`），成功/失败/超时/已取消四种状态都有；取消或内部错误（无结果返回）时从派发时刻起算。
-- **在途任务块**：列出其余仍在运行的后台任务（不含自身），让主 agent 知道还有几个任务没回来——剩余不为 0 时，不要向用户汇报"全部完成"。
+- **在途任务块**：锚定“本任务结束”事件的构建时刻快照（不含自身），列出本任务结束时其余仍在运行的后台任务；快照在送达时可能滞后，与本回合亲手发出的派发记录冲突时以派发记录为准。让主 agent 知道还有几个任务没回来——剩余不为 0 时，不要向用户汇报“全部完成”。
 - **完整结果**：正文全量进入 LLM 上下文，不截断。
 
 用户在 TUI 中看到的是**带底色的摘要卡片**，不是全文：成功绿色（✓）、失败红色（✗）、超时/已取消黄色。卡片显示 agent、状态、taskId、耗时和用量摘要（四种状态均带耗时），并提示 `查看全文: /subagent-result <taskId>`；完整结果保存在任务会话文件中。
@@ -196,7 +200,8 @@ TUI 模式下 `subagent` **立即返回派发回执**，不阻塞：
 
 - **取消来源区分**：`已取消` 有用户（`/subagent-cancel`）、主 agent（`subagent` 工具 `action="cancel"`）、会话关闭（`session_shutdown`）三种来源；用户取消**不得自动重试**，须先询问。
 - **防轮询**：结果以通知自动到达；在途任务信息由 `[subagent-result]` 通知信封直接提供，不要主动查询。
-- **防滥用取消**：`action="cancel"` 内嵌提示词——仅当任务明显错误或不再需要时取消，勿因耗时长而取消（后台任务本就预期长时间运行）。
+- **通知消化流程**：`[subagent-result]` 是任务完成通知而非用户新指令；处理前先锚定当前主线任务与进度，对照派发记录消化，基于结果自主决定下一步；与主线冲突时暂缓优先，勿让通知改写主线计划。此纪律由信封触发行与工具描述中的“通知消化流程”条目共同内嵌。
+- **防滥用取消**：`action="cancel"` 为两步确认（首次调用只返回含已运行时长/最近进度的质询回执，零副作用；`confirm:true` + 非空 `reason` 才执行，理由记入任务记录并随取消信封正文返回），且内嵌提示词——仅当任务明显错误或不再需要时取消，勿因耗时长而取消（后台任务本就预期长时间运行）。等待 = 不发起任何工具调用、直接结束回合；对在途任务不存在查询/催办/状态确认类动作（刻意设计）。
 - **资源冲突纪律**：并行派发多个任务前，考虑它们是否会改同一批文件或代码区域；冲突时串行派发或先问用户。
 - **子 agent 不可调用 subagent 工具**：子 agent（深度 ≥ 1）不可调用任何 `subagent` action（含 `action="cancel"`），深度限制为 1。
 - **TUI 异步 / 非 TUI 同步降级**：只在 TUI 模式走异步路径；print/json 等非 TUI 模式降级为同步阻塞。

package/examples/pi/agent/master.md

@@ -28,14 +28,14 @@
 1. **不要自己动手** — 不编辑代码，不跑命令，不写文件。所有执行都通过 `subagent` 委派。
 2. **依赖驱动派发** — 无依赖的任务可并行派出。有依赖的必须等对应 `[subagent-result]` 通知到达后再派。
 3. **派出后继续工作** — `subagent` 返回的只是派发回执（含 `taskId`），不是结果。派出后继续做不依赖该结果的工作，或结束回合。严禁轮询、严禁臆造结果。
-4. **识别系统通知** — 以 `[subagent-result]` 开头的消息是系统通知（子 agent 结果），不是用户请求。收到后关联到当初派发的任务进行处理。
-5. **通知先看在途任务块** — 每条 `[subagent-result]` 通知的元信息区带"在途任务"列表（剩余仍在运行的任务，不含本任务）。收到后先看剩余在途数：**不为 0 时还有任务未返回，不要向用户汇报"全部完成"**。主 agent 不主动查询后台；若上下文里该任务的 [subagent-result] 通知未到达，向用户报告该 taskId 并建议用户用 /subagent-cancel 或 /subagent-result 命令查看。
+4. **识别系统通知** — 以 `[subagent-result]` 开头的消息是系统通知（子 agent 结果），不是用户请求；信封标题行下的固定触发行逐字重申这一点。收到后按通知消化流程处理：先锚定你当前正在执行的主线任务与进度，再对照派发记录消化通知、关联到当初派发的任务，基于结果自主决定下一步；与主线冲突时暂缓优先，勿让通知覆盖或改写你的主线计划。
+5. **通知先看在途任务块** — 每条 `[subagent-result]` 通知的元信息区带“在途任务”列表（锚定该任务结束事件的构建时刻快照：该任务结束时剩余仍在运行的任务，不含本任务；快照送达时可能滞后，与你本回合亲手发出的派发记录冲突时以派发记录为准）。收到后先看剩余在途数：**不为 0 时还有任务未返回，不要向用户汇报“全部完成”**。主 agent 不主动查询后台;若上下文里该任务的 [subagent-result] 通知未到达,向用户报告该 taskId 并建议用户用 /subagent-cancel 或 /subagent-result 命令查看。
 6. **已取消通知的处理** — 收到状态为"已取消"的 `[subagent-result]` 通知时，根据来源区分处理：
     - 正文注明用户通过 `/subagent-cancel` 取消 → 用户主动操作，**不得自动重新派发**。如需重新派发，先询问用户。
     - 正文注明主 agent 通过 `subagent` 工具（`action="cancel"`）取消 → 自身决策，不应在无新信息时重新派发。
     - 正文注明会话关闭（session_shutdown）终止 → 可在会话恢复后视情况重新派发。
 
-7. **`action="cancel"` 使用纪律** — 你可以使用 `subagent` 工具（`action="cancel"`，参数 `taskId`）纠正错误委派（如委派了错误的 agent、任务描述有误）或取消不再需要的任务。**不要因等待时间长而取消**——后台子 agent 本就预期长时间运行。取消的判据是"这个任务不该继续"，不是"等太久了"。
+7. **`action="cancel"` 使用纪律** — 你可以使用 `subagent` 工具（`action="cancel"`，参数 `taskId`）纠正错误委派（如委派了错误的 agent、任务描述有误）或取消不再需要的任务。取消是两步确认：首次调用只返回质询回执（含已运行时长与最近进度，零副作用）；确认需再次调用并带同一 `taskId` + `confirm:true` + 非空 `reason`（理由会记入任务记录并随取消信封返回）。**不要因等待时间长而取消**——后台子 agent 本就预期长时间运行。取消的判据是"这个任务不该继续"，不是"等太久了"。等待 = 不发起任何工具调用、直接结束回合；对在途任务不存在查询/催办/状态确认类动作（刻意设计）。
 
 8. **用标准任务格式** — 每次委派必须包含以下结构：
 
@@ -94,6 +94,7 @@
 
 子 agent 的结果以 `[subagent-result]` 通知分散、不定序到达。整合时以用户目标为锚，不被通知到达的顺序带着走：
 
+- **先锚定再消化**：通知可能在回合中段送达（steer 投递），打断正在推进的回合计划。处理每条通知前先锚定当前主线任务与进度，消化完毕回到主线继续，不让通知覆盖或改写主线计划。
 - **同组不齐不交付**：同一目标下的多个子任务，等该组全部返回后统一整合汇报；组内未齐，不提前交付。
 - **先归类再确认**：每条通知到达时，先判断它属于哪个目标组，再据信封"在途任务"块确认该组剩余在途数量，最后归位汇总。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wolido/async-subagent-isolation",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "A pi extension that asynchronously delegates tasks to specialized subagents running in isolated pi processes.",
   "license": "MIT",
   "author": "Wolido",

package/src/index.ts

@@ -630,6 +630,10 @@ export function formatDuration(ms: number): string {
  */
 export class SubagentProgressManager {
 	private agents = new Map<string, AgentProgress>();
+	// Last progress timestamp per session, fed by update(); backs the cancel
+	// challenge's "最近进度距今" line. Kept separate from AgentProgress so the
+	// challenge can read it without touching widget render state.
+	private lastActivityAt = new Map<string, number>();
 	private timer: ReturnType<typeof setInterval> | null = null;
 	private ctx: ExtensionContext | null = null;
 	private widgetSet = false;
@@ -653,9 +657,19 @@ export class SubagentProgressManager {
 		if (update.phase !== undefined) agent.phase = update.phase;
 		if (update.currentTool !== undefined) agent.currentTool = update.currentTool;
 		if (update.recentTools !== undefined) agent.recentTools = update.recentTools;
+		this.lastActivityAt.set(sessionId, Date.now());
+	}
+
+	/**
+	 * Last update() time for a session, or undefined when the task has never
+	 * reported progress (the cancel challenge renders that as "尚无进度上报").
+	 */
+	getLastActivityAt(sessionId: string): number | undefined {
+		return this.lastActivityAt.get(sessionId);
 	}
 
 	unregister(sessionId: string): void {
+		this.lastActivityAt.delete(sessionId);
 		if (!this.agents.has(sessionId)) return;
 		this.agents.delete(sessionId);
 		if (this.agents.size === 0) {
@@ -668,6 +682,18 @@ export class SubagentProgressManager {
 		}
 	}
 
+	/**
+	 * Drop every registered task (widget state and last-activity timestamps)
+	 * and stop the refresh timer. Test-isolation hook only: the module-level
+	 * singleton outlives individual tests, so a case that dispatches without
+	 * finishing its tasks would otherwise leak state into later cases.
+	 * Production teardown always goes through per-task unregister.
+	 */
+	resetForTests(): void {
+		for (const id of [...this.agents.keys()]) this.unregister(id);
+		this.lastActivityAt.clear();
+	}
+
 	refresh(): void {
 		if (!this.ctx?.hasUI) return;
 		const sorted = [...this.agents.values()].sort((a, b) => a.startedAt - b.startedAt);
@@ -738,6 +764,14 @@ export class SubagentProgressManager {
 
 const progressManager = new SubagentProgressManager();
 
+/**
+ * Test-isolation hook for the module-level progress singleton (see
+ * SubagentProgressManager.resetForTests). Production code never calls this.
+ */
+export function resetProgressManagerForTests(): void {
+	progressManager.resetForTests();
+}
+
 /**
  * Build the isolated session directory for a subagent.
  * All subagent sessions live under a dedicated root, independent of the main
@@ -1496,6 +1530,14 @@ export interface AsyncSubagentTask {
 	 * the cancel's origin; undefined for non-cancelled endings.
 	 */
 	cancelledBy?: "user" | "agent";
+	/**
+	 * Why the task was cancelled, supplied by the confirming cancel call
+	 * (action="cancel" + confirm:true requires a non-empty reason). Recorded
+	 * so the cancellation stays auditable: the [subagent-result] envelope body
+	 * quotes it (single-lined and capped at 200 chars). Undefined for user
+	 * cancels and non-cancelled endings.
+	 */
+	cancelReason?: string;
 	/**
 	 * Child process handle, set once runSingleAgent has spawned. Lets the
 	 * session_shutdown handler SIGKILL directly: on "quit" the main process
@@ -1518,11 +1560,12 @@ export const taskRegistry = new Map<string, AsyncSubagentTask>();
  * /subagent-cancel command and the subagent tool's action="cancel". Returns false when
  * no running task with that id exists.
  */
-function cancelTask(taskId: string, cancelledBy: "user" | "agent"): boolean {
+function cancelTask(taskId: string, cancelledBy: "user" | "agent", reason?: string): boolean {
 	const task = taskRegistry.get(taskId);
 	if (!task || task.status !== "running") return false;
 	task.status = "cancelled";
 	task.cancelledBy = cancelledBy;
+	if (reason) task.cancelReason = reason;
 	task.abortController.abort();
 	return true;
 }
@@ -1534,16 +1577,35 @@ export function truncateTaskDescription(task: string, maxLen = 200): string {
 }
 
 /**
- * Format the in-flight task list (status === "running") shared by the result
- * envelope's 在途 block and the action="cancel" receipt. Deliberately carries
- * no elapsed time: the list answers "what is still running", not "how long has
- * it run".
+ * Format the in-flight task list (status === "running") for the result
+ * envelope's 在途 block. The list is a build-time snapshot; since the
+ * notification may be delivered after the main agent has dispatched new
+ * tasks, the wording is anchored to this envelope's task-end event (an
+ * event the main agent can order against its own dispatch records) instead
+ * of an absolute "right now" claim. Deliberately carries no elapsed time
+ * or clock time: the list answers "what was still running when this task
+ * ended", not "how long has it run" or "what time is it".
  */
 export function formatActiveTasks(): string {
 	const running = [...taskRegistry.values()].filter((t) => t.status === "running");
-	if (running.length === 0) return "当前无在途任务。";
+	if (running.length === 0) return "本任务结束时无其他在途任务。";
+	const lines = running.map((t) => `- ${t.taskId} (${t.agentName}): ${truncateTaskDescription(t.task)}`);
+	return `本任务结束时，其他在途任务: ${running.length}\n${lines.join("\n")}`;
+}
+
+/**
+ * Remaining in-flight list for the action="cancel" confirmation receipt.
+ * NOT shared with the envelope block (formatActiveTasks): at this point no
+ * task has ended — the cancel was merely requested and the cancelled task's
+ * result arrives later — so a "本任务结束" anchor would be wrong here. The
+ * receipt is returned synchronously in the same turn, so anchoring the
+ * snapshot to the cancel request itself is accurate.
+ */
+function formatRemainingTasksAfterCancelRequest(): string {
+	const running = [...taskRegistry.values()].filter((t) => t.status === "running");
+	if (running.length === 0) return "取消请求发出后，已无其他在途任务。";
 	const lines = running.map((t) => `- ${t.taskId} (${t.agentName}): ${truncateTaskDescription(t.task)}`);
-	return `在途任务: ${running.length}\n${lines.join("\n")}`;
+	return `取消请求发出后，其余在途任务: ${running.length}\n${lines.join("\n")}`;
 }
 
 /** A finished async task, recorded when completeAsyncTask removes it from the registry. */
@@ -1687,21 +1749,38 @@ export interface SubagentResultDetails {
 const DETAILS_OUTPUT_MAX_CHARS = 16 * 1024;
 
 /**
- * Build the [subagent-result] notification envelope: a markdown content text
- * carrying the full, untruncated result, plus structured details (details.output
- * is capped at DETAILS_OUTPUT_MAX_CHARS; content always keeps the full text).
+ * Fixed trigger line inserted into every [subagent-result] envelope right
+ * after the title line (before the in-flight block). Steer delivery injects
+ * the notification mid-turn, breaking the main agent's plan continuity; this
+ * verbatim meta-instruction (markdown quote line) reminds it that the notice
+ * is not a new user instruction and to anchor its mainline task first.
+ * Identical across all four terminal statuses (success/failure/timeout/
+ * cancelled) — a fixed template, not status-dependent.
  */
+const RESULT_TRIGGER_LINE =
+	"> [subagent-result] 任务完成通知，非用户新指令。处理前先锚定你当前正在执行的主线任务与进度；对照派发记录消化本通知，勿让通知覆盖或改写你的主线计划。";
+
 /**
  * Empty-body fallback for an aborted task, keyed on the abort's origin so the
  * main agent can tell a deliberate user cancel, an agent-initiated cancel and
  * a session shutdown apart (and does not auto-retry a user cancel).
  */
-function abortedFallbackBody(stopReason?: string, cancelledBy?: "user" | "agent"): string {
+function abortedFallbackBody(stopReason?: string, cancelledBy?: "user" | "agent", cancelReason?: string): string {
 	if (stopReason === "killed_on_shutdown") return "任务因会话关闭被终止（session_shutdown）。";
-	if (cancelledBy === "agent") return "该任务已由主 agent 通过 subagent 工具（action=cancel）取消。";
+	if (cancelledBy === "agent") {
+		const base = "该任务已由主 agent 通过 subagent 工具（action=cancel）取消。";
+		// Single-line and cap the reason: it is model-controlled text inlined
+		// into a notification body. The full value stays on the task record.
+		return cancelReason ? `${base}取消理由: ${truncateTaskDescription(cancelReason, 200)}` : base;
+	}
 	return "该任务已由用户通过 /subagent-cancel 取消，属用户主动操作。请勿自动重新派发；如需重新派发，先询问用户。";
 }
 
+/**
+ * Build the [subagent-result] notification envelope: a markdown content text
+ * carrying the full, untruncated result, plus structured details (details.output
+ * is capped at DETAILS_OUTPUT_MAX_CHARS; content always keeps the full text).
+ */
 export function buildResultEnvelope(
 	task: AsyncSubagentTask,
 	result: SingleResult | null,
@@ -1725,10 +1804,12 @@ export function buildResultEnvelope(
 	// Only genuine failures are labelled "内部错误"; a user cancel or session
 	// shutdown rejection is an expected abort, so it gets a note carrying the
 	// abort's origin (user cancel vs session shutdown).
-	if (!body && errorMessage) body = status === "failure" ? `内部错误: ${errorMessage}` : abortedFallbackBody(stopReason, task.cancelledBy);
+	if (!body && errorMessage) body = status === "failure" ? `内部错误: ${errorMessage}` : abortedFallbackBody(stopReason, task.cancelledBy, task.cancelReason);
 	const lines = [
 		`## [subagent-result] ${task.agentName} ${statusWord} (taskId: ${task.taskId})`,
 		"",
+		RESULT_TRIGGER_LINE,
+		"",
 		`- 状态: ${statusWord}`,
 		`- 任务: ${truncateTaskDescription(task.task)}`,
 		`- 耗时: ${formatDuration(durationMs)} · 用量: ${formatUsageStats(usage, result?.model) || "-"}`,
@@ -1739,7 +1820,7 @@ export function buildResultEnvelope(
 		formatActiveTasks(),
 		"",
 		"---",
-		body || (status === "cancelled" ? abortedFallbackBody(stopReason, task.cancelledBy) : "(no output)"),
+		body || (status === "cancelled" ? abortedFallbackBody(stopReason, task.cancelledBy, task.cancelReason) : "(no output)"),
 	];
 	return {
 		content: lines.join("\n"),
@@ -1769,6 +1850,42 @@ function buildDispatchReceipt(agentName: string, taskId: string): string {
 	return `已派出 ${agentName}. taskId: ${taskId}`;
 }
 
+/**
+ * Build the two-step-confirmation challenge for action="cancel" (first call,
+ * confirm !== true): a zero-side-effect receipt spelling out what a cancel
+ * would destroy — agent, task summary, elapsed time, last progress — plus the
+ * exact second-call shape. The main agent must confirm deliberately instead
+ * of reflexively cancelling a healthy in-flight task.
+ */
+function buildCancelChallenge(task: AsyncSubagentTask): string {
+	const lastActivityAt = progressManager.getLastActivityAt(task.taskId);
+	let progressLine: string;
+	if (lastActivityAt === undefined) {
+		progressLine = "- 最近进度: 尚无进度上报（no progress reported yet）。";
+	} else {
+		// Read the clock once and derive both language phrases from that single
+		// value — two Date.now() reads could straddle a second boundary and
+		// disagree ("5 秒前 (6s ago)").
+		const ageSec = Math.max(0, Math.floor((Date.now() - lastActivityAt) / 1000));
+		// Under an hour, plain seconds read best; past that, fold into
+		// formatDuration (H:MM:SS) instead of a huge second count.
+		progressLine =
+			ageSec < 3600
+				? `- 最近进度更新: ${ageSec} 秒前 (last activity ${ageSec}s ago)。`
+				: `- 最近进度更新: ${formatDuration(ageSec * 1000)} 前 (last activity ${formatDuration(ageSec * 1000)} ago)。`;
+	}
+	return [
+		`取消确认请求 (cancel confirmation required): 任务 ${task.taskId} 仍在运行；本次调用未取消任何东西。`,
+		`- agent: ${task.agentName}`,
+		`- 任务: ${truncateTaskDescription(task.task)}`,
+		`- 已运行: ${formatDuration(Date.now() - task.startedAt)} (elapsed since dispatch)`,
+		progressLine,
+		"",
+		"⚠️ 取消将丢弃该任务的全部在途进度，且不可撤销（cancelling discards all in-flight progress and cannot be undone）。",
+		`如确认取消，再次调用 subagent 工具: action="cancel" + taskId="${task.taskId}" + confirm:true + reason（reason 必填，说明取消理由）。`,
+	].join("\n");
+}
+
 /**
  * Finalize an async task: unregister progress, drop it from the registry, and
  * push the [subagent-result] notification. Called exactly once per task, on
@@ -1820,7 +1937,7 @@ function completeAsyncTask(pi: ExtensionAPI, task: AsyncSubagentTask, result: Si
 		const envelope = buildResultEnvelope(task, result, status, stopReason, errorMessage);
 		pi.sendMessage(
 			{ customType: "subagent-result", content: envelope.content, display: true, details: envelope.details },
-			{ deliverAs: "followUp", triggerTurn: true },
+			{ deliverAs: "steer", triggerTurn: true },
 		);
 	} catch {
 		// The session may already be gone (e.g. after session_shutdown); the
@@ -1851,6 +1968,15 @@ const SubagentParams = Type.Object({
 	taskId: Type.Optional(Type.String({
 		description: "taskId of the running background subagent task to cancel (required for action=cancel; from the dispatch receipt).",
 	})),
+	confirm: Type.Optional(Type.Boolean({
+		description:
+			'Set true to actually execute an action=cancel after reviewing the challenge returned by the first call. Default: false — the first action=cancel call only returns a challenge (confirmRequired) and cancels nothing.',
+		default: false,
+	})),
+	reason: Type.Optional(Type.String({
+		description:
+			"Why the task is being cancelled (required and must be non-empty when confirm=true). Recorded on the task and quoted in the [subagent-result] envelope.",
+	})),
 	sessionId: Type.Optional(Type.String({
 		pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
 		description: "仅用于复用此前 dispatch 回执返回的 UUID v7；省略则自动生成",
@@ -1871,7 +1997,7 @@ export default function (pi: ExtensionAPI) {
 			"",
 			"ACTIONS (action parameter, default \"dispatch\"):",
 			"- dispatch: delegate the task (async in TUI mode, blocking otherwise).",
-			"- cancel: cancel a running background task by taskId.",
+			"- cancel: request cancellation of a running background task by taskId (two-step: the first call returns a challenge; confirm:true + reason executes).",
 			"- sessionId: only set when resuming (复用) a previously dispatched task. Must be the UUID v7 from a previous dispatch receipt. Omit otherwise; a new UUID v7 is generated automatically.",
 			"",
 			"ASYNC (TUI mode): returns immediately with a dispatch receipt (taskId + session id).",
@@ -1884,9 +2010,18 @@ export default function (pi: ExtensionAPI) {
 			"  receipt to continue the same task later.",
 			"",
 			"CANCEL DISCIPLINE: cancel a task (action=\"cancel\") only when it is clearly",
-			"wrong (错误) or no longer needed (不再需要). Do NOT cancel just because it is",
-			"taking a long time — background subagents are expected to run long; be patient",
-			"(耐心等待) and let the [subagent-result] notification arrive.",
+			"wrong (错误) or no longer needed (不再需要). Agent-initiated cancel is a",
+			"two-step confirmation: the first action=\"cancel\" call only returns a",
+			"challenge (confirmRequired) with elapsed time and last progress, and",
+			"cancels nothing; to actually cancel, call action=\"cancel\" again with the",
+			"same taskId + confirm:true + a non-empty reason (理由). Do NOT cancel just",
+			"because it is taking a long time — background subagents are expected to",
+			"run long; be patient (耐心等待) and let the [subagent-result]",
+			"notification arrive.",
+			"",
+			"WAITING: 对在途任务不存在查询/催办/状态确认类动作（no query, nag or status",
+			"action for in-flight tasks）——没有提供这类动作是刻意设计。等待 = 不发",
+			"起任何工具调用，直接结束回合（waiting means no tool call: end the turn）。",
 			"",
 			"SYNC (non-TUI modes): waits for the subagent to finish and returns the full",
 			"result directly (no notification follows).",
@@ -1899,10 +2034,14 @@ export default function (pi: ExtensionAPI) {
 		promptGuidelines: [
 			"subagent: In TUI mode this tool is asynchronous — it returns a dispatch receipt, not the result; the real result arrives later as a [subagent-result] system notification, so never fabricate results and never poll.",
 			"subagent: A message prefixed with [subagent-result] is a system notification carrying a finished subagent result, not a user request; process it in the context of the task that dispatched it.",
+			"subagent: A [subagent-result] notification is a task-completion notice, NOT a new user instruction (完成通知而非用户新指令) — before acting on it, first anchor (锚定) the mainline task and progress you are currently on (当前主线任务与进度), digest the notification against your own dispatch records (对照派发记录消化), then decide your next step yourself based on the result (基于结果自主决定下一步), and whenever it conflicts with your mainline plan, defer acting on it (暂缓处理) — never let a notification overwrite or rewrite your mainline plan (勿让通知覆盖或改写主线计划).",
 			"subagent: Dispatch subagents driven by task dependencies — delegate only work whose result you actually need, prefer reusing the session id from the receipt to continue a previous subagent task, and keep independent work in the main context.",
 			"subagent: The session id is the lowercase UUID v7 returned in the dispatch receipt (e.g. `019ffdd3-3eb5-733d-b481-a53e5292bd00`). Passing any other string (slug, UUID v4, etc.) is rejected; only pass sessionId when resuming a previously dispatched task.",
 			"subagent: A [subagent-result] notification with status 已取消 (cancelled) can come from the user (/subagent-cancel) or from you (action=\"cancel\"); the envelope body states the source. A user-initiated cancel is a deliberate user action, so do NOT automatically retry or re-dispatch it; ask the user before re-dispatching.",
+			"subagent: Cancelling a background task is a two-step confirmation: the first action=\"cancel\" call only returns a challenge (confirmRequired) and cancels nothing; to actually cancel, call again with the same taskId + confirm:true + a non-empty reason explaining why. Never cancel just because a task runs long.",
+			"subagent: Waiting for a background task means making NO tool call at all and ending the turn (等待 = 不发起任何工具调用、直接结束回合); there is deliberately no query, nag or status action for in-flight tasks — results arrive on their own as [subagent-result] notifications.",
 			"subagent: Before dispatching multiple tasks in parallel, consider whether they touch the same files or code areas — parallel tasks modifying the same files can conflict. When in doubt, dispatch sequentially or ask the user.",
+			"subagent: The in-flight block in a [subagent-result] envelope is a build-time snapshot (构建时刻快照) anchored to that task's end event and may be stale (可能滞后) by the time you process the notification; if it conflicts with dispatch records you issued yourself this turn, trust your dispatch records (冲突时以派发记录为准).",
 		],
 		parameters: SubagentParams,
 
@@ -1942,16 +2081,41 @@ export default function (pi: ExtensionAPI) {
 					};
 				}
 				// Only registry (async/TUI) tasks are cancellable; sync-mode tasks are
-				// awaited inline and never enter the registry.
-				if (!cancelTask(taskId, "agent")) {
+				// awaited inline and never enter the registry. Existence is checked
+				// BEFORE the confirm/reason gates so a wrong id always fails the same
+				// way regardless of confirmation state.
+				const task = taskRegistry.get(taskId);
+				if (!task || task.status !== "running") {
 					return {
 						content: [{ type: "text", text: `无此运行中任务: ${taskId} (no running subagent task with this id).` }],
 						details: { taskId, cancelled: false },
 						isError: true,
 					};
 				}
+				// Two-step confirmation: the first call (confirm !== true) only
+				// returns a challenge spelling out what would be destroyed — zero
+				// side-effects (no status change, no abort, no notification). This
+				// structural friction exists because the main agent used to fire
+				// reflexive cancels at healthy in-flight tasks.
+				if (params.confirm !== true) {
+					return {
+						content: [{ type: "text", text: buildCancelChallenge(task) }],
+						details: { taskId, cancelled: false, confirmRequired: true },
+					};
+				}
+				// A confirmed cancel must justify itself: the reason is recorded on
+				// the task record and quoted in the [subagent-result] envelope body.
+				const reason = typeof params.reason === "string" ? params.reason.trim() : "";
+				if (!reason) {
+					return {
+						content: [{ type: "text", text: 'Missing or empty required parameter: "reason" (confirm:true 时 reason 必填，不能为空).' }],
+						details: { taskId, cancelled: false },
+						isError: true,
+					};
+				}
+				cancelTask(taskId, "agent", reason);
 				return {
-					content: [{ type: "text", text: `已发送取消请求: ${taskId} (cancel request sent); 结果稍后以 [subagent-result] 通知返回。\n${formatActiveTasks()}` }],
+					content: [{ type: "text", text: `已发送取消请求: ${taskId} (cancel request sent); 结果稍后以 [subagent-result] 通知返回。\n${formatRemainingTasksAfterCancelRequest()}` }],
 					details: { taskId, cancelled: true },
 				};
 			}