Coordination Tools
Last updated
Tools for subagents, schedules, checklists, questions to the user and final results.
| Tool | Description |
|---|---|
subagents | mode=invoke runs a subtask in its own session (in-process, no HTTP); mode=list returns the reusable named sessions and their roles. Written to stand alone — the leg sees none of the parent conversation. Foreground legs run at most min(MAX_CONCURRENT_TOOLS, MAX_CONCURRENT_SUBAGENTS) at a time — half the CPU cores, at least 3, since v1.3.0 (a fixed 3 before) — and the next one queues while its own timeout runs, so wide fan-outs dispatch in batches of that size. Results carry a [subagent · <model> · session=<id> · usage: in=X out=Y cached=Z write=W] header that rolls up into parent-session usage. Since v1.0.22 the leg's report body no longer comes back inline: it is written to ~/.config/agenvoy/download/temp-<report_name>.md and the result is that header plus the file path, which the caller reads with read_files before relaying or synthesizing. report_name is a short kebab-case name (job + entity, e.g. nvda-news); a taken name gets a random suffix, and a blank one uses a random name. self_id reuses an existing non-temp session verbatim — it replaced name / session_id in v0.35.0 and is now required for mode=list, which resolves one delegated name instead of dumping every session. Since v1.1.0 model is required on every mode=invoke call — the dispatcher fallback for a blank model was removed, and model: "auto" (hotfix after v1.1.0) hands the choice to the dispatcher, which picks from the task as for a normal request; when self_id resolves to a session pinned to its own model that model runs instead, and a session left on auto runs the given one. Foreground legs are capped at MAX_SUBAGENT_TIMEOUT_MIN (30 min). The background and timeout_min parameters (added in v1.3.0) were Removed in v1.3.2; use background_subagents instead, and the description sends legs very likely over 5 minutes, or a request such as "take your time" / "let me know when it's done" / "run it in the background" (English-only trigger phrases since v1.3.7), there. Since v1.0.21 each leg has one job — collect, analyze, compare, review, transform or code — mapped to a work kind; since v1.1.0 the leg's tier order runs one tier lower than the dispatcher's (collect → fetch C>B>A>S, transform → chat C>B>A>S, analyze / compare / review → work B>A>C>S, code or high-precision → code A>B>C>S). The former reason job was split into analyze, compare and code. model is checked against the live registry, so models added after startup work; an unregistered or pass-tier name is rejected with the list of usable models. reasoning defaults to auto (the leg's session setting, else the dispatcher's pick); a value that is not a reasoning level is rejected. Legs only gather: a leg never gets subagents, background_subagents, edit_file, remove_file, restore_file, edit_tool, test_tool, edit_skill, write_result, html_template, any generate_* tool, open_file, schedules, store_secret, or the TUI-only tools (configs/jsons/tui_tools.json, whose tool list is empty in v1.3.2), and code comes back as text for the main agent to apply; exclude_tools adds to that set. Full dispatch protocol and model tiers → reasoning_guide(topics=["subagent_dispatch"]) |
background_subagents | Added in v1.3.2. Starts one leg in the background and returns a task id at once, so the turn continues. Takes the subagents mode=invoke parameters (task and model required; report_name, self_id, reasoning, new, system_prompt, exclude_tools) plus timeout_min (1-60, default 60) in place of the 30-minute cap, and since v1.3.8 objective and next. Legs started in the same turn form one group (v1.3.8). When a leg finishes, its saved report path goes to the starting task while that task is running or pending; once it has ended, the group waits for all its legs and runs objective + next + every report as a new task, which can read the starting task through chat_history. Before v1.3.8 each report resumed the original task on its own. A background leg never raises a confirmation: a call that would need one is not run and the leg is told to report that it still needs approval; it also gets no ask_user. Each leg's progress (model, tool calls and results, text, errors) is written to ~/.config/agenvoy/sessions/<session>/background/<task id>.log, removed when the leg ends. The leg takes a background task slot instead of a foreground one: at most MAX_BACKGROUND_TASKS per session (half the CPU cores, at least 3), shared with background_command. The description reserves it for legs very likely over 5 minutes, or a request such as "take your time" / "let me know when it's done" / "run it in the background"; an action the user wants after the gathering goes into next, and a request that finishes in a few minutes stays in the foreground (v1.3.8). Every leg of a group is started in the same turn. Excluded unless the request comes from the TUI (cli- origin with no deliver target) |
schedules | Scheduled runs bound to a scheduler skill. mode=list shows what this session has queued, mode=patch moves an entry to a new time, mode=remove cancels it and trashes its skill, mode=write is the internal binding step of the scheduler-skill-creator flow. target is task (one-shot), cron (5-field expression), or all (list only). Task time formats: +5m / +1h30m (relative), 15:04 (later today only, no rollover to tomorrow), 2006-01-02 15:04 (local), or RFC3339. skill_name carries a generated hash suffix — hand-made values always fail |
write_todo | Live task checklist the user watches in real time. The entire ordered list is resent on every call (state is replaced, not merged); exactly one step stays in_progress. While a plan runs the step set is fixed — only status advances. The checklist is stored per task hash, so concurrent tasks in one session keep separate lists. When the last step completes and no report-*.md or report-*.html was written in that task, the result tells the model to call write_result for a long-form deliverable. Since v1.0.26 it carries the Concurrent flag, so it runs alongside the other fan-out calls of the same round. A checklist opens whenever the answer takes more than one round of tool calls, and for any analysis or research request however short the plan looks; a running Skill whose steps take more than one round opens one built from its own steps before the first step — dropping the ones the request does not reach; single-pass Skills get none (v1.1.1 used a three-step threshold) |
ask_user | Free-text / single-select / multi-select / masked-secret prompts. Each question carries an optional multi-line detail for supporting context (named hint before v1.3.5). Since v1.3.8 Telegram and Discord send the question, its detail and question n/m (only with several questions) on separate lines, and the web card shows the same progress; the tool-call line reads Ask(...) with the first line of the first question's detail (or its question), up to 128 characters. Since v1.0.23 the TUI (cli- origin) asks inline: the question appears in place and the same run continues with the answer. Since v1.2.0 the daemon runs the agent and sends the question over its Unix socket only to the TUI window that started the run. Every other origin (web, Telegram, Discord, API, scheduler) saves a pending snapshot — tool results clamped to 32 KiB and arguments to 4 KiB each (4 KiB / 1 KiB before v1.1.2) — ends the run, and resumes in a new turn with full context once the user answers. The tool has no timeout. The description tells the model not to ask when an active Skill's SKILL.md or data a tool can fetch already settles the question. A credential is never asked for here → store_secret |