Skip to main content
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:

​
Built-in agents

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 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.

​
Where agent files live

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. 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.

​
Front matter fields

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

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.

​
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:
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.
  • Campaigns: split one objective across parallel workers.
  • Plan mode: research before you change anything.
  • Permissions: approval modes for the main agent.