# 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](websearch.md)
- 停車と再開の仕組み（sentinel）は [movement 制御フローツール](../movement-control-flow-tools.md)