> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open4rena.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Subagents

> Let the model hand work to subagents that run in their own context.

A subagent is a separate agent that the model starts to handle one part of a
job. Each subagent has its own context window, system prompt, and set of
tools, so a long search or a side task doesn't fill up your main
conversation. When the subagent finishes, the model gets its result.

The model decides when to use subagents. You can also ask for one directly:

```text theme={null}
Use the Explore agent to find every place we parse dates, then summarize the formats.
```

## Built-in agents

| Agent | What it's for | Tools |
| - | - | - |
| `Explore` | Finding files and code and answering questions about the codebase. | `read`, `glob`, `grep`, `ls` |
| `Plan` | Designing an implementation plan: key files, approach, and trade-offs. | `read`, `glob`, `grep`, `ls`, and `web_search`, which its `plan` permission mode blocks unless a rule allows it |
| `General` | Any multi-step task. | All subagent tools |

`Explore` and `Plan` can't edit files or run commands. The tools a subagent
can have are `read`, `glob`, `grep`, `ls`, `write`, `edit`, `bash`, `fetch`,
`web_search`, `git_info`, your MCP tools, and `agent` for starting its own
subagents.

When the model starts a subagent without naming one, o4 starts a fork: a copy
of the main agent with the same context and tools. It's listed as the built-in
`Fork` agent in `/sub-agents`.

Every subagent uses your current model unless its definition or the model's
request names another one. To make all subagents use one model, set the
`O4_SUBAGENT_MODEL` environment variable to a model reference.

## Watch and control subagents

While a subagent runs, its progress shows in the chat. Run `/agents` to open
the **Agent command center**, which lists every subagent in the session with
its status. From there you can open a subagent's output, send it a message
with `m`, or stop it with `x`. See
[todos and background tasks](/guides/tasks-and-todos#see-and-control-background-work)
for all the keys.

A subagent that runs in the foreground for more than 2 minutes moves to the
background, and the conversation continues. The model can also start a
subagent in the background from the beginning. Either way, o4 tells the model
when it finishes. The `auto_background_ms` setting changes the 2-minute limit.

## Approvals

A subagent's tool calls go through approvals like the main agent's. When a
subagent needs approval, the status row says `Awaiting approval` and names the
subagent that is waiting.

A custom agent can set its own `permissionMode`, described below.

## Limits

* A subagent can start its own subagents, up to 3 levels deep.
* At most 10 subagents run at once by default. Set `max_concurrent_agents` in
  `~/.o4/settings.json` or `.o4/settings.json` to change this.

## Run a subagent in its own worktree

The model can pass `isolation: "worktree"` when it starts a subagent, and a
custom agent can set `isolation: worktree`. The subagent then works in its
own git worktree under `.o4/worktrees/`, on its own branch, so it can't change
your checkout.

When the subagent finishes, o4 removes the worktree if it has no changes. If
it has changes, o4 keeps it and tells the model where it is, so the changes
can be reviewed and merged. o4 removes clean worktrees that haven't been used
for 30 days when a session starts.

## Custom agents

A custom agent is a Markdown file with YAML front matter. The front matter
configures the agent, and the body is its system prompt.

```md theme={null}
---
name: reviewer
description: Reviews a diff for bugs and missing tests. Use after making changes.
tools: [read, grep, glob, git_info]
model: inherit
color: blue
---

You are a careful code reviewer. Read the changed files, look for bugs,
missing error handling, and untested paths, and report findings with file and
line references. Don't edit files.
```

### Where agent files live

| Location | Scope |
| - | - |
| `~/.o4/agents/*.md` | Your agents, available in every project. |
| `.o4/agents/*.md` | Project agents, shared with everyone who works on the repository. |

If two files define the same `name`, the project agent wins over your own,
and both win over a built-in agent with that name. o4 loads project agents
only after you trust the workspace. See
[workspace trust](/safety/workspace-trust).

o4 reads agent files when a session starts, and again after you create,
edit, or delete an agent through `/sub-agents`. If you change an agent file in
your own editor during a session, start a new session to pick up the change.
Agents that plugins provide are also available. See
[plugins](/extend/plugins).

### Front matter fields

| Field | What it does |
| - | - |
| `name` | The agent's name. Required. |
| `description` | When to use the agent. The model reads this to choose an agent. |
| `tools` | The tools the agent can use. Leave it out to allow all tools. |
| `disallowedTools` | Tools to remove from the agent. |
| `model` | A model reference, or `inherit` to use the current model. |
| `permissionMode` | How the agent's tool calls are approved. See below. |
| `isolation` | Set to `worktree` to always run the agent in its own git worktree. |
| `background` | Set to `true` to always run the agent in the background. |
| `skills` | Skills to load into the agent's prompt. See [skills](/extend/skills). |
| `mcpServers` | MCP servers the agent may use. See [MCP servers](/extend/mcp). |
| `memory` | Give the agent its own memory: `user`, `project`, or `local`. See [memory](/guides/memory#agent-memory). |
| `effort` | Reasoning effort for the agent. |
| `color` | Display color: `red`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, or `cyan`. |

o4 also accepts `maxTurns`, `initialPrompt`, and `omitClaudeMd`, but in o4
0.2.74 they don't change how the agent runs: subagents run until they finish,
whatever `maxTurns` says.

### Permission modes for custom agents

| `permissionMode` | Tool calls that normally need approval |
| - | - |
| not set | Follow your session's approval mode, like the main agent. |
| `default` | Ask you. |
| `acceptEdits` | Run `write` and `edit` without asking; ask for the rest. |
| `plan` | Are denied. Read-only tools still run. |
| `dontAsk` | Run without asking. |
| `bypassPermissions` | Run without asking. |

<Warning>
  `dontAsk` and `bypassPermissions` let an agent run shell commands and edit
  files without asking you. o4 honors them in built-in agents, your own agents,
  and project agents, which load only in trusted workspaces. In agents that
  come from plugins, o4 treats them as `default`. Before you trust a
  repository, check its `.o4/agents/` files for these modes.
</Warning>

## Manage agents with /sub-agents

Run `/sub-agents` to open the **Agents** browser. It lists every agent
definition with its description and source: `built-in`, `user`, `project`, or
`plugin`. `Tab` and `Shift+Tab` switch between the **All**, **Project**,
**User**, **Built-in**, **Plugin**, and **Errors** tabs. The **Errors** tab
lists agent files that failed to load. Type to filter the list, and press
`Ctrl+U` to clear the filter. You can also open the browser from the Agents tab
of `/config`, with its **Open agent browser** row.

Press `Enter` on an agent to see its actions, and `Backspace` to go back to the
list:

* **Select agent** fills the prompt with `Use the <name> agent for: ` so you
  can type the task.
* **Edit agent** opens the file in your editor.
* **Delete agent** deletes the file right away, without asking.

Built-in and plugin agents can't be edited or deleted.

While the model is working, you can still open the browser and use
**Select agent**, but creating, editing or deleting an agent is refused: o4
closes the browser and shows
`Wait for the current turn to finish before making this change.`

To create an agent, choose **Create new agent** at the top of the list. Type a
name, then pick the location: project (`.o4/agents/`, the default) or user
(`~/.o4/agents/`). o4 writes a starter file with `name`, `description`, and a
one-line prompt, and opens it in your editor: `$EDITOR`, then `$VISUAL`, then
`vi`.

You can also go straight to an action:

```text theme={null}
/sub-agents create reviewer
/sub-agents edit reviewer
```

`create` (or `new`) opens the create form with the name filled in. `select`,
`edit`, and `delete` open that agent with the action highlighted; press
`Enter` to run it.

## Teams

For larger jobs, the model can organize subagents into a team. The
`team_create` tool sets up a named team under `.o4/teams/<name>/` with a
roster of 1 to 10 members and a mailbox for each. It doesn't start any
agents. `team_delete` removes the team.

The `send_message` tool delivers a message to a running subagent by name, or
to a team. Messages reach a subagent at its next tool call rather than in the
middle of a response.

`team_create` and `team_delete` ask for approval every time. `send_message`
asks once per session.

## Related pages

* [Campaigns](/guides/campaigns): split one objective across parallel
  workers.
* [Plan mode](/guides/plan-mode): research before you change anything.
* [Permissions](/safety/permissions): approval modes for the main agent.