Merge branch 'claudedo/0733742e0da8407d8e2be1bc5886bf9b'

docs/explore-notes/external-mcp.md

@@ -123,9 +123,9 @@ failing item never aborts the rest — and rejects batches over **100 items**.
 
 **`GetTaskLog`** — latest run's log, tail-capped at 256 KB.
 
-**`WaitForTaskChange(taskIds, timeoutSeconds = 60)`** — blocks until any given task leaves
-`Queued`/`Running`, or times out. Returns immediately for a task already outside those two
-(unknown ids reported as status `"NotFound"`, also immediate).
+**`WaitForTaskChange(taskIds, timeoutSeconds = 60, treatWaitingForChildrenAsBusy = false)`** —
+blocks until any given task leaves `Queued`/`Running`, or times out. Returns immediately for a
+task already outside those two (unknown ids reported as status `"NotFound"`, also immediate).
 - Implemented as an **async DB poll** (short-lived `DbContext` per check, 500 ms delay, no
   held connection, no busy loop) rather than hooking `HubBroadcaster` — deliberately isolated
   so it can't regress the existing broadcast callers.
@@ -136,6 +136,13 @@ failing item never aborts the rest — and rejects batches over **100 items**.
   `timedOut: true` instead of racing the client's own abort. A caller running claude with a
   different (or default: 60 s) `MCP_TOOL_TIMEOUT` will still see its own client-side timeout
   fire first; the server has no way to detect or compensate for that.
+- **`treatWaitingForChildrenAsBusy` pitfall (default `false`, backward-compatible):** a planning
+  parent with children goes `Running` → `WaitingForChildren` while children are still working,
+  and by default that already counts as "changed" (it's outside `Queued`/`Running`) — so waiting
+  on a parent returns immediately even though the unit isn't done. Set the flag to keep polling
+  through `WaitingForChildren`; the call then only reports changed once the parent reaches
+  `WaitingForReview` or a terminal status. Does not list or watch the parent's children —
+  callers still need their own ids for that.
 - Replaced the list handler's old "sleep + poll `get_task` in a loop" Phase 3 instruction.
 
 **`GetQueueState()`** — read-only snapshot so a caller doesn't have to infer queue state from