# 協作工具

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

| 工具 | 說明 |
|---|---|
| `subagents` | `mode=invoke` 在獨立 session 中執行子任務（in-process，不走 HTTP）；`mode=list` 回傳可重用的具名 session 與其角色。任務描述必須自我完備 —— 子任務看不到母對話的任何內容。**前景 leg 同時最多 `min(MAX_CONCURRENT_TOOLS, MAX_CONCURRENT_SUBAGENTS)` 條** —— v1.3.0 起為 CPU 核心數的一半、至少 3（之前固定為 3）—— 超出的會在自己的 timeout 計時中排隊，因此大規模 fan-out 以此數量為一批派送。結果帶有 `[subagent · <model> · session=<id> · usage: in=X out=Y cached=Z write=W]` 標頭，並累計進母 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 則使用傳入的模型。前景 leg 上限為 `MAX_SUBAGENT_TIMEOUT_MIN`（30 分鐘）。`background` 與 `timeout_min` 參數（v1.3.0 新增）已移除於 v1.3.2；請改用 `background_subagents`，工具描述會把幾乎確定超過 5 分鐘的 leg，或「take your time」「let me know when it's done」「run it in the background」這類請求導向該工具（v1.3.7 起觸發語只寫英文）。自 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 的名稱會直接報錯並列出可用模型。`reasoning` 預設 `auto`（沿用 leg 所在 session 的設定，否則由 dispatcher 挑選）；不是合法推理等級的值會直接報錯。leg 只負責蒐集：一律拿不到 `subagents`、`background_subagents`、`edit_file`、`remove_file`、`restore_file`、`edit_tool`、`test_tool`、`edit_skill`、`write_result`、`html_template`、任何 `generate_*` 工具、`open_file`、`schedules`、`store_secret` 與 TUI 專屬工具（`configs/jsons/tui_tools.json`，v1.3.2 中其工具清單為空），程式碼以文字回傳由主 agent 套用；`exclude_tools` 在此之上追加。完整派送協定與模型 tier → `reasoning_guide(topics=["subagent_dispatch"])` |
| `background_subagents` | v1.3.2 新增。在背景啟動一條 leg 並立即回傳 task id，當輪繼續進行。參數沿用 `subagents` 的 `mode=invoke`（`task` 與 `model` 必填；`report_name`、`self_id`、`reasoning`、`new`、`system_prompt`、`exclude_tools`），另加 `timeout_min`（1-60，預設 60）取代 30 分鐘上限，v1.3.8 起另有 `objective` 與 `next`。同一回合開的 leg 組成一組（v1.3.8）。leg 完成時，發起的任務仍在執行或 pending 時，存好的報告路徑送進該任務；任務結束後，整組等所有 leg 完成，以 `objective`＋`next`＋所有報告另開新任務，可經 `chat_history` 讀取發起的任務。v1.3.8 之前每份報告各自接回原任務。背景 leg 從不觸發確認：需要確認的呼叫不會執行，leg 會被告知回報該呼叫仍待使用者核准；它也拿不到 `ask_user`。每條 leg 的進度（模型、工具呼叫與結果、文字、錯誤）寫入 `~/.config/agenvoy/sessions/<session>/background/<task id>.log`，leg 結束即刪除。leg 佔用背景任務名額而非前景名額：每個 session 最多 `MAX_BACKGROUND_TASKS` 個（CPU 核心數的一半，至少 3），與 `background_command` 共用。工具描述只在 leg 幾乎確定超過 5 分鐘，或使用者提出「take your time」「let me know when it's done」「run it in the background」這類請求時才使用；使用者要在蒐集後進行的動作寫進 `next`，幾分鐘內就能完成的請求仍留在前景（v1.3.8）。同一組的 leg 都在同一回合派出。請求不是來自 TUI（`cli-` origin 且沒有 deliver target）時排除 |
| `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 呼叫一起執行。回答需要超過一輪工具呼叫時就開清單，分析或研究類請求不論計畫多短也一律開；執行中的 Skill 若步驟需要超過一輪工具呼叫，會在第一步前依自身步驟開清單 —— 略去本次請求用不到的步驟；單輪完成的 Skill 不開清單（v1.1.1 的門檻為三個步驟） |
| `ask_user` | 自由輸入 / 單選 / 複選 / 遮罩輸入的提問。每個問題可帶多行 `detail` 承載補充說明（v1.3.5 前名為 `hint`）。v1.3.8 起 Telegram 與 Discord 把問題、detail 與 `question n/m`（多題時才有）分行送出，網頁卡片顯示同樣的進度；工具呼叫行為 `Ask(...)`，內容為第一題 `detail` 的第一行（沒有則用 question），最多 128 字元。自 v1.0.23 起 TUI（`cli-` origin）直接就地提問：問題出現在原處，同一次執行拿到回答後繼續。自 v1.2.0 起由 daemon 執行 agent，問題經 Unix socket 只送到發起該次執行的 TUI 視窗。其他 origin（web、Telegram、Discord、API、排程）則存下 pending 快照 —— 工具結果每筆截至 32 KiB、參數截至 4 KiB（v1.1.2 前為 4 KiB / 1 KiB） —— 結束本次執行，待使用者回答後以完整脈絡於新 turn 恢復。此工具沒有 timeout。工具描述要求：作用中 Skill 的 `SKILL.md` 或工具可取得的資料已能回答時不再提問。憑證一律不從這裡問 → `store_secret` |