Sub-agents

Sub-agents are isolated agentic loops that the main agent can spawn for focused tasks. They get their own context, run their own tool loop, and return a written summary. The main agent sees only the summary, keeping its context clean.

IsonForge has two:

Tool	What it does	Tools available to it
`task_explore`	Map the codebase. Find where things are defined, how flows connect.	Read-only filesystem: `read_file`, `search_files`, `list_files`, `glob`
`task_research`	Research the web. Compare libraries, find docs, survey approaches.	Read-only web: `web_search`, `web_fetch`

Neither can write files or run bash. They're strictly read-only.

Why sub-agents

The main session has limited context. If you ask "map the entire auth flow" and the agent runs 15 search_files + read_file calls inline, those results burn 30K+ tokens of your context, leaving less room for the actual implementation.

A sub-agent runs the same searches in an isolated context, then returns 200 words of summary. Your main context stays free for the part you care about: the implementation.

When the model uses them

The agent decides. With the system prompt patches in IsonForge v0.15+, the model is explicitly nudged to use task_explore BEFORE non-trivial edits in unfamiliar code, and task_research for multi-source web research.

Heuristics the model follows:

"Where is X defined / which files reference X" -> task_explore
"Find every place that calls Y" -> task_explore
"Map the auth flow" -> task_explore
"How do other people solve Z" -> task_research
"Compare library A vs B" -> task_research
"Find the latest docs for X" -> task_research

Force one

You can tell the agent to use a specific sub-agent:

> use task_explore to map the entire payment flow, then summarize who calls who

Or just describe the task in a way that's clearly delegation-shaped:

> map every entry point that ends up calling persistUser()

What you see

When the agent dispatches a sub-agent, the tool call shows in your REPL:

  ┌─ 🤖 task_explore ─
  │ Map the auth flow from request through session storage to user lookup
  └

The sub-agent runs internally - you don't see its individual tool calls. When it finishes, the result is a written summary attached to your main session as a tool result. The main agent reads that and continues.

If you want to see the sub-agent's work, use --verbose - sub-agent activity logs to stderr.

Sub-agent limits

Max iterations: 8 by default, 12 max. The sub-agent is forced to summarize after that.
No mutations. Even if you ask the sub-agent to edit a file, it refuses (the tool isn't exposed).
No bash. Same reason.
Independent context. The sub-agent doesn't see your conversation history. It only sees the prompt the main agent gave it.

`/agents` slash

In the REPL, /agents shows:

Available sub-agent tools.
A list of every task_* invocation in the current session, with description previews.

Useful when you want to see what's been delegated.

Pair with plan mode

Plan mode forbids mutating tools. Sub-agents (read-only) are still allowed. Use the combination for the deepest exploration:

> /plan on
> task_explore the codebase: map every place that talks to the database.
  task_research best practices for connection pooling.
  then propose a plan to add connection pooling.

The agent dispatches both sub-agents, gathers context, and produces a plan - without touching code.

Sub-agents vs background agents

	Sub-agent	Background agent
Scope	Inside one main turn	Separate session
Returns	Summary as tool result	Logs you tail later
Tools	Read-only	Full toolbox
Control	Main agent decides	You decide explicitly via `--bg`

Sub-agents are tactical (mid-task delegation). Background agents are strategic (whole tasks you run async).