sync: update from private repo (edc775f2)

docs/tools/requesttool.md

@@ -1,10 +1,10 @@
 # RequestTool
 
-この movement で提示されていないツールがどうしても必要なときに、その要求を**記録**するためのメタツール（`allowed_tools` に書かなくても常時利用可能）。
+この movement で提示されていないツールがどうしても必要なときに、その要求を**記録**し、可能ならユーザー承認を求めるためのメタツール（常時利用可能）。
 
 ## いつ使うか
 
-- 依頼を達成するのに必要なツールが、現在の movement の `allowed_tools` に無いと気づいたとき。
+- 依頼を達成するのに必要なツールが、現在の movement に無いと気づいたとき。
 - まず「本当にそのツールが要るか」を検討すること。多くの作業は既存のツール（`Bash` / `Read` / `WebSearch` 等）で代替できる。
 
 ## 引数
@@ -12,13 +12,16 @@
 | 引数 | 必須 | 説明 |
 |------|------|------|
 | `name` | はい | 必要なツール名（例: `WebSearch`, `Bash`, `mcp__foo__bar`） |
-| `reason` | はい | なぜそのツールが必要かを具体的に。これがピース作者への記録に残る |
+| `reason` | はい | なぜそのツールが必要かを具体的に。これが記録に残る |
 
-## 重要: これは「要求の記録」であって「即時付与」ではない
+## 承認フローと即時利用の可否
 
-RequestTool を呼んでも、そのツールが**その場で使えるようにはならない**。要求は記録され、タスク詳細とピース集計に表示される。ピース作者が `allowed_tools` / `shared_tools` に追加すれば次回から使える。
+ツールの可否は**ワークスペースのツールポリシー（設定 → ツール／SSH）**で決まる。RequestTool の挙動は実行環境で変わる:
 
-要求したあとの進め方:
+- **ユーザーが応答できる実行**（対話承認が有効）: 承認を求めて停車し、**承認されればそのまま続行してそのツールを使える**。拒否されればツール無しで進む。
+- **それ以外の実行**: その場では使えない。要求が記録され、タスク詳細とツール要求の集計に表示される。運用者がワークスペースの設定でそのツールを有効化すれば、次回から使える。
+
+その場で使えない場合の進め方:
 
 1. そのツール無しで達成できないか、もう一度考える。
 2. どうしても無理なら `complete({status: "needs_user_input", missing_info: "...", why_no_default: "..."})` でユーザーに依頼する。
@@ -27,9 +30,9 @@ RequestTool を呼んでも、そのツールが**その場で使えるように
 ## 分類（記録される `category`）
 
 - **既に利用可能**: そのツールはこの movement で使える → 記録せず「そのまま呼んでください」と返る。
-- **`requested`**: カタログに存在するがこの movement では未許可 → 設定漏れ候補として記録。
+- **`requested`**: カタログに存在するがこの movement では未許可 → 対話承認が有効なら承認待ちに、無効なら設定漏れ候補として記録。
 - **`unknown`**: そんなツールは存在しない（名前の誤り・能力ギャップ）→ **エラーを返す**（実在ツール名のみ要求可）。診断のため記録は残るが、承認待ちにはならない。エラーを受けたら実在するツールで進めること。
 
 ## 関連
 
-足りないツールを呼んで弾かれた場合も、同じ記録に「受動捕捉（`blocked`）」として残る。ピース側の `shared_tools`（全 movement 共通ツール）も参照（`pieces/SCHEMA.md`）。
+足りないツールを呼んで弾かれた場合も、同じ記録に「受動捕捉（`blocked`）」として残る。ワークスペースのツール許可の考え方は「[ツール](../../ui/src/content/help/16-tools.md)」も参照。