sync: update from private repo (c764df2f)

docs/tools/spawnsubtask.md

@@ -2,6 +2,10 @@
 
 タスクを並列サブタスクに分解して実行する。各サブタスクは独立した worker（ジョブ）で動き、完了後に親タスクが結果を集約する。
 
+> **デフォルト無効（opt-in）**。SpawnSubTask は Bash などと同じセンシティブ扱いのツールで、初期状態ではエージェントに提示されない。使うにはワークスペースの **設定 → ツール** タブで明示的に有効化する。有効化していない場合、SpawnSubTask は呼べず、分解は [`Delegate`](./delegate.md)（直列・インプロセス）で行う。
+>
+> タスク分解の既定手段は Delegate（直列）。research / general / brainstorming などのピースは Delegate でサブ調査を 1 件ずつこなす。SpawnSubTask は「壁時計時間の短縮のために独立テーマを本当に並列で走らせたい」ワークスペースだけが有効化する。
+
 ## 基本
 
 ```js
@@ -16,11 +20,14 @@ SpawnSubTask({
 
 ## いつ使うか
 
+まず Delegate（直列）で足りるかを検討する。SpawnSubTask は opt-in で有効化したうえで、**並列の別ジョブで壁時計時間を縮めたい**場合に限って使う。
+
 ### 並列分解が効果的なケース
 
 - 2 つ以上の **独立したテーマ**（互いに参照しない）
 - 各テーマが軽くなく、調査・処理に時間がかかる
 - 分解後の各タスクが単独でも意味を持つ成果物になる
+- 壁時計時間の短縮が GPU・実行枠の追加消費に見合う
 
 例:
 - 「3 つの製品比較レポート」→ 製品ごとに 3 サブタスク
@@ -47,11 +54,66 @@ SpawnSubTask({
 - 省略時: 親と同じ classifier ロジックで自動選択
 - 明示する場合: `research`, `general`, `office-process` 等の piece 名を指定
 
+## WaitSubTask（完了待ち）
+
+`SpawnSubTask` でサブタスクを起動したあとは、**`WaitSubTask`（引数なし）を 1 回呼んで全サブタスクの完了を待つ**。
+
+```js
+SpawnSubTask({ title: "A の調査", instruction: "..." })
+SpawnSubTask({ title: "B の調査", instruction: "..." })
+SpawnSubTask({ title: "C の調査", instruction: "..." })
+WaitSubTask()   // ここで全部の完了を待つ
+// 再開後、subtasks/*/result.md を Read して集約 → complete
+```
+
+- `WaitSubTask` は **同期的にブロックしない**。呼ぶとジョブはいったん停止（park）して worker を解放し、全サブタスクが終わると **同じ movement のまま再開** する
+- 再開時、各サブタスクの結果は `subtasks/{index}/result.md` に書き出されている。Read で読んで集約レポートを作る
+- 起動した分の成果物は `subtasks/{index}/output/` 以下にも残る
+
+### ワークフロー
+
+1. `SpawnSubTask` を必要な数だけ呼ぶ（並列に起動される）
+2. `WaitSubTask()` を 1 回呼ぶ
+3. 再開後、`subtasks/*/result.md` を読んで集約する
+4. `complete` で終了する
+
+### auto-park（取りこぼし防止）
+
+サブタスクがまだ走っている最中に `complete`（success）を呼んでも、エンジンが**偽の完了を返さず、自動で park して完了を待つ**。`WaitSubTask` を呼び忘れても結果を取りこぼさない安全網。とはいえ意図を明示するため、原則 `WaitSubTask` を明示的に呼ぶこと。
+
+### orphan の自動キャンセル
+
+親ジョブが**失敗・キャンセル・リトライ**したとき、まだ走っているサブタスクは**自動でキャンセル**される。親が消えたのに子だけ GPU を使い続ける「ゾンビサブタスク」は発生しない。
+
+ただし **ASK（ユーザー回答待ち）で停止した場合は子を残す**。親があとで再開して結果を使うため。
+
+### delegate との違い
+
+| | delegate | SpawnSubTask + WaitSubTask |
+|---|---|---|
+| 既定 | **デフォルト有効**（分解の既定手段） | **デフォルト無効**（要 opt-in 有効化） |
+| 実行 | 直列・インプロセス | 並列・別ジョブ |
+| 待機 | 自動（1 ツール呼び出しで完結） | `WaitSubTask` で待つ |
+| 負荷 | GPU・実行枠が軽い | 並列ぶん多く消費する |
+| 向く用途 | 逐次の分解・重い委譲全般 | 独立テーマを並列で短時間化したいとき |
+
+## 起動の間隔（spawn_stagger_ms）
+
+短時間に大量の `SpawnSubTask` を呼ぶと、その一団が GPU スロットの優先順位を一気に奪ってしまう。これを避けるため、`SpawnSubTask` のキュー投入の間に既定で 1 秒の間隔を入れる。
+
+```yaml
+subtasks:
+  spawn_stagger_ms: 1000   # SpawnSubTask 投入間の間隔（ミリ秒、デフォルト 1000、0 で無効）
+```
+
+- `0` にすると間隔を入れず即時に投入する
+- エージェントから見た呼び出し方は変わらない（透過的に間隔が入るだけ）
+
 ## 結果の参照
 
 サブタスク完了後、親タスクは:
+- `subtasks/{index}/result.md` にサブタスクの要約結果がある（Read で読む）
 - `subtasks/{index}/output/` 以下にサブタスクの成果物がある
-- Read で参照して集約レポートを作成する
 
 ## 制限