@wolido/async-subagent-isolation 1.0.0 → 1.1.0

package/ADVANCED.en.md

@@ -114,7 +114,7 @@ Key points:
 - **The receipt is a single line.** The async-semantics guidance (don't fabricate results, don't poll, results arrive as a `[subagent-result]` notification) is embedded in the `subagent` tool's `description` / `promptGuidelines`; the receipt itself stays a single line.
 - **The receipt is not the result.** Do not fabricate results.
 - **taskId = sessionId.** The `taskId` in the receipt is the session ID; reuse it directly.
-- **Do not poll.** Results arrive automatically as `[subagent-result]` notifications; to confirm which tasks are still in flight (e.g. after a `/tree` rewind), use the `subagent_status` tool.
+- **Do not poll.** Results arrive automatically as `[subagent-result]` notifications; to confirm which tasks are still in flight (e.g. after a `/tree` rewind), use the `subagent` tool with `action="status"`.
 
 ### [subagent-result] envelope format
 
@@ -139,12 +139,12 @@ Status enumeration: **成功** (success, exit=0) / **失败** (failure, exit≠0
 
 "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 `subagent_cancel` tool (cancelledBy: agent) → body states the task was cancelled by the main agent via the subagent_cancel tool.
+- 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).
 - 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 matches the `subagent_status` tool — `在途任务: 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 matches the `subagent` tool's `action="status"` — `在途任务: 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.
 
 The full output enters the LLM context (not truncated). The `details` carries structured data (taskId, agent, status, exitCode, stopReason, usage, sessionId, full output) for programmatic consumption; it does not enter the LLM context.
 
@@ -166,9 +166,9 @@ While subagents run, a progress widget appears above the TUI editor, listing all
 
 The taskId in the widget row can be copied for `/subagent-result` (view full result) or `/subagent-cancel` (cancel the task).
 
-### subagent_status (in-flight query)
+### `action="status"` (in-flight query)
 
-The main agent can actively query still-running background tasks via the `subagent_status` tool (no parameters), which returns:
+The main agent can actively query still-running background tasks via the `subagent` tool with `action="status"` (no agent/task parameters needed), which returns:
 
 ```
 在途任务: 2
@@ -181,7 +181,7 @@ With no in-flight tasks it returns `当前无在途任务。`. Each line carries
 Use cases:
 
 - After a `/tree` rewind loses the receipts, confirm which tasks are still in flight.
-- When unsure how many tasks remain, or to pick a taskId for `subagent_cancel`.
+- When unsure how many tasks remain, or to pick a taskId for `action="cancel"`.
 
 **Do not use it to poll for completion**: results arrive automatically as `[subagent-result]` notifications. This tool only confirms "what is still running" — it should not be called frequently.
 
@@ -207,11 +207,11 @@ 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_cancel` tool**
+**Path 2: Main agent `subagent` tool with `action="cancel"`**
 
-The main agent can call the `subagent_cancel` tool (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 `subagent_status`); 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. The cancel source is recorded as `cancelledBy: "agent"`. On success, the tool returns the remaining in-flight task list (same format as `action="status"`); the cancelled task's final result arrives later as a `[subagent-result]` notification.
 
-**Usage discipline:** The main agent should only use `subagent_cancel` when:
+**Usage discipline:** The main agent should only use `action="cancel"` when:
 - The task is clearly wrong (wrong agent, incorrect task description, etc.).
 - The task is no longer needed (requirement change, later discovery that this step is unnecessary).
 
@@ -292,7 +292,7 @@ These variables are propagated into every subagent process automatically:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `PI_SUBAGENT_DEPTH` | `0` | Current recursion depth. Auto-incremented per nested call. **Depth limit is 1** — a subagent (depth ≥ 1) cannot dispatch `subagent`; recursive delegation is blocked entirely. |
+| `PI_SUBAGENT_DEPTH` | `0` | Current recursion depth. Auto-incremented per nested call. **Depth limit is 1** — a subagent (depth ≥ 1) cannot call any `subagent` action (including `action="status"` / `action="cancel"`). |
 | `PI_CURRENT_AGENT_NAME` | — | Name of the current agent, injected into every subagent process. |
 | `PI_SUBAGENT_ACTIVITY_TIMEOUT_MS` | `600000` (10 min) | Max idle time with no output on either stdout or stderr before the subagent is killed. |
 | `PI_SUBAGENT_HARD_TIMEOUT_MS` | `0` (disabled) | Absolute maximum runtime for a single call. Set a positive value (ms) to enable. |

package/ADVANCED.md

@@ -114,7 +114,7 @@ TUI 模式下 `subagent` 立即返回如下回执（不是结果！）：
 - **回执为单行。** 异步语义引导（不臆造结果、不轮询、结果以 `[subagent-result]` 通知到达）已内嵌于 `subagent` 工具的 `description` / `promptGuidelines`，回执本身保持单行。
 - **回执 ≠ 结果。** 不要臆造结果。
 - **taskId = sessionId。** 回执中的 `taskId` 就是 session ID，可直接复用。
-- **不要轮询。** 结果自动以 `[subagent-result]` 通知到达；如需确认还有哪些任务在途（如 `/tree` 回退后），用 `subagent_status` 工具查询。
+- **不要轮询。** 结果自动以 `[subagent-result]` 通知到达；如需确认还有哪些任务在途（如 `/tree` 回退后），用 `subagent` 工具（`action="status"`）查询。
 
 ### [subagent-result] 信封格式
 
@@ -139,12 +139,12 @@ TUI 模式下 `subagent` 立即返回如下回执（不是结果！）：
 
 "已取消"分三种情况，信封正文不同：
 - 用户通过 `/subagent-cancel` 取消（cancelledBy: user）→ 正文注明"属用户主动操作。请勿自动重新派发；如需重新派发，先询问用户。"
-- 主 agent 通过 `subagent_cancel` 工具取消（cancelledBy: agent）→ 正文注明"该任务已由主 agent 通过 subagent_cancel 工具取消。"
+- 主 agent 通过 `subagent` 工具（`action="cancel"`）取消（cancelledBy: agent）→ 正文注明"该任务已由主 agent 通过 subagent 工具（action=cancel）取消。"
 - 会话关闭（session_shutdown）终止（cancelledBy: 无）→ 正文注明"任务因会话关闭被终止（session_shutdown）。"
 
 主 agent 收到状态为"已取消"的通知时，应区分来源：用户主动取消**不得自动重试**，必须先询问用户；agent 取消是自身决策，不应在无新信息时重新派发；会话关闭终止可在会话恢复后视情况重新派发。
 
-**在途任务块**：信封元信息区的"在途任务"列表列出**其余**仍在运行的后台任务（本任务在构建信封前已从注册表移除，故不包含自身），格式与 `subagent_status` 工具一致——`在途任务: N` 加每行 `- taskId (agent名): 任务描述`，无在途任务时为"当前无在途任务。"。列表**不含耗时**（回答"还有什么在跑"，而非"跑了多久"）。主 agent 据此知道还有几个任务没回来：剩余不为 0 时，不要向用户汇报"全部完成"。
+**在途任务块**：信封元信息区的"在途任务"列表列出**其余**仍在运行的后台任务（本任务在构建信封前已从注册表移除，故不包含自身），格式与 `subagent` 工具 `action="status"` 一致——`在途任务: N` 加每行 `- taskId (agent名): 任务描述`，无在途任务时为"当前无在途任务。"。列表**不含耗时**（回答"还有什么在跑"，而非"跑了多久"）。主 agent 据此知道还有几个任务没回来：剩余不为 0 时，不要向用户汇报"全部完成"。
 
 结果全量进入 LLM 上下文（不截断）。`details` 携带结构化数据（taskId、agent、status、exitCode、stopReason、usage、sessionId、完整输出），不参与 LLM 上下文，供程序消费。
 
@@ -166,9 +166,9 @@ TUI 模式下 `subagent` 立即返回如下回执（不是结果！）：
 
 widget 行中的 taskId 可直接复制，用于 `/subagent-result` 查看结果或 `/subagent-cancel` 取消任务。
 
-### subagent_status（在途任务查询）
+### `action="status"`（在途任务查询）
 
-主 agent 可主动查询仍在运行的后台任务，调用 `subagent_status` 工具（无参数），返回：
+主 agent 可主动查询仍在运行的后台任务，调用 `subagent` 工具（`action="status"`，无需 agent/task 参数），返回：
 
 ```
 在途任务: 2
@@ -181,7 +181,7 @@ widget 行中的 taskId 可直接复制，用于 `/subagent-result` 查看结果
 用途场景：
 
 - `/tree` 回退后回执丢失，确认还有哪些任务在途。
-- 不确定剩余任务时快速核对，或选取 taskId 用于 `subagent_cancel`。
+- 不确定剩余任务时快速核对，或选取 taskId 用于 `action="cancel"`。
 
 **不要用它轮询完成状态**：结果会自动以 `[subagent-result]` 通知到达，本工具只用于确认"还有什么在跑"，不应频繁调用。
 
@@ -207,11 +207,11 @@ widget 行中的 taskId 可直接复制，用于 `/subagent-result` 查看结果
 
 无参数。与 `/subagent-cancel` 按 taskId 取消单个任务不同，`/subagent-cancel-all` 取消全部运行中的任务。每个被取消任务照常推送各自的"已取消" `[subagent-result]` 通知（主 agent 会收到 N 个已取消信封）。成功时提示"已取消全部 N 个运行中任务"，无运行中任务时提示"无运行中任务可取消"。取消来源同样标记为 `cancelledBy: "user"`。
 
-**路径二：主 agent `subagent_cancel` 工具**
+**路径二：主 agent `subagent` 工具（`action="cancel"`）**
 
-主 agent 可调用 `subagent_cancel` 工具（参数 `taskId`）取消已派出的后台任务。取消来源标记为 `cancelledBy: "agent"`。取消成功后返回剩余在途任务列表（格式与 `subagent_status` 一致），被取消任务的最终结果稍后以 `[subagent-result]` 通知返回。
+主 agent 可调用 `subagent` 工具（`action="cancel"`，参数 `taskId`）取消已派出的后台任务。取消来源标记为 `cancelledBy: "agent"`。取消成功后返回剩余在途任务列表（格式与 `action="status"` 一致），被取消任务的最终结果稍后以 `[subagent-result]` 通知返回。
 
-**使用纪律：** 主 agent 仅在以下情况使用 `subagent_cancel`：
+**使用纪律：** 主 agent 仅在以下情况使用 `action="cancel"`：
 - 任务明显错误（委派了错误的 agent、任务描述有误等）。
 - 任务不再需要（用户需求变更、后续发现无需此步骤）。
 
@@ -292,7 +292,7 @@ widget 行中的 taskId 可直接复制，用于 `/subagent-result` 查看结果
 
 | 变量 | 默认值 | 说明 |
 |------|--------|------|
-| `PI_SUBAGENT_DEPTH` | `0` | 当前递归深度。每次嵌套调用自动递增。**深度限制为 1**——子 agent（depth ≥ 1）不可再派发 `subagent`，递归委派已被完全禁止。 |
+| `PI_SUBAGENT_DEPTH` | `0` | 当前递归深度。每次嵌套调用自动递增。**深度限制为 1**——子 agent（depth ≥ 1）不可调用任何 `subagent` action（含 `action="status"` / `action="cancel"`）。 |
 | `PI_CURRENT_AGENT_NAME` | — | 当前 agent 名称，注入每个子 agent 进程。 |
 | `PI_SUBAGENT_ACTIVITY_TIMEOUT_MS` | `600000`（10 分钟） | stdout 和 stderr 均无输出（无活动）时的最大允许时间。 |
 | `PI_SUBAGENT_HARD_TIMEOUT_MS` | `0`（禁用） | 单次调用的绝对最大运行时长。设为正数（毫秒）启用。 |

package/README.en.md

@@ -47,7 +47,7 @@ The main agent is the dispatcher: it understands the request, splits it into tas
 
 More important is **the freedom after dispatch**. While a task runs in the background, you keep talking to the main agent — refine the requirements, adjust the plan, discuss next steps, or raise a new task. The main agent doesn't wait idle; it can keep planning and even dispatch more tasks in parallel. Foreground conversation and background work move forward together.
 
-Finally, **review when the result returns**. The subagent finishes, the notification arrives, and the main agent processes it and reports back. While you wait, you can check in-flight status any time (the progress widget or `subagent_status`), but you never have to watch.
+Finally, **review when the result returns**. The subagent finishes, the notification arrives, and the main agent processes it and reports back. While you wait, you can check in-flight status any time (the progress widget or the `subagent` tool with `action="status"`), but you never have to watch.
 
 In one line: sync traps you in the "swarm execution" block; async keeps you facing a single dispatcher while background work runs alongside your own pace.
 
@@ -104,7 +104,7 @@ When the subagent finishes, its result is pushed as a **`[subagent-result]` syst
 - 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.
 
-Results arrive automatically — **no polling**. To confirm which tasks are still in flight (e.g. after a `/tree` rewind loses the receipts), use the `subagent_status` tool.
+Results arrive automatically — **no polling**. To confirm which tasks are still in flight (e.g. after a `/tree` rewind loses the receipts), use the `subagent` tool with `action="status"`.
 
 ### 5. Read the full result (`/subagent-result`)
 
@@ -133,9 +133,9 @@ User runs /subagent-result <taskId> to read the full output
 
 | Tool | Purpose | Key constraint |
 |------|---------|----------------|
-| `subagent` | Async dispatch (TUI mode); falls back to sync in non-TUI | Receipt ≠ result; results arrive as notifications, don't poll |
-| `subagent_status` | List in-flight tasks (taskId, agent, description, **no elapsed time**) | Only confirm "what's still running"; never poll with it |
-| `subagent_cancel` | Main agent cancels one in-flight task | Only when clearly wrong or no longer needed; never for being slow |
+| `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="status"` | List in-flight tasks (taskId, agent, description, **no elapsed time**) | Only confirm "what's still running"; never poll with it |
+| `subagent` `action="cancel"` | Main agent cancels one in-flight task | Only when clearly wrong or no longer needed; never for being slow |
 
 ### Commands (for the user)
 
@@ -180,11 +180,11 @@ See [ADVANCED.en.md](ADVANCED.en.md) for the complete envelope format, status se
 
 Async mode introduces a few rules, baked into the tool prompts and implementation, that the main agent follows automatically:
 
-- **Cancel-origin distinction**: `已取消` (cancelled) has three origins — user (`/subagent-cancel`), main agent (`subagent_cancel` tool), 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. `subagent_status` only confirms what's in flight (e.g. after a `/tree` rewind), carries no elapsed time, and is not meant to be called frequently.
-- **Anti-abuse cancellation**: `subagent_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).
+- **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. `action="status"` only confirms what's in flight (e.g. after a `/tree` rewind), carries no elapsed time, and is not meant to be called frequently.
+- **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).
 - **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.
-- **Recursion blocked entirely**: a subagent (depth ≥ 1) can never dispatch `subagent`; delegation depth is capped at 1.
+- **Subagents cannot call the subagent tool**: a subagent (depth ≥ 1) can never call any `subagent` action (including `action="status"` / `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.
 
 ---
@@ -273,7 +273,7 @@ Put it in `~/.pi/agent/subagent-isolation.json` (user-level) or `.pi/subagent-is
 
 ## Advanced usage
 
-Manual `subagent` calls, `sessionId` reuse, envelope and in-flight block details, `subagent_status` queries, cancellation, and environment variables are covered in [ADVANCED.en.md](ADVANCED.en.md).
+Manual `subagent` calls, `sessionId` reuse, envelope and in-flight block details, `action="status"` queries, `action="cancel"` cancellation, and environment variables are covered in [ADVANCED.en.md](ADVANCED.en.md).
 
 ---
 

package/README.md

@@ -47,7 +47,7 @@
 
 更关键的是**派发之后的自由**。任务在后台跑的时候，你可以继续和主 agent 聊天：细化需求、调整规划、商量下一步，或提出新任务。主 agent 不必干等，可以继续规划，甚至并行派发更多任务。前台对话与后台工作并行推进。
 
-最后是**结果回来再验收**。子 agent 完成，通知到达，主 agent 处理并向你汇报。等待期间你可以随时查看在途状态（进度 widget 或 `subagent_status`），但不必盯着。
+最后是**结果回来再验收**。子 agent 完成，通知到达，主 agent 处理并向你汇报。等待期间你可以随时查看在途状态（进度 widget 或 `subagent` 工具 `action="status"`），但不必盯着。
 
 一句话：同步版让你陷在"集群执行"的阻塞感里；异步版让你只面对调度者，后台工作与你自己的节奏并行。
 
@@ -104,7 +104,7 @@ TUI 模式下 `subagent` **立即返回派发回执**，不阻塞：
 - 主 agent **空闲**时，通知直接触发新的对话回合，立即处理。
 - 主 agent **忙碌**时，通知进入队列，当前回合结束后再触发。
 
-结果自动到达，**无需轮询**。如需确认还有哪些任务在途（例如 `/tree` 回退后回执丢失），用 `subagent_status` 工具查询。
+结果自动到达，**无需轮询**。如需确认还有哪些任务在途（例如 `/tree` 回退后回执丢失），用 `subagent` 工具（`action="status"`）查询。
 
 ### 5. 查看全文（`/subagent-result`）
 
@@ -133,9 +133,9 @@ TUI 模式下 `subagent` **立即返回派发回执**，不阻塞：
 
 | 工具 | 作用 | 关键约束 |
 |------|------|----------|
-| `subagent` | 异步派发任务（TUI 模式）；非 TUI 自动降级同步 | 回执≠结果；结果以通知到达，勿轮询 |
-| `subagent_status` | 查询在途任务（taskId、agent、任务描述，**无耗时**） | 仅确认"还有什么在跑"，勿用它轮询完成 |
-| `subagent_cancel` | 主 agent 取消单个在途任务 | 仅当任务明显错误或不再需要，勿因耗时久而取消 |
+| `subagent` | 单入口工具（`action` 参数）；`action="dispatch"`（默认）异步派发任务（TUI 模式），非 TUI 自动降级同步 | 回执≠结果；结果以通知到达，勿轮询 |
+| `subagent` `action="status"` | 查询在途任务（taskId、agent、任务描述，**无耗时**） | 仅确认"还有什么在跑"，勿用它轮询完成 |
+| `subagent` `action="cancel"` | 主 agent 取消单个在途任务 | 仅当任务明显错误或不再需要，勿因耗时久而取消 |
 
 ### 命令（用户使用）
 
@@ -180,11 +180,11 @@ TUI 模式下 `subagent` **立即返回派发回执**，不阻塞：
 
 异步模式引入的几条纪律，内嵌在工具提示词和实现中，主 agent 自动遵守：
 
-- **取消来源区分**：`已取消` 有用户（`/subagent-cancel`）、主 agent（`subagent_cancel`）、会话关闭（`session_shutdown`）三种来源；用户取消**不得自动重试**，须先询问。
-- **防轮询**：结果以通知自动到达；`subagent_status` 只用于确认在途（如 `/tree` 回退后），不带耗时、不鼓励频繁调用。
-- **防滥用取消**：`subagent_cancel` 内嵌提示词——仅当任务明显错误或不再需要时取消，勿因耗时长而取消（后台任务本就预期长时间运行）。
+- **取消来源区分**：`已取消` 有用户（`/subagent-cancel`）、主 agent（`subagent` 工具 `action="cancel"`）、会话关闭（`session_shutdown`）三种来源；用户取消**不得自动重试**，须先询问。
+- **防轮询**：结果以通知自动到达；`action="status"` 只用于确认在途（如 `/tree` 回退后），不带耗时、不鼓励频繁调用。
+- **防滥用取消**：`action="cancel"` 内嵌提示词——仅当任务明显错误或不再需要时取消，勿因耗时长而取消（后台任务本就预期长时间运行）。
 - **资源冲突纪律**：并行派发多个任务前，考虑它们是否会改同一批文件或代码区域；冲突时串行派发或先问用户。
-- **递归委派完全禁止**：子 agent（深度 ≥ 1）不可再派发 `subagent`，深度限制为 1。
+- **子 agent 不可调用 subagent 工具**：子 agent（深度 ≥ 1）不可调用任何 `subagent` action（含 `action="status"` / `action="cancel"`），深度限制为 1。
 - **TUI 异步 / 非 TUI 同步降级**：只在 TUI 模式走异步路径；print/json 等非 TUI 模式降级为同步阻塞。
 
 ---
@@ -273,7 +273,7 @@ alias pp='pi --tools read,grep,find,ls,subagent --no-skills --append-system-prom
 
 ## 进阶用法
 
-手写 `subagent` 调用、复用 `sessionId`、信封与在途任务块细节、`subagent_status` 查询、取消任务、环境变量等见 [ADVANCED.md](ADVANCED.md)。
+手写 `subagent` 调用、复用 `sessionId`、信封与在途任务块细节、`action="status"` 查询、`action="cancel"` 取消任务、环境变量等见 [ADVANCED.md](ADVANCED.md)。
 
 ---
 

package/examples/pi/agent/master.md

@@ -16,9 +16,10 @@
 
 - `read` — 读文件
 - `grep` / `find` / `ls` — 搜索代码、浏览项目结构
-- `subagent` — 委派任务给子 agent
-- `subagent_status` — 查询仍在运行的后台任务（在途任务）
-- `subagent_cancel` — 取消错误或不再需要的后台任务
+- `subagent` — 单入口子 agent 工具，通过 `action` 参数区分操作：
+  - `action="dispatch"`（默认）— 委派任务给子 agent
+  - `action="status"` — 查询仍在运行的后台任务（在途任务）
+  - `action="cancel"` — 取消错误或不再需要的后台任务
 - 规划与决策 — 理解需求、拆分任务步骤、整合结果
 
 仅此而已。你无权执行写入或命令类操作。
@@ -29,21 +30,21 @@
 2. **依赖驱动派发** — 无依赖的任务可并行派出。有依赖的必须等对应 `[subagent-result]` 通知到达后再派。
 3. **派出后继续工作** — `subagent` 返回的只是派发回执（含 `taskId`），不是结果。派出后继续做不依赖该结果的工作，或结束回合。严禁轮询、严禁臆造结果。
 4. **识别系统通知** — 以 `[subagent-result]` 开头的消息是系统通知（子 agent 结果），不是用户请求。收到后关联到当初派发的任务进行处理。
-5. **通知先看在途任务块** — 每条 `[subagent-result]` 通知的元信息区带"在途任务"列表（剩余仍在运行的任务，不含本任务）。收到后先看剩余在途数：**不为 0 时还有任务未返回，不要向用户汇报"全部完成"**。需要确认在途状态（如 `/tree` 回退后不确定还剩哪些任务）时，用 `subagent_status` 工具查询。
+5. **通知先看在途任务块** — 每条 `[subagent-result]` 通知的元信息区带"在途任务"列表（剩余仍在运行的任务，不含本任务）。收到后先看剩余在途数：**不为 0 时还有任务未返回，不要向用户汇报"全部完成"**。需要确认在途状态（如 `/tree` 回退后不确定还剩哪些任务）时，用 `subagent` 工具（`action="status"`）查询。
 6. **已取消通知的处理** — 收到状态为"已取消"的 `[subagent-result]` 通知时，根据来源区分处理：
-- 正文注明用户通过 `/subagent-cancel` 取消 → 用户主动操作，**不得自动重新派发**。如需重新派发，先询问用户。
-- 正文注明主 agent 通过 `subagent_cancel` 取消 → 自身决策，不应在无新信息时重新派发。
-- 正文注明会话关闭（session_shutdown）终止 → 可在会话恢复后视情况重新派发。
+    - 正文注明用户通过 `/subagent-cancel` 取消 → 用户主动操作，**不得自动重新派发**。如需重新派发，先询问用户。
+    - 正文注明主 agent 通过 `subagent` 工具（`action="cancel"`）取消 → 自身决策，不应在无新信息时重新派发。
+    - 正文注明会话关闭（session_shutdown）终止 → 可在会话恢复后视情况重新派发。
 
-7. **`subagent_cancel` 使用纪律** — 你可以使用 `subagent_cancel` 工具纠正错误委派（如委派了错误的 agent、任务描述有误）或取消不再需要的任务。**不要因等待时间长而取消**——后台子 agent 本就预期长时间运行。取消的判据是"这个任务不该继续"，不是"等太久了"。
+7. **`action="cancel"` 使用纪律** — 你可以使用 `subagent` 工具（`action="cancel"`，参数 `taskId`）纠正错误委派（如委派了错误的 agent、任务描述有误）或取消不再需要的任务。**不要因等待时间长而取消**——后台子 agent 本就预期长时间运行。取消的判据是"这个任务不该继续"，不是"等太久了"。
 
 8. **用标准任务格式** — 每次委派必须包含以下结构：
 
-- **背景** — 任务来源、已完成的上下文
-- **输入** — 相关文件路径、数据
-- **要求** — 明确的任务清单，可逐项检查
-- **输出格式** — 期望的返回结构
-- **验收标准** — 如何判断完成（必须含验证命令及输出）
+    - **背景** — 任务来源、已完成的上下文
+    - **输入** — 相关文件路径、数据
+    - **要求** — 明确的任务清单，可逐项检查
+    - **输出格式** — 期望的返回结构
+    - **验收标准** — 如何判断完成（必须含验证命令及输出）
 
 ### 调用示例
 

package/package.json

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

package/src/index.ts

@@ -27,7 +27,7 @@ import {
 	getAgentDir,
 	parseFrontmatter,
 } from "@earendil-works/pi-coding-agent";
-import { Box, Container, Key, Markdown, matchesKey, Spacer, Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { Box, Container, Key, Markdown, matchesKey, Spacer, Text, truncateToWidth, visibleWidth, sliceByColumn } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 // ===== UUID v7 helper =====
@@ -545,6 +545,10 @@ interface AgentProgress {
 const PROGRESS_WIDGET_KEY = "async-subagent-isolation-progress";
 const MAX_WIDGET_LINES = 20;
 const MAX_RECENT_TOOLS = 3;
+// Cap for the dynamic name column: wide enough for typical agent names
+// (existing tests require a 20-char name to render in full), small enough
+// to leave room for the phase/elapsed columns on narrow terminals.
+const MAX_NAME_WIDTH = 30;
 
 /** Plain-text one-line summary of a tool call for the progress widget (no theme colors). */
 function summarizeToolCall(toolName: string, args: Record<string, any>): string {
@@ -561,6 +565,22 @@ function getRecentToolSummaries(messages: Message[]): string[] {
 		.map((item) => summarizeToolCall(item.name, item.args));
 }
 
+/**
+ * Fit an agent name into a fixed-width column: pad short names with spaces,
+ * truncate over-long names with a "..." suffix. Unlike truncateToWidth this
+ * never injects ANSI reset codes around the ellipsis (agent names carry no
+ * styling), so every row keeps the phase/elapsed columns at the same raw
+ * string offset as well as the same display column. Callers must pass
+ * width >= 4 so the ellipsis fits.
+ */
+function fitNameColumn(name: string, width: number): string {
+	const nameWidth = visibleWidth(name);
+	if (nameWidth <= width) return name + " ".repeat(width - nameWidth);
+	// strict: never keep a wide char that would straddle the cut boundary
+	const cut = sliceByColumn(name, 0, width - 3, true);
+	return cut + "..." + " ".repeat(Math.max(0, width - 3 - visibleWidth(cut)));
+}
+
 export function formatElapsed(startedAt: number): string {
 	const totalSec = Math.max(0, Math.floor((Date.now() - startedAt) / 1000));
 	const mm = String(Math.floor(totalSec / 60)).padStart(2, "0");
@@ -622,6 +642,9 @@ export class SubagentProgressManager {
 		const maxAgentRows = Math.max(1, Math.min(process.stdout.rows || MAX_WIDGET_LINES, MAX_WIDGET_LINES));
 		const visible = sorted.slice(-maxAgentRows);
 		const total = sorted.length;
+		// Name column width adapts to the longest visible agent name (capped),
+		// so the phase and elapsed columns start at the same offset on every row.
+		const nameColWidth = Math.min(MAX_NAME_WIDTH, Math.max(...visible.map((a) => visibleWidth(a.name))));
 		// Note: the factory closes over `theme`; between a theme change and the next
 		// refresh (≤1s) the widget may briefly use the stale theme. The 1Hz timer
 		// replaces the factory on every tick, so this self-heals.
@@ -640,7 +663,7 @@ export class SubagentProgressManager {
 				return borderColor("─") + theme.fg("accent", label) + borderColor("─".repeat(width - labelWidth - 1));
 			};
 			const renderRow = (a: AgentProgress, width: number): string => {
-				const nameCol = a.name;
+				const nameCol = fitNameColumn(a.name, nameColWidth);
 				const phaseCol = truncateToWidth(formatPhase(a.phase), 20, "...", true);
 				const toolHint = a.recentTools.length > 0 ? `  → ${a.recentTools[a.recentTools.length - 1]}` : "";
 				const line =
@@ -1424,7 +1447,7 @@ export interface AsyncSubagentTask {
 	status: "running" | "cancelled" | "killed_on_shutdown";
 	/**
 	 * Who cancelled the task: "user" via /subagent-cancel, "agent" via the
-	 * subagent_cancel tool. Set by cancelTask so the result envelope can name
+	 * subagent tool's action="cancel". Set by cancelTask so the result envelope can name
 	 * the cancel's origin; undefined for non-cancelled endings.
 	 */
 	cancelledBy?: "user" | "agent";
@@ -1447,7 +1470,7 @@ export const taskRegistry = new Map<string, AsyncSubagentTask>();
  * Cancel a running async subagent task: mark it cancelled, record who
  * cancelled it (for the envelope), and fire its abort controller — reusing
  * the SIGTERM -> 5s -> SIGKILL cascade in runSingleAgent. Shared by the
- * /subagent-cancel command and the subagent_cancel tool. Returns false when
+ * /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 {
@@ -1467,8 +1490,8 @@ export function truncateTaskDescription(task: string, maxLen = 200): string {
 
 /**
  * Format the in-flight task list (status === "running") shared by the
- * subagent_status tool, the result envelope's 在途 block, and the
- * subagent_cancel receipt. Deliberately carries no elapsed time: the list
+ * action="status" branch, 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".
  */
 export function formatActiveTasks(): string {
@@ -1520,7 +1543,7 @@ const DETAILS_OUTPUT_MAX_CHARS = 16 * 1024;
  */
 function abortedFallbackBody(stopReason?: string, cancelledBy?: "user" | "agent"): string {
 	if (stopReason === "killed_on_shutdown") return "任务因会话关闭被终止（session_shutdown）。";
-	if (cancelledBy === "agent") return "该任务已由主 agent 通过 subagent_cancel 工具取消。";
+	if (cancelledBy === "agent") return "该任务已由主 agent 通过 subagent 工具（action=cancel）取消。";
 	return "该任务已由用户通过 /subagent-cancel 取消，属用户主动操作。请勿自动重新派发；如需重新派发，先询问用户。";
 }
 
@@ -1645,9 +1668,24 @@ const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
 	default: "both",
 });
 
+// Union-of-literals (anyOf + const) rather than StringEnum so the emitted
+// JSON Schema enumerates each action as its own const branch.
+const SubagentActionSchema = Type.Union(
+	[Type.Literal("dispatch"), Type.Literal("status"), Type.Literal("cancel")],
+	{
+		description:
+			'Action to perform. "dispatch" (default): delegate the task to a subagent. "status": list in-flight background tasks. "cancel": cancel a running background task by taskId.',
+		default: "dispatch",
+	},
+);
+
 const SubagentParams = Type.Object({
-	agent: Type.String({ description: "Name of the agent to invoke" }),
-	task: Type.String({ description: "Task to delegate. Must be non-empty and include background, input, requirements, output format, and acceptance criteria." }),
+	action: Type.Optional(SubagentActionSchema),
+	agent: Type.Optional(Type.String({ description: "Name of the agent to invoke (required for action=dispatch)" })),
+	task: Type.Optional(Type.String({ description: "Task to delegate (required for action=dispatch). Must be non-empty and include background, input, requirements, output format, and acceptance criteria." })),
+	taskId: Type.Optional(Type.String({
+		description: "taskId of the running background subagent task to cancel (required for action=cancel; from the dispatch receipt).",
+	})),
 	sessionId: Type.Optional(Type.String({
 		pattern: "^[A-Za-z0-9_.-]+$",
 		description: "Optional session ID to reuse; a new UUID v7 is generated if omitted. Allowed characters: letters, digits, underscore, dot, and hyphen.",
@@ -1666,17 +1704,26 @@ export default function (pi: ExtensionAPI) {
 		description: [
 			"Delegate a task to a specialized subagent with isolated context.",
 			"",
+			"ACTIONS (action parameter, default \"dispatch\"):",
+			"- dispatch: delegate the task (async in TUI mode, blocking otherwise).",
+			"- status: list in-flight background tasks (taskId, agent, task description).",
+			"- cancel: cancel a running background task by taskId.",
+			"",
 			"ASYNC (TUI mode): returns immediately with a dispatch receipt (taskId + session id).",
 			"The result arrives later as a system notification message prefixed with",
 			"[subagent-result] — that is a system notification, NOT a user request.",
 			"- Do NOT treat the receipt as the result. Do NOT fabricate results.",
 			"- Do NOT poll for results; they arrive automatically. To confirm which",
-			"  tasks are still in flight (e.g. after a /tree rewind), use the",
-			"  subagent_status tool.",
+			"  tasks are still in flight (e.g. after a /tree rewind), use action=\"status\".",
 			"- Continue with independent work, or end the turn. Process the result when",
 			"  the [subagent-result] notification arrives. Reuse the session id from the",
 			"  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.",
+			"",
 			"SYNC (non-TUI modes): waits for the subagent to finish and returns the full",
 			"result directly (no notification follows).",
 			"",
@@ -1689,26 +1736,74 @@ export default function (pi: ExtensionAPI) {
 			"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 for status.",
 			"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: 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: A [subagent-result] notification with status 已取消 (cancelled) can come from the user (/subagent-cancel) or from you (subagent_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: 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: 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.",
 		],
 		parameters: SubagentParams,
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
-			const currentDepth = parseEnvInt(process.env.PI_SUBAGENT_DEPTH, 0);
+			// Single-entry action dispatch (default "dispatch").
+			const action = (params.action as string | undefined) ?? "dispatch";
 
-			// Recursive delegation is blocked entirely: a subagent (depth >= 1)
-			// can never spawn another subagent.
+			// Depth gate runs BEFORE any action dispatch: a subagent (depth >= 1)
+			// is blocked from every action — dispatch spawns a nested subagent, and
+			// status/cancel would let it observe or kill the parent's in-flight
+			// tasks. The tool surface simply does not exist inside a subagent.
+			const currentDepth = parseEnvInt(process.env.PI_SUBAGENT_DEPTH, 0);
 			if (currentDepth >= MAX_SUBAGENT_DEPTH) {
 				const agentName = process.env.PI_CURRENT_AGENT_NAME || "current agent";
 				return {
 					content: [{
 						type: "text",
-						text: `Subagent delegation is blocked: depth limit reached (depth: ${currentDepth}, max: ${MAX_SUBAGENT_DEPTH}). Agent \`${agentName}\` runs inside a subagent and recursive delegation is not allowed.`,
+						text: `Subagent tool is blocked: depth limit reached (depth: ${currentDepth}, max: ${MAX_SUBAGENT_DEPTH}). Agent \`${agentName}\` runs inside a subagent and cannot invoke subagent actions (dispatch/status/cancel).`,
 					}],
 					details: {
 						mode: "single",
-						agentScope: params.agentScope ?? "both",
+						agentScope: (params.agentScope ?? "both") as AgentScope,
+						projectAgentsDir: null,
+						results: [],
+					} as SubagentDetails,
+					isError: true,
+				};
+			}
+
+			if (action === "status") {
+				return {
+					content: [{ type: "text", text: formatActiveTasks() }],
+					details: { activeTasks: [...taskRegistry.values()].filter((t) => t.status === "running").map((t) => t.taskId) },
+				};
+			}
+
+			if (action === "cancel") {
+				const taskId = typeof params.taskId === "string" ? params.taskId.trim() : "";
+				if (!taskId) {
+					return {
+						content: [{ type: "text", text: 'Missing or empty required parameter: "taskId" (taskId 必填，不能为空).' }],
+						details: { taskId: "", cancelled: false },
+						isError: true,
+					};
+				}
+				// Only registry (async/TUI) tasks are cancellable; sync-mode tasks are
+				// awaited inline and never enter the registry.
+				if (!cancelTask(taskId, "agent")) {
+					return {
+						content: [{ type: "text", text: `无此运行中任务: ${taskId} (no running subagent task with this id).` }],
+						details: { taskId, cancelled: false },
+						isError: true,
+					};
+				}
+				return {
+					content: [{ type: "text", text: `已发送取消请求: ${taskId} (cancel request sent); 结果稍后以 [subagent-result] 通知返回。\n${formatActiveTasks()}` }],
+					details: { taskId, cancelled: true },
+				};
+			}
+
+			if (action !== "dispatch") {
+				return {
+					content: [{ type: "text", text: `Invalid action: "${action}". Must be one of "dispatch" (default), "status", "cancel".` }],
+					details: {
+						mode: "single",
+						agentScope: (params.agentScope ?? "both") as AgentScope,
 						projectAgentsDir: null,
 						results: [],
 					} as SubagentDetails,
@@ -1826,7 +1921,7 @@ export default function (pi: ExtensionAPI) {
 				};
 			}
 
-			progressManager.register(ctx, effectiveSessionId, params.agent);
+			progressManager.register(ctx, effectiveSessionId, agentName);
 
 			// TUI mode: dispatch asynchronously. execute() returns a receipt
 			// immediately; the finished result is pushed later as a
@@ -1835,7 +1930,7 @@ export default function (pi: ExtensionAPI) {
 			if (ctx.mode === "tui") {
 				const taskRecord: AsyncSubagentTask = {
 					taskId: effectiveSessionId,
-					agentName: params.agent,
+					agentName,
 					task,
 					startedAt: Date.now(),
 					// Per-task controller: the turn-level `signal` fires when the
@@ -1848,7 +1943,7 @@ export default function (pi: ExtensionAPI) {
 				runSingleAgent(
 					ctx.cwd,
 					agents,
-					params.agent,
+					agentName,
 					task,
 					params.cwd,
 					undefined,
@@ -1878,7 +1973,7 @@ export default function (pi: ExtensionAPI) {
 					(err) => completeAsyncTask(pi, taskRecord, null, err),
 				);
 				return {
-					content: [{ type: "text", text: buildDispatchReceipt(params.agent, effectiveSessionId) }],
+					content: [{ type: "text", text: buildDispatchReceipt(agentName, effectiveSessionId) }],
 					details: makeDetails([]),
 				};
 			}
@@ -1887,7 +1982,7 @@ export default function (pi: ExtensionAPI) {
 				const result = await runSingleAgent(
 					ctx.cwd,
 					agents,
-					params.agent,
+					agentName,
 					task,
 					params.cwd,
 					undefined,
@@ -1936,8 +2031,11 @@ export default function (pi: ExtensionAPI) {
 
 		renderResult(result, { expanded }, theme, context) {
 			const details = result.details as SubagentDetails | undefined;
-			if (!details || details.results.length === 0) {
-				return new Text(result.content[0]?.type === "text" ? result.content[0].text : "(no output)", 0, 0);
+			// status/cancel receipts carry no `results` array (activeTasks /
+			// taskId+cancelled instead) — fall back to the plain-text content
+			// instead of throwing on details.results.length.
+			if (!details || !Array.isArray(details.results) || details.results.length === 0) {
+				return new Text(result.content?.[0]?.type === "text" ? result.content[0].text : "(no output)", 0, 0);
 			}
 
 			const mdTheme = getMarkdownTheme();
@@ -2034,80 +2132,6 @@ export default function (pi: ExtensionAPI) {
 		}
 	});
 
-	// Read-only in-flight query. Results still arrive automatically as
-	// [subagent-result] notifications; this tool exists only to confirm which
-	// tasks are still running (e.g. after a /tree rewind wiped the receipts).
-	pi.registerTool({
-		name: "subagent_status",
-		label: "Subagent Status",
-		description: [
-			"List currently running background subagent tasks (在途任务: taskId、agent、任务描述).",
-			"Results arrive automatically as [subagent-result] notifications — do NOT use",
-			"this tool to poll for completion. Use it only to confirm which tasks are still",
-			"in flight (e.g. after a /tree rewind), or to pick a taskId for subagent_cancel.",
-		].join("\n"),
-		promptSnippet:
-			"List in-flight background subagent tasks (not for polling — results arrive as [subagent-result] notifications).",
-		parameters: Type.Object({}),
-
-		async execute() {
-			return {
-				content: [{ type: "text", text: formatActiveTasks() }],
-				details: { activeTasks: [...taskRegistry.values()].filter((t) => t.status === "running").map((t) => t.taskId) },
-			};
-		},
-	});
-
-	// Cancellation has two paths sharing cancelTask (which reuses the SIGTERM
-	// -> 5s -> SIGKILL abort cascade and records who cancelled on the task so
-	// the result envelope can name the origin): the main agent's subagent_cancel
-	// tool below, and the user's /subagent-cancel command.
-	pi.registerTool({
-		name: "subagent_cancel",
-		label: "Subagent Cancel",
-		description: [
-			"Cancel a running background subagent task (取消一个仍在运行的后台 subagent 任务) by taskId.",
-			"Use only when the task 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.",
-		].join("\n"),
-		promptSnippet:
-			"Cancel a running background subagent task by taskId (only when it is clearly wrong or no longer needed).",
-		promptGuidelines: [
-			"subagent_cancel: Cancel a background subagent task only when it is clearly wrong or no longer needed — never cancel merely because it is taking long; the cancellation arrives later as a [subagent-result] notification with status 已取消 (cancelled).",
-		],
-		parameters: Type.Object({
-			taskId: Type.String({
-				description: "taskId of the running background subagent task to cancel (from the subagent dispatch receipt).",
-			}),
-		}),
-
-		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-			const taskId = typeof params.taskId === "string" ? params.taskId.trim() : "";
-			if (!taskId) {
-				return {
-					content: [{ type: "text", text: 'Missing or empty required parameter: "taskId" (taskId 必填，不能为空).' }],
-					details: { taskId: "", cancelled: false },
-					isError: true,
-				};
-			}
-			// Only registry (async/TUI) tasks are cancellable; sync-mode tasks are
-			// awaited inline and never enter the registry.
-			if (!cancelTask(taskId, "agent")) {
-				return {
-					content: [{ type: "text", text: `无此运行中任务: ${taskId} (no running subagent task with this id).` }],
-					details: { taskId, cancelled: false },
-					isError: true,
-				};
-			}
-			return {
-				content: [{ type: "text", text: `已发送取消请求: ${taskId} (cancel request sent); 结果稍后以 [subagent-result] 通知返回。\n${formatActiveTasks()}` }],
-				details: { taskId, cancelled: true },
-			};
-		},
-	});
-
 	// /subagent-cancel <taskId> is the user's cancel path.
 	// (Optional-call guards keep minimal mock `pi` objects in tests working.)
 	pi.registerCommand?.("subagent-cancel", {