EONYX subagents: delegating work to the task tool
A subagent is a separate instance of the agent.
EONYX hands it a slice of the work.
It runs in its own context window, with a reduced tool set, and returns only the result.
So the main conversation stays clean: the research never clutters it.
1 🎯 The task tool
Delegation is one tool: task.
The model reaches for it when something has to be dug out of the codebase without bloating the conversation.
● task find every place the Store interface is used
⎿ 12 call sites in 4 packages: session/jsonl.go, agent/agent.go, …There is a single argument, description.
It must be self-contained and carry all the context.
The subagent cannot ask a clarifying question.
It works alone and returns a finished answer.
1.1 What a subagent can and cannot do
The child gets the read tools only: read, ls, glob, grep, fetch.
It cannot write files, run commands, or delegate further.
- Context isolation. It reads dozens of files and returns a short summary. The main context stays small.
- Safety. Read-only, so a delegated task changes nothing.
- No recursion. Its tool set has no
task, so subagents never spawn subagents.
The child inherits the parent’s model and max_steps.
It gets the same system prompt plus a note about its role: work autonomously, read-only tools, finish with a concise self-contained answer.
- Parallel research. Hand “figure out how authorization works” to
taskand keep going on the main line. - Broad searches. “Find every call of the deprecated API” returns a list, not hundreds of lines of context.
- Reconnaissance before an edit. The subagent collects facts, the main agent acts on them.
2 🧰 Built-in tools
Beyond task, load_skill and the MCP tools, EONYX registers 15 standard ones.
Registration order is the order the model sees them in.
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 |
It is never a fatal failure.
So the model sees what went wrong and adapts, for instance by fixing the path and retrying.
2.6 An in-process shell
bash and the hooks run on the embedded mvdan.cc/sh interpreter.
No system bash is needed.
Everything is cross-platform, Windows included.
One shell session keeps the working directory and the exported variables between calls, so cd and export persist.
A few dangerous commands are blocked at policy level: shutdown, reboot, halt, poweroff, mkfs, init.
3 🔄 How the agent loop works
A single turn is a loop of up to max_steps rounds, 50 by default:
- The user message is recorded.
- The model’s response streams in, text and tool calls.
- No tool calls means this is the final answer, and the turn ends.
- Otherwise the tools run, the results go back, and the loop repeats.
A few guarantees along the way:
- Parallel reads. Consecutive read-only calls run in parallel:
read,ls,glob,grep,git_status,git_diff,git_log. Everything else is sequential. Results always return in the original order. - The write is the source of truth. Every new message is saved to the session, and a save error aborts the turn.
- A denial does not break the conversation. A blocked tool comes back as an error, not a crash.
- The step limit. Hitting
max_stepswithout a final answer is reported honestly, with an offer to raise the limit. Headless, that 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.