Delegate to subagents

A subagent is another agent that handles a focused task in its own conversation. The main agent can wait for its result or keep working while it runs.

Ask for a specific task with a clear result. For example:

Have a subagent inspect the callers of the cache implementation and identify
which tests would be affected by removing it. Ask it to report file locations
and test names without making edits. Meanwhile, review the cache itself.

The main agent chooses the subagent’s profile, which sets its role and narrows its tools, and uses its result in the main task. Check the reported evidence and test results before relying on them.

Follow delegated work

Enter a request such as “Ask a subagent to inspect the parser while you review the tests.” Once the subagent starts, list active and finished subagents:

/agent

Each subagent is listed with its status, task, current activity (waiting for a slot, thinking, writing a reply, or running a tool), and the files it changed with Orek’s file-editing tools.

Subagents belong to the session that started them. Quitting Orek, clearing or switching the conversation, ending orek run, or cancelling or closing an editor session stops every running subagent. A running saved workflow pauses instead, so you can resume it with /workflow resume <run-id>.

Use /workflows for linked checklist progress and /detail for tool results. Each subagent follows your tool-discovery settings on its own; if its profile leaves out tool_search, it gets every tool its profile allows from the start.

Workflow runs

See Create reusable workflows to write workflows and to run, approve, limit, and recover them, and Manage sessions to resume a session.

When to use a subagent

Subagents suit independent investigations, separate parts of an implementation, or a second review of a change. The explore and reviewer profiles cannot edit files or run shell commands, while edit can change files under the same approval rules as the main agent.

Subagent tools

Agents use these tools to manage subagents:

Every subagent below agent.max_subagent_depth has these tools and can reach any subagent in the session by ID or name. Any profile can start any profile; a subagent cannot close itself. See the agent tools reference for arguments and limits.

Messages between agents

Agents message each other with send_input by ID or name, and reach the main agent as main (no subagent can be named main). Each message names its sender:

[messages from other agents]
Message from agent `explore-2` (id `agent-2`):
The parser's error path is in src/parse.rs:212.

An agent holds at most 64 unread messages (100,000 bytes in total) before senders are asked to wait; this limit never holds back a subagent’s final result. When a session ends, unread messages for subagents are saved for when you resume it, while unread messages for main are discarded.

When a subagent finishes

When a subagent’s turn completes or fails, its result is delivered once as a message to the agent that started it, unless that agent already received it through spawn_agent with block=true, wait_agent, fanout, or a workflow step:

[messages from other agents]
Message from agent `explore-2` (id `agent-2`):
Finished with status `completed`:
The parser's error path is in src/parse.rs:212.

Closing a subagent (close_agent or Ctrl+C), or typing directly in its view in the TUI, does not send a result to the agent that started it.

How the main agent handles a subagent result depends on where you run Orek:

A subagent gets its task, a profile, and its own conversation. Its final reply goes to the agent or workflow that started it, never to a plan approval prompt, and the session checklist stays with the main agent. A subagent saves memories only when its profile includes memory (among the built-in profiles, only edit does).

Choose a profile

A profile gives the subagent its role, with an optional model choice, a tool list that keeps it focused, and limits:

search_project searches your project’s code index and works even when automatic retrieval is off. It needs an index and tools.search_project.enabled, and respects the profile’s tool list and your model tool access rules. If the index is missing, out of date, or unavailable, it says so instead of building one. See Find and explore code.

Provider web tools enabled for a subagent’s model are available to every profile, subject to your websearch and webfetch permission rules.

A profile’s allowed_tools list keeps a subagent focused; it is not a security boundary. For example, tester can still change files through shell or run_python, and any subagent below agent.max_subagent_depth can start further subagents.

Configure named profiles

Define your own profiles in user or project configuration:

[agent.subagent_profiles.auditor]
allowed_tools = ["read_file", "git_inspect"]
persona = "Review correctness and cite file:line evidence."
max_iterations = 1000
max_budget_usd = 5.0
max_tokens = 50000
reasoning_effort = "high"

Without allowed_tools, the subagent sees every session tool, including tools from connected MCP servers. With it, list MCP tools by full name (such as mcp__github__search_issues) and add read_mcp_resource for resource reads; the subagent tools stay available below agent.max_subagent_depth. Without max_iterations, a profile allows 10,000 iterations, and agent.max_iterations always caps it.

Profile names use lowercase letters, digits, _, and -, start with a letter, and are at most 64 bytes. A user or project profile replaces a profile of the same name entirely. orek config set agent.subagent_profiles updates only the named profiles in that scope, and orek config unset agent.subagent_profiles.<name> removes one.

A model or reasoning_effort given when starting a subagent overrides the profile; without either, the subagent uses the parent agent’s. Subagents share the session’s MCP connections and permission rules.

Progress reporting

A subagent succeeds only when it answers its task. A denied tool call, or reaching an iteration, cost, or token limit, ends its turn with an error.

When a subagent is linked to a checklist item through work_item_id, success marks the item completed and failure marks it blocked; see Subagents linked to a checklist item.

Workspace file handling

Subagents, including workflow steps, work directly on the files in your project:

1. A subagent has file-editing tools (search_replace, write_file, and delete_file) unless its profile’s allowed_tools leaves them out.
2. Subagents run at the same time as the main agent and each other. Give parallel editing subagents separate files in your plan so their changes do not collide. search_replace refuses an edit when the file changed since it was read, but write_file, delete_file, and shell commands can overwrite.
3. Session approval and permission rules apply before any tool that changes something runs.
4. Changes land in your project immediately, and stopping or closing a subagent does not undo them. Review the diff and run tests before committing.
5. Orek does not give each subagent its own checkout. If you want separate checkouts, tell a subagent to use git worktree add.

Concurrency limits

Use [agent] settings to control how deep subagents can nest and how many run at once:

[agent]
max_live_subagents = 4

Starting a subagent past max_live_subagents makes it wait rather than fail. A subagent that waits on its own subagents (wait_agent, fanout, run_workflow, adversarial_verify, or spawn_agent with block=true) gives up its slot while it waits, so its subagents can run even when max_live_subagents = 1.

Subagents in a resumed session

When you resume a session, its subagents come back with their names, IDs, last status, and last result, and list_agents, send_input, wait_agent, and close_agent reach them as before:

• Interrupted turns: a subagent that was running when the session ended comes back idle, with that turn marked interrupted. Sending it a message starts its next turn.
• Closed subagents and unread messages: closed subagents stay closed until messaged, and unread messages saved when the session ended are still waiting for them.
• Original settings: a restored subagent continues with the model, instructions, and limits it started with.
• Workflow steps: resuming a saved workflow continues a step in the same subagent, unless that subagent has taken another turn since.

Saved subagent transcripts

Each subagent’s conversation is saved whenever a turn ends or stops, and a workflow step’s also as the step runs. List saved conversations, including subagents:

orek session list --include-children

Show a subagent’s session by ID:

orek session show <ID>

You can also copy a subagent’s transcript into a new main conversation with orek session fork. Deleting a main session deletes its subagent transcripts. See Manage sessions.

Trace hierarchy

When trace export is configured, each subagent’s activity appears nested under the turn that started it. See OpenTelemetry export.

Common pitfalls

Before retrying interrupted work, check whether its commands or requests already changed files or external services. See Recover delegated work.

Plan mode + subagents

Plan mode, the approval mode, the execution policy, and the OS sandbox belong to the session and apply to every running subagent:

• In Plan mode, Orek and its subagents can read and investigate but cannot start new subagents or run tools that change things; only the main conversation proposes a plan for your approval.
• Toggling /plan or changing /permissions (for example to yolo) applies immediately to every running subagent.
• Subagent approval prompts name the asking subagent and its ID, in the TUI and in editors.

See Plan and track work for what Plan mode blocks, including the memory tool exception.