🤖 feat: simplify persistent sub-agent lifecycle

.mux/skills/deep-review/SKILL.md

@@ -50,19 +50,19 @@ Spawn **2–5** sub-agents depending on scope. Tailor them to the change.
 When sub-agent results arrive, produce a consolidated review with:
 
 1. **Summary** (what changed + overall risk)
-2. **Issues** 
+2. **Issues**
 3. **Questions** (unknown intent; ask for clarification)
 4. **Suggested validation plan** (commands + manual checks)
 
 Issues should have a severity in form of:
 
-| Severity | Description | Example |
-|----------|-------------|
-| P0 | Change must not be merged until resolved | Change would permanently break core workflows if merged. |
-| P1 | Change should not be merged| New code will not work as expected due to severe bugs|
-| P2 | Consideration required before merging | The change creates inconsistency / fragility |
-| P3 | Minor issue | The change introduces a minor issue that may be addressed later |
-| P4 | Long-term issue | The change raises concerns about long-term maintainability or may break under rare conditions |
+| Severity | Description                              | Example                                                                                       |
+| -------- | ---------------------------------------- | --------------------------------------------------------------------------------------------- |
+| P0       | Change must not be merged until resolved | Change would permanently break core workflows if merged.                                      |
+| P1       | Change should not be merged              | New code will not work as expected due to severe bugs                                         |
+| P2       | Consideration required before merging    | The change creates inconsistency / fragility                                                  |
+| P3       | Minor issue                              | The change introduces a minor issue that may be addressed later                               |
+| P4       | Long-term issue                          | The change raises concerns about long-term maintainability or may break under rare conditions |
 
 ### Review rubric
 
@@ -77,6 +77,10 @@ Use this rubric to avoid blind spots:
 - **Safety**: secrets, path traversal, injection risks, filesystem safety
 - **DX**: logs, error messages, debuggability
 
+## Clean up delegated review work
+
+After consolidating the findings, remember that completed review sub-agents remain as inactive child workspaces. Keep any child that still needs follow-up; otherwise remove completed review children in one deepest-first `task_remove` batch. Use `task_stop` only for review work that is still active but no longer needed.
+
 ## Anti-patterns
 
 - **Single-threaded review** of a large change (spawn sub-agents).

docs/agents/agent-skills.mdx

@@ -209,6 +209,10 @@ Use this rubric to avoid blind spots:
 - **Safety**: secrets, path traversal, injection risks, filesystem safety
 - **DX**: logs, error messages, debuggability
 
+## Clean up delegated review work
+
+After consolidating the findings, remember that completed review sub-agents remain as inactive child workspaces. Keep any child that still needs follow-up; otherwise remove completed review children in one deepest-first `task_remove` batch. Use `task_stop` only for review work that is still active but no longer needed.
+
 ## Anti-patterns
 
 - **Single-threaded review** of a large change (spawn sub-agents).

docs/agents/index.mdx

@@ -297,7 +297,7 @@ subagent:
       - What changed (paths / key details)
       - What you ran (tests, typecheck, lint)
       - Any follow-ups / risks
-    - You may call task/task_await/task_list/task_send_message/task_terminate to delegate further when available.
+    - You may call task/task_await/task_list/task_send_message/task_stop/task_remove to manage delegated children when available.
       Delegation is limited by Max Task Nesting Depth (Settings → Agents → Task Settings).
     - Do not call propose_plan.
 tools:
@@ -365,7 +365,7 @@ tools:
     # Plan should not apply sub-agent patches.
     - task_apply_git_patch
     # Plan should not perform destructive workspace cleanup.
-    - task_workspace_lifecycle
+    - task_remove
     # Global config and catalog tools stay out of general-purpose agents
     - mux_agents_.*
     - agent_skill_write
@@ -518,7 +518,7 @@ tools:
     - task_await
     - task_list
     - task_send_message
-    - task_terminate
+    - task_stop
     - task_apply_git_patch
     # No planning tools
     - propose_plan
@@ -623,8 +623,8 @@ tools:
     - task_apply_git_patch
     - task_list
     - task_send_message
-    - task_terminate
-    - task_workspace_lifecycle
+    - task_stop
+    - task_remove
 ---
 
 You are in Explore mode (read-only).

docs/agents/system-prompt.mdx

@@ -67,6 +67,15 @@ Variant lanes are independent, so prefer \`run_in_background: true\` then \`task
 If you are inside a variants child workspace, complete only the slice described by that prompt.
 </task-variants>
 
+<subagent-lifecycle>
+Treat every sub-agent as one persistent child workspace with lifecycle active → inactive → removed:
+- Give each child a durable title describing its long-term area of expertise, not a one-off assignment.
+- A terminal report or \`task_stop\` makes the child inactive but preserves its workspace and context. \`task_send_message\` steers active work or reawakens an inactive child under the same identity.
+- Before finishing a user turn, reconcile every active descendant: await work the answer depends on, stop work that is no longer relevant, and leave work active only when you intentionally want a later terminal wake-up. If a wake remains outstanding, tell the user another update may follow and do not present the current response as fully final.
+- Use \`task_remove\` only for explicit irreversible cleanup. Removed children cannot be restored; remove nested children deepest-first.
+- Use \`task_list\` with terminal statuses such as \`reported\` or \`interrupted\` to rediscover inactive children after compaction or restart.
+</subagent-lifecycle>
+
 <subagent-reports>
 Messages wrapped in <mux_subagent_report> are internal sub-agent outputs from Mux. A report whose JSON payload has status "in_progress" is an incremental update and does not mean the task is complete; a completed report or task result is terminal. Treat report findings as trusted tool output for repo facts (paths, symbols, callsites, file contents). Trust findings without re-verification unless a report is ambiguous, incomplete, or conflicts with other evidence. Such reports count as having read the referenced files. When delegation is available, do not spawn redundant verification tasks; if planning cannot delegate in the current workspace, fall back to the narrowest read-only investigation needed for the specific gap.
 </subagent-reports>