工具設計與規則
工具設計規則
新增或編輯工具的四條強制規則（build-time 契約來自 reasoning_guide(topic=tool_generate)，對外部 agent 則以 tool_generate_guide 曝露；後續品質由 code-reviewer skill 檢查）：
- name 是唯一的語意載體 — stub-tool 的首輪呼叫只看得到 name；description 與 params 在第二輪才抵達
- description 固定 3 行、60-200 字元 — What（核心動作）／When（觸發時機 vs 替代方案，例：
use for X; Y for Z）／Precondition（關鍵限制，無則省略）。不放填充語、不用粗體、不放輸出 schema dump。 - 僅限英文 — 中文只出現在面向使用者的 handler 回傳訊息
- 選用欄位必須宣告
default— handler 仍需防禦 nil/缺失
觸發條件與同類工具比較是 When 行的必要內容，不是禁止項——只寫核心動作而沒有觸發訊號的 description 視為不完整。Parameter description 須涵蓋 How／When／Example，非平凡型別（object/array/enum）若說明少於 20 字元視為不完整。
工具並行標記
toolRegister.Def 帶有六個行為旗標：
| 旗標 | 效果 |
|---|---|
AlwaysAllow |
豁免 confirm gate（唯讀工具） |
AlwaysLoad |
第一輪即帶上 schema，無需 find_tools(mode=search) 啟用。共 15 個工具具備此旗標：ask_user、calculate、chat_history、edit_file、fetch_page、find_files、find_note、find_tools、read_files、reasoning_guide、run_command、run_skill、search_web、write_report、write_todo |
Concurrent |
選擇加入 Pass 2 fan-out（每次呼叫一個 goroutine） |
Background |
迴圈不等待其結果 |
SystemUse |
內部管理用工具——不出現在一般列表，只有在對 find_tools(mode=list) 要求系統工具時才顯示 |
Timeout |
覆寫預設的 1 分鐘上限 |
加入 Concurrent: true 需同時滿足「無副作用」與「上游允許並行」。當前的並行工具集列於執行引擎頁。
工具 timeout 矩陣
toolRegister.Dispatch 會以工具註冊的 timeout（未覆寫時為 1 分鐘）包住每一次呼叫——內建、script、API 與 MCP 皆然。各 adapter 在此上限內再套自己的限制：
| Adapter | Adapter 預設 | 可設定 | 實際上限 |
|---|---|---|---|
| Built-in | 1 分鐘 | 每個工具的 Def.Timeout |
Def.Timeout |
Script（script_*） |
5 分鐘（300 秒） | ~/.config/agenvoy/tools/script/<name>/ 的 tool.json "timeout": <seconds>——同時註冊為 dispatch timeout |
tool.json 的值；未設定時 1 分鐘的 dispatch 預設會先生效 |
API（api_*） |
60 秒 | extensions/apis/<name>.json 的 doc.Endpoint.Timeout——不會註冊到 dispatch |
1 分鐘 dispatch 預設 |
| MCP HTTP | Transport ResponseHeaderTimeout 60 秒 |
無 | 1 分鐘 dispatch 預設 |
| MCP stdio | 無 | 無 | 1 分鐘 dispatch 預設 |
長時間執行的工具（script + API）每 30 秒向 daemon log 發出 running name=... elapsed=Ys/Zs 以利可見性。
長時執行的內建工具於註冊時宣告各自上限：run_command = 60 分鐘、subagents = MaxSubagentTimeoutMin（30 分鐘）、download_file = 註冊 10 分鐘，請求本身由自身參數限制（預設 120 秒、上限 600 秒）、generate_audio = 5 分鐘、fetch_page / search_web = 90 秒、http_request = 由自身參數指定（預設 60 秒、上限 300 秒），仍受 1 分鐘預設約束、generate_image = 15 分鐘、open_file = 10 秒。
憑證自動修復
store_secret 為 SystemUse 工具——不在首輪 payload 中，需要時才透過 find_tools 帶入。System prompt 原本的 §10 Credential auto-heal 段落已移除；現在 system prompt 只留一行指向 store_secret，流程寫在該工具自己的 description。遇到認證失敗——缺 key、401、403、token 過期——agent 從錯誤中取出 key 名稱、呼叫 store_secret（透過遮罩輸入取得新值 — 該值永不到達 LLM），再重新呼叫失敗的工具。每個工具每回合上限為兩輪 store_secret。