工具擴充
Agenvoy 支援四種在內建集合之外新增工具的方式：從 capability gap 自動生成、script tool、API tool 與 MCP tool。由 extension 安裝的工具落在 ~/.config/agenvoy/tools/.extension/，並以 ext_ 前綴註冊。
自動生成（Capability Gap）
當 user request 需要即時外部資料（天氣、匯率、股票、geocoding、翻譯等）且無現有 tool 涵蓋時，agent 當場建立該 tool，隨即執行以回答。無需寫程式。
reasoning_guide(topic=tool_generate) 承載建置契約；同一份文字也透過 MCP server 以 tool_generate_guide 對外部 agent 曝露。序列如下：
| 步驟 | 動作 |
|---|---|
| 1. 找到合適的 API | api_public_api_list(type=category) 挑選相關類別，選出最佳候選（偏好 no-auth + HTTPS），再 fetch_page 文件 |
| 2. 決定工具型態 | 多步驟邏輯或需運算 → script tool（tool.json + script.py）；單一 REST 端點且無運算 → API tool（單一 JSON） |
| 3. 寫入 | edit_tool(mode=write) 搭配 tag=json + tag=script，或宣告式的 tag=api |
| 4. 驗證 | test_tool 於沙箱執行 script.py；失敗以 edit_tool(mode=patch) 修正 |
| 5. 回答 | 呼叫新工具，並以其輸出回答 |
建立後，工具持久化於 ~/.config/agenvoy/tools/script/<name>/（或 tools/api/<name>.json），在所有未來 session 及所有連線的 MCP agent 中皆可用。憑證絕不硬編碼：命名慣例為 {BRAND}_API_KEY，以 store_secret 取得，並從本機 keychain 端點 GET http://localhost:17989/v1/key?key=<KEY_NAME> 讀回。
關鍵限制：
- agent 絕不可用裸
http_request或 inlinepython3 -c回答；必須將可重用工具寫入磁碟 fetch_page僅允許用於讀取 API 文件，不用於抓取回答資料- 名稱採
snake_case動詞 + 名詞（fetch_weather、calculate_rsi）且不帶前綴——runtime 會自動加上script_或api_
Script tool（script_*）
在 ~/.config/agenvoy/tools/script/<name>/（或專案本地的 <cwd>/.config/agenvoy/tools/script/<name>/）放入 tool.json descriptor 與 script.py（Python）或 script.js（JavaScript）。Agenvoy 自動註冊為 script_<name>。原本的 extensions/scripts/<name>/ + run.py 佈局不會被掃描；由 extension 安裝在 tools/.extension/script/ 的 script 以 ext_<name> 註冊。
~/.config/agenvoy/tools/script/my_tool/
├── tool.json # name, description, parameter schema
└── script.py # actual script (or script.js)
API tool（api_*）
在 ~/.config/agenvoy/tools/api/<name>.json（或專案本地的 <cwd>/.config/agenvoy/tools/api/）放入描述 REST 端點的 JSON 檔。它自動註冊為 api_<name>。extensions/apis/*.json 則編譯進 binary 作為內建 API tool（例如 public-api-list.json → api_public_api_list）。
Confirm gate —— api_* tool 不因前綴而豁免確認。使用者可能定義破壞性 endpoint（DELETE / POST 寫入），因此除非 descriptor 設定 "always_allow": true，每次呼叫都依當前權限模式確認。需要批次自動核准時，開啟 auto 模式（Shift+Tab）或在請求帶上 allow_all: true。
MCP tool（mcp__*）
由 MCP server 曝露的 tool 自動註冊為 mcp__<server>__<tool>。MCP tool output 每次呼叫上限 1 MiB，以將 tool result 保持在 provider 限制內。