maestro/docs/tools/requestcaptchahelp.md

RequestCaptchaHelp

検索が「人かどうかの確認（CAPTCHA）」で完全に塞がれたときに、人が確認を済ませるまで作業を止めて待つためのツール（issue #1199 段階 2）。

いつ使うか

WebSearch がこの形で失敗したときだけ:

WebSearch error: ブラウザ検索がすべて CAPTCHA で止められ、SearXNG も結果を返しませんでした。
検索そのものが実行できていません。

そのうえで、検索なしではその依頼を達成できないときに呼ぶ。

呼ぶ前に確かめること:

• URL が分かっているなら WebFetch で直接開けば済まないか
• すでに手元にある資料や Read で足りないか
• 検索がそもそも本筋でない依頼ではないか（雑談・要約・書き換えなど）

止まっているあいだ、利用者は確認画面を開いて操作する必要がある。避けられるなら避けたい手間なので、他に道が無いときだけ呼ぶこと。

引数

引数	必須	説明
reason	いいえ	検索が通らないと進められない理由。カードを見る人が読む

呼んだあと何が起きるか

1. その movement が畳まれ、ジョブが「人の確認待ち」で停車する（ワーカーは解放される）
2. 確認カードが出るのは元のタスクのチャット。サブタスクの中で呼んだ場合も、親をたどった先の元のタスクへ出る（#1225）
3. 誰かが確認を済ませて「解決した」を押すと、その確認画面で止まっているジョブがまとめて再開する
4. 「スキップ」を押した場合は、押したタスクのジョブとその配下で確認待ちのサブタスクだけが、検索が使えないまま再開する
5. 再開すると同じステップの頭からやり直しになるので、もう一度 WebSearch を呼ぶこと

止まらないことがある

次のときは停車せず、エラーとして「続けてください」が返る。呼べば必ず止まるツールではない。

返る内容	意味
この実行では人の確認を待てません	親をたどっても元のタスクに行き着かない実行（チャットに紐づかない実行）。確認カードを出す先が無いので、止めても押す相手が居ない。検索抜きで組み立てるか complete で中断する
まだ検索が塞がっていません	この実行の WebSearch が上のエラーで失敗していない。SearXNG 経由で結果が出ているなら塞がっていない
未解決の求めは残っていません	確認画面に立っていた旗がもう下りている（誰かが解いた・画面が無い）。もう一度 WebSearch を試す

待てるかどうかの判断は「サブタスクかどうか」では決まらない（#1225）。サブタスクでも、親をたどって元のタスクに行き着くなら待てる。行き着かない実行だけが上の 1 行目に当たる。

確認画面はワークスペース単位で共有される。同じワークスペースの誰かが一度解けば、そのあとの検索は通る。

関連

• 検索そのものは WebSearch
• 停車と再開の仕組み（sentinel）は movement 制御フローツール