# 協作工具

subagent、排程、清單、向使用者提問與最終結果的工具。

| 工具 | 說明 |
|---|---|
| `subagents` | `mode=invoke` 在獨立 session 中執行子任務（in-process，不走 HTTP）；`mode=list` 回傳可重用的具名 session 與其角色。任務描述必須自我完備 —— 子任務看不到母對話的任何內容。**最多 3 條並行**，第 4 條會在自己的 timeout 計時中排隊，因此大規模 fan-out 以 3 個為一批派送。結果帶有 `[subagent · <model> · session=<id> · usage: in=X out=Y cached=Z]` 標頭，並累計進母 session 的用量。自 v1.0.22 起 leg 的報告內文不再直接回傳：它會寫入 `~/.config/agenvoy/download/temp-<report_name>.md`，結果只含上述標頭與檔案路徑，呼叫端須先以 `read_files` 讀取再轉述或彙整。`report_name` 為簡短 kebab-case 名稱（工作 + 對象，例如 `nvda-news`）；名稱已存在時加上隨機後綴，空白則使用隨機名稱。`self_id` 用於原樣重用既有的非暫時 session，v0.35.0 起取代 `name` / `session_id`，且 `mode=list` 必須帶它 —— 現在是解析單一被指名的 agent，而非列出所有 session；自 v1.1.0 起每次 `mode=invoke` 都必須帶 `model` —— 空白 model 改由 dispatcher 代選的退路已移除，改為明確傳 `model: "auto"`（v1.1.0 後的 hotfix）交由 dispatcher 依任務挑選，與一般請求相同；`self_id` 解析到綁定自有模型的 session 時改用該模型，停在 `auto` 的 session 則使用傳入的模型。Timeout 為 `MaxSubagentTimeoutMin`（30 分鐘）。自 v1.0.21 起每條 leg 只有一個 job —— collect、analyze、compare、review、transform 或 code —— 並對應到一種工作類別；自 v1.1.0 起 leg 的 tier 順序比 dispatcher 低一階（collect → `fetch` C>B>A>S、transform → `chat` C>B>A>S、analyze / compare / review → `work` B>A>C>S、程式碼或高精度 → `code` A>B>C>S）。原本的 `reason` job 拆成 analyze、compare 與 code。`model` 會對照即時 registry 檢查，啟動後才新增的模型也能用；未註冊或 `pass` tier 的名稱會直接報錯並列出可用模型。leg 一律拿不到 `subagents`、`edit_file`、任何 `generate_*` 工具與 TUI 專屬工具；`exclude_tools` 在此之上追加。完整派送協定與模型 tier → `reasoning_guide(topics=["subagent_dispatch"])` |
| `schedules` | 綁定 scheduler skill 的排程執行。`mode=list` 顯示本 session 已排入的項目、`mode=patch` 調整時間、`mode=remove` 取消並丟棄其 skill、`mode=write` 是 `scheduler-skill-creator` 流程的內部綁定步驟。`target` 為 `task`（單次）、`cron`（5 欄位表達式）或 `all`（僅 list 可用）。task 時間格式：`+5m` / `+1h30m`（相對）、`15:04`（今日時鐘）、`2006-01-02 15:04`（本地日期時間）或 RFC3339。`skill_name` 帶有生成的 hash 後綴 —— 手寫的名稱必定失敗 |
| `write_todo` | 使用者即時觀看的任務清單。每次呼叫都重送整份有序清單（狀態是取代而非合併）；恰好一個步驟維持 `in_progress`。計畫執行期間步驟集合固定 —— 只推進狀態，不改寫、不重排。清單以 task hash 分開儲存，同一 session 的並行任務各自保有清單。最後一步完成且該任務尚未寫出 `report-*.md` 或 `report-*.html` 時，回傳結果會提示模型對長篇產出呼叫 `write_result`。自 v1.0.26 起帶有 `Concurrent` 旗標，會與同一輪的其他 fan-out 呼叫一起執行。v1.1.1 起請求列出三個以上步驟即視為需開清單的複雜任務；執行中的 Skill 若有三個以上步驟，會在第一步前依自身步驟開清單 —— 略去本次請求用不到的步驟；單步完成的 Skill 不開清單 |
| `ask_user` | 自由輸入 / 單選 / 複選 / 遮罩輸入的提問。每個問題可帶多行 `hint` 承載補充細節。自 v1.0.23 起 TUI（`cli-` origin）直接就地提問：問題出現在原處，同一次執行拿到回答後繼續。其他 origin（web、Telegram、Discord、API、排程）則存下 pending 快照 —— 工具結果每筆截至 4 KiB、參數截至 1 KiB —— 結束本次執行，待使用者回答後以完整脈絡於新 turn 恢復。此工具沒有 timeout。工具描述要求：作用中 Skill 的 `SKILL.md` 或工具可取得的資料已能回答時不再提問。憑證一律不從這裡問 → `store_secret` |