maestro/docs/tools/askuser.md

AskUser

ユーザーに選択肢つきで質問し、回答があるまでタスクを停車する park ツール。

いつ使うか

• 指示が曖昧で、進め方の分岐を自分で列挙できるとき（デプロイ先、対象範囲、形式の選択など）
• Mission Brief と今回の指示がずれて見え、どちらに従うべきか確認したいとき
• 複数の論点をまとめて確認したいとき（1 回の停車で最大 4 問）

いつ使わないか

• 選択肢を作れない開放的な質問（「何をお望みですか？」）→ complete({status:"needs_user_input", missing_info})
• 自明な既定値があり、進めてから報告すれば足りる場合 → 質問せず進める
• subtask 実行 → 利用不可（degrade メッセージが返る）。自明な選択肢で進めるか complete で報告

書き方

{
  "questions": [
    {
      "question": "デプロイ先はどちらにしますか？",
      "header": "デプロイ先",
      "options": [
        { "label": "本番", "description": "即時反映。ロールバック可" },
        { "label": "ステージング", "description": "検証後に手動昇格" }
      ],
      "multiSelect": false
    }
  ]
}

• 選択肢は 2〜6 個・相互排他に。網羅しようとせず、迷う候補は入れずに自由記述（UI が常に追加する「その他」）に任せる
• question は文脈を含め単体で意味が通るように。ユーザーは会話全体を読み直さない
• header はカードの短いラベル。省略可

挙動

• 呼ぶとタスクは停車（waiting_human）し、ワーカーは解放される。ツール内で回答を待たない
• 回答は次の再開時にユーザーメッセージとして届く（「見出し: 選択」の平文）
• ASK 上限は停車 1 回で 1 消費（質問数ではない）。上限は askPolicy 設定に従う
• 回答を受けたら、決定事項を MissionUpdate の decisions / clarifications に記録すること