EONYX subagents: delegating work to the task tool
A subagent is a separate instance of the agent that EONYX hands part of the work to. It performs the task in its own context window, with a reduced set of tools, and returns only the result into the main conversation. This keeps the main context clean: the details of the research don’t clutter the dialog. This article covers the task tool, the full list of built-in tools, and how the agent loop works.
1 The task tool
Delegation in EONYX is a single tool, task. The model calls it when something has to be researched in the codebase without bloating the main conversation:
● task find every place the Store interface is used
⎿ 12 call sites in 4 packages: session/jsonl.go, agent/agent.go, …There is one argument — description: a self-contained statement of the task with all the context it needs. The subagent cannot ask clarifying questions — it works autonomously and returns a finished answer.
1.1 What a subagent can and can’t do
The child agent gets only the read tools: read, ls, glob, grep, fetch. It cannot write files, run commands, or delegate any further:
- Context isolation. The subagent will read dozens of files and return a short summary into the main conversation — the main context doesn’t get filled up.
- Safety. Read-only: a delegated task will not change the project.
- No recursion. The subagent’s tool set has no
tasktool, so subagents don’t spawn subagents.
The child agent inherits the same model and step limit (max_steps) as the main one, and works with the same system prompt plus a note about its role: “you are a subagent, you work autonomously with read-only tools, at the end give a concise self-contained answer”.
- Parallel research — you hand “figure out how authorization works” to
taskwhile you keep going on the main line yourself. - Broad searches — “find every call of the deprecated API” returns a list instead of hundreds of lines in the context.
- Reconnaissance before an edit — the subagent collects the facts, the main agent makes the changes based on them.
2 Built-in tools
Besides task, load_skill, and the MCP tools, EONYX registers 15 standard tools. The registration order is the order in which they are offered to the model.
2.1 Files
| Tool | What it does |
|---|---|
read | reads a text file; optionally with a line offset and a limit |
write | writes a file, creating directories and overwriting; dry_run shows a diff |
edit | replaces an exact substring; replace_all — every occurrence, dry_run — a preview |
multi_edit | several replacements in one file atomically: either all of them, or the file is untouched |
ls | lists the contents of a directory (directories with a /) |
picker | navigation through the project tree — browse and pick paths |
2.2 Search
| Tool | What it does |
|---|---|
glob | finds files by a glob pattern (** — recursive) |
grep | searches contents with a regex, path:line:text; skips binaries and .git |
2.3 Execution and network
| Tool | What it does |
|---|---|
bash | a command in a persistent shell session; the output is stdout+stderr, the exit code is in the text |
fetch | downloads a web page: HTML → markdown, other text as is, binaries are rejected |
2.4 Git
| Tool | What it does |
|---|---|
git_status | the working tree status (git status --short --branch) |
git_diff | the diff of uncommitted changes (or staged=true) |
git_log | recent commits, one per line (git log --oneline) |
git_commit | a commit with a message; all=true stages tracked files first |
2.5 Organizing the work
| Tool | What it does |
|---|---|
todo_write | keeps a task list for multi-step work; the whole list is passed at once |
2.6 An in-process shell
The bash tool (and the hooks) work through the embedded mvdan.cc/sh interpreter — a system bash is not needed, everything is cross-platform, Windows included. A single shell session keeps the working directory and the exported variables between calls: cd and export persist. A small set of dangerous commands is blocked at the policy level: shutdown, reboot, halt, poweroff, mkfs, init.
3 How the agent loop works
A single agent turn (Send) is a loop of up to max_steps iterations (50 by default):
- The user message is recorded.
- The model’s response is streamed (text + tool calls).
- If there are no tool calls — this is the final answer, the turn is over.
- Otherwise the tools are executed, the results are returned to the model, and the loop repeats.
A couple of optimizations and guarantees:
- Parallel reads. Consecutive read-only calls (
read,ls,glob,grep,git_status,git_diff,git_log) are executed in parallel; everything else runs sequentially. Results are always returned in the original order. - The write is the source of truth. Every new message is saved into the session; a save error aborts the turn.
- A denial doesn’t break the conversation. A tool blocked by the gate is returned to the model as an error, not as a crash.
- The step limit. If
max_stepsis hit without a final answer, EONYX says so honestly and offers to raise the limit (in headless mode this is exit code5).
4 Summary
- task — delegates a research task to a subagent with read-only tools (
read,ls,glob,grep,fetch); returns a condensed result without cluttering the context. - No recursion — the subagent has no
task, so there will be no nesting; it inherits the parent’s model andmax_steps. - 15 tools — files (read/write/edit/multi_edit/ls/picker), search (glob/grep), execution (bash/fetch), git (status/diff/log/commit), tasks (todo_write).
- An in-process shell —
mvdan/sh, no system bash; keeps cwd/env; blocks shutdown/reboot/mkfs and the like. - The loop — up to
max_stepsrounds; parallel reads, the write as the source of truth, errors as data.