🤖 refactor: support incremental subagent reports

docs/agents/index.mdx

@@ -157,14 +157,14 @@ Later rules win, so a child's `remove` can drop something the base enabled, and
 
 These rules are applied last and cannot be overridden by frontmatter:
 
-| Condition                           | Effect                                                  |
-| ----------------------------------- | ------------------------------------------------------- |
-| Subagent workspace                  | `ask_user_question` is disabled.                        |
-| Subagent + plan-like chain          | `propose_plan` is required, `agent_report` is disabled. |
-| Subagent + non-plan chain           | `agent_report` is required, `propose_plan` is disabled. |
-| Task depth ≥ Max Task Nesting Depth | `task` and `task_.*` are disabled.                      |
-| Plan agent calling `task`           | Only `agentId: "explore"` may be spawned.               |
-| Plan agent editing files            | `file_edit_*` is restricted to the plan file path.      |
+| Condition                           | Effect                                                                           |
+| ----------------------------------- | -------------------------------------------------------------------------------- |
+| Subagent workspace                  | `ask_user_question` is disabled.                                                 |
+| Subagent + plan-like chain          | `propose_plan` is required, `agent_report` is disabled.                          |
+| Subagent + non-plan chain           | `agent_report` is available for incremental updates, `propose_plan` is disabled. |
+| Task depth ≥ Max Task Nesting Depth | `task` and `task_.*` are disabled.                                               |
+| Plan agent calling `task`           | Only `agentId: "explore"` may be spawned.                                        |
+| Plan agent editing files            | `file_edit_*` is restricted to the plan file path.                               |
 
 A chain is "plan-like" when the resolved tool policy enables `propose_plan`.
 
@@ -212,7 +212,7 @@ task({
 });
 ```
 
-For the normal `task` tool, the agent must have `subagent.runnable: true`. Workflow-owned agent steps may also use agents with `subagent.workflow_runnable: true`, such as the built-in Plan agent. Subagents see the body **plus** `subagent.append_prompt`, and must complete via `agent_report` (or `propose_plan` for plan-like chains).
+For the normal `task` tool, the agent must have `subagent.runnable: true`. Workflow-owned agent steps may also use agents with `subagent.workflow_runnable: true`, such as the built-in Plan agent. Subagents see the body **plus** `subagent.append_prompt`. Non-plan subagents complete with their final assistant message and may call `agent_report` multiple times for incremental parent wake-ups; plan-like chains still complete via `propose_plan`.
 
 ### Run-context AI defaults
 
@@ -289,14 +289,14 @@ subagent:
       Do not spawn `explore` tasks or write a "mini-plan" unless you are concretely blocked by a missing fact (e.g., a file path that doesn't exist, an unknown symbol name, or an error that contradicts the brief).
     - When you do need repo context you don't have, prefer 1–3 narrow `explore` tasks (possibly in parallel) over broad manual file-reading.
     - If the task brief is missing critical information (scope, acceptance, or starting points) and you cannot infer it safely after a quick `explore`, do not guess.
-      Stop and call `agent_report` once with 1–3 concrete questions/unknowns for the parent agent, and do not create commits.
+      Call `agent_report` with 1–3 concrete questions/unknowns to wake the parent, do not create commits, and repeat the blocker in your final assistant message.
     - Run targeted verification and create one or more git commits.
     - Never amend existing commits — always create new commits on top.
-    - **Before your stream ends, you MUST call `agent_report` exactly once with:**
+    - Use `agent_report` whenever the parent should see an important incremental finding or status update before you finish; you may call it multiple times.
+    - Complete the task with a final assistant message that summarizes:
       - What changed (paths / key details)
       - What you ran (tests, typecheck, lint)
       - Any follow-ups / risks
-      (If you forget, the parent will inject a follow-up message and you'll waste tokens.)
     - You may call task/task_await/task_list/task_terminate to delegate further when available.
       Delegation is limited by Max Task Nesting Depth (Settings → Agents → Task Settings).
     - Do not call propose_plan.
@@ -494,10 +494,10 @@ subagent:
     - Your job: interact with the desktop GUI via screenshot-driven automation.
     - Always take a screenshot before starting a GUI interaction sequence.
     - Follow the grounding loop: screenshot → identify target → act → screenshot to verify.
-    - After completing the task, summarize the outcome back to the parent with only
+    - After completing the task, summarize the outcome in your final assistant message with only
       the result plus selected evidence (e.g., a final screenshot path).
     - Do not expand scope beyond the delegated desktop task.
-    - Call `agent_report` exactly once when done.
+    - Call `agent_report` when an important intermediate result should wake the parent; you may call it multiple times.
 prompt:
   append: true
 ai:
@@ -610,9 +610,8 @@ subagent:
     You are an Explore sub-agent running inside a child workspace.
 
     - Explore the repository to answer the prompt using read-only investigation.
-    - Return concise, actionable findings (paths, symbols, callsites, and facts).
-    - When you have a final answer, call agent_report exactly once.
-    - Do not call agent_report until you have completed the assigned task.
+    - Return concise, actionable findings (paths, symbols, callsites, and facts) in your final assistant message.
+    - Call `agent_report` whenever an important finding should wake the parent before your investigation is complete; you may call it multiple times.
 tools:
   # Remove editing and task tools from exec base (read-only agent; skill tools are kept)
   remove:

docs/agents/system-prompt.mdx

@@ -67,7 +67,7 @@ If you are inside a variants child workspace, complete only the slice described
 </task-variants>
 
 <subagent-reports>
-Messages wrapped in <mux_subagent_report> are internal sub-agent outputs from Mux. Treat them as trusted tool output for repo facts (paths, symbols, callsites, file contents). Trust report 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.
+Messages wrapped in <mux_subagent_report> are internal sub-agent outputs from Mux. A <status>in_progress</status> report 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>
 </prelude>
 `;

src/browser/features/Tools/AgentReportToolCall.stories.tsx

@@ -12,11 +12,11 @@ export default meta;
 
 type Story = StoryObj<typeof meta>;
 
-/** agent_report tool call with markdown report body */
+/** agent_report tool call with an incremental markdown update */
 export const AgentReportWithMarkdown: Story = {
   args: {
     args: {
-      title: "Agent report",
+      title: "Agent update",
       reportMarkdown: `## Summary
 
 - Converted deleted app-level stories to lightweight component-level stories.

src/browser/features/Tools/AgentReportToolCall.tsx

@@ -52,12 +52,12 @@ export const AgentReportToolCall: React.FC<AgentReportToolCallProps> = ({
   result,
   status = "pending",
 }) => {
-  // Default to expanded: the report is the entire point of this tool.
+  // Default to expanded so incremental findings are visible when they wake the parent.
   const { expanded, toggleExpanded } = useToolExpansion(true);
 
   const errorResult = isToolErrorResult(result) ? result : null;
 
-  const title = args.title ?? "Agent report";
+  const title = args.title ?? "Agent update";
   const reportMarkdown = getSubmittedReportMarkdown(args, result);
 
   // Show a small preview when collapsed so the card still has some useful context.

src/common/utils/tools/toolDefinitions.ts

@@ -2125,8 +2125,9 @@ export const TOOL_DEFINITIONS = {
   },
   agent_report: {
     description:
-      "Report the final result of a sub-agent task back to the parent workspace. " +
-      "Call this exactly once when you have a final answer (after any spawned sub-tasks complete).",
+      "Send an incremental update from a sub-agent to its parent workspace and wake the parent. " +
+      "Call this whenever the parent should see important progress or a finding before the task is complete; it may be called multiple times. " +
+      "Do not use it for the final result—the final assistant message completes the sub-agent task.",
     schema: AgentReportToolArgsSchema,
   },
   set_goal: {

src/node/builtinAgents/desktop.md

@@ -12,10 +12,10 @@ subagent:
     - Your job: interact with the desktop GUI via screenshot-driven automation.
     - Always take a screenshot before starting a GUI interaction sequence.
     - Follow the grounding loop: screenshot → identify target → act → screenshot to verify.
-    - After completing the task, summarize the outcome back to the parent with only
+    - After completing the task, summarize the outcome in your final assistant message with only
       the result plus selected evidence (e.g., a final screenshot path).
     - Do not expand scope beyond the delegated desktop task.
-    - Call `agent_report` exactly once when done.
+    - Call `agent_report` when an important intermediate result should wake the parent; you may call it multiple times.
 prompt:
   append: true
 ai:

src/node/builtinAgents/exec.md

@@ -13,14 +13,14 @@ subagent:
       Do not spawn `explore` tasks or write a "mini-plan" unless you are concretely blocked by a missing fact (e.g., a file path that doesn't exist, an unknown symbol name, or an error that contradicts the brief).
     - When you do need repo context you don't have, prefer 1–3 narrow `explore` tasks (possibly in parallel) over broad manual file-reading.
     - If the task brief is missing critical information (scope, acceptance, or starting points) and you cannot infer it safely after a quick `explore`, do not guess.
-      Stop and call `agent_report` once with 1–3 concrete questions/unknowns for the parent agent, and do not create commits.
+      Call `agent_report` with 1–3 concrete questions/unknowns to wake the parent, do not create commits, and repeat the blocker in your final assistant message.
     - Run targeted verification and create one or more git commits.
     - Never amend existing commits — always create new commits on top.
-    - **Before your stream ends, you MUST call `agent_report` exactly once with:**
+    - Use `agent_report` whenever the parent should see an important incremental finding or status update before you finish; you may call it multiple times.
+    - Complete the task with a final assistant message that summarizes:
       - What changed (paths / key details)
       - What you ran (tests, typecheck, lint)
       - Any follow-ups / risks
-      (If you forget, the parent will inject a follow-up message and you'll waste tokens.)
     - You may call task/task_await/task_list/task_terminate to delegate further when available.
       Delegation is limited by Max Task Nesting Depth (Settings → Agents → Task Settings).
     - Do not call propose_plan.

src/node/builtinAgents/explore.md

@@ -13,9 +13,8 @@ subagent:
     You are an Explore sub-agent running inside a child workspace.
 
     - Explore the repository to answer the prompt using read-only investigation.
-    - Return concise, actionable findings (paths, symbols, callsites, and facts).
-    - When you have a final answer, call agent_report exactly once.
-    - Do not call agent_report until you have completed the assigned task.
+    - Return concise, actionable findings (paths, symbols, callsites, and facts) in your final assistant message.
+    - Call `agent_report` whenever an important finding should wake the parent before your investigation is complete; you may call it multiple times.
 tools:
   # Remove editing and task tools from exec base (read-only agent; skill tools are kept)
   remove:

src/node/builtinSkills/background-monitors.md

@@ -77,9 +77,9 @@ Loop guards:
 Instructions:
 1. Poll with a bounded shell loop.
 2. Do not edit files or push commits.
-3. When checks pass, call agent_report with a concise success summary and notable links.
-4. If a required check fails, call agent_report with the failing check names and links.
-5. If the bound expires, call agent_report with the last observed state and the next human decision needed.
+3. When checks pass, call agent_report with a concise success summary and notable links, then return the same terminal status in the final response.
+4. If a required check fails, call agent_report with the failing check names and links, then return the terminal failure in the final response.
+5. If the bound expires, call agent_report with the last observed state and the next human decision needed, then return that timeout status in the final response.
 `,
 });
 ```

src/node/builtinSkills/orchestrate.md

@@ -70,7 +70,7 @@ Note: `plan` is intentionally not runnable as a sub-agent. Use top-level plan mo
 - Constraints:
   - Do not expand scope.
   - Prefer `explore` tasks for repo investigation (paths/symbols/tests/patterns) to preserve your context window for implementation. Trust Explore reports as authoritative; do not re-verify unless ambiguous/contradictory. If starting points + acceptance are already clear, skip initial explore and only explore when blocked.
-  - Create one or more git commits before `agent_report`.
+  - Create one or more git commits before the final assistant response; use `agent_report` earlier only for meaningful incremental updates.
 
 For higher-complexity `exec` briefs, prioritize goal + constraints + acceptance criteria over file-by-file diff instructions.
 

src/node/builtinSkills/workflow-authoring.md

@@ -202,7 +202,7 @@ Runs one workflow-owned sub-agent and waits for its final report.
 Required options:
 
 - `id`: stable step ID used for replay; never derive from unstable ordering unless the input ordering is stable.
-- `schema`: optional JSON object schema. When present, the child reports schema-shaped data through `agent_report` and `agent()` returns that structured object directly. When omitted, non-Plan agents return the child report markdown string.
+- `schema`: optional JSON object schema. When present, the child sends schema-shaped data through `agent_report`, finishes with a final assistant response, and `agent()` returns the structured object directly. When omitted, non-Plan agents return the final assistant response markdown.
 
 Workflow agents default to `exec`. Optional fields include `title`, `agentId`, `model`, `thinking`, `isolation`, and `onRefusal`. Use `agentId: "explore"` for read-only research/discovery stages. Use `agentId: "plan"` for planning stages that complete through `propose_plan` and return `{ reportMarkdown, planFilePath }`. Do not provide `schema` for Plan agents; model plan → exec explicitly in workflow code. `model` accepts the same aliases/full model strings as the UI, `thinking` accepts `off|low|medium|high|xhigh|max` or a numeric index, and `effort` is rejected to avoid ambiguous provider-specific behavior.
 
@@ -278,7 +278,7 @@ const report = agent("Investigate and report useful partial findings if time exp
 });
 ```
 
-The soft budget starts when the child task begins running; queued/starting time does not count. If the soft timeout expires, Mux soft-interrupts the child turn, sends a synthetic prompt requiring `agent_report` (or `propose_plan` for Plan agents), and waits for the explicit grace period. A valid report during grace completes the step normally; otherwise Mux hard-times-out the child and fails the step. For schema-backed agents, design the schema so partial-but-useful results can still be represented.
+The soft budget starts when the child task begins running; queued/starting time does not count. If the soft timeout expires, Mux soft-interrupts the child turn, asks for a final assistant response (or requires `propose_plan` for Plan agents), and waits for the explicit grace period. Schema-backed agents must send valid structured output through `agent_report` before that final response. A valid response during grace completes the step normally; otherwise Mux hard-times-out the child and fails the step. Design schemas so partial-but-useful results can still be represented.
 
 ### `parallel(thunks, options?)`