Delegate focused work
Give a focused piece of work to a specialist Agent. Bring the result back to the task.
A subagent is an independent Agent started by Levin within the current task. It receives an assignment from the main Agent, reads, analyzes, or executes in its own context, then returns the result to the main conversation. The subagent handles the focused work. The main Agent still owns the final judgment and integration.
Start with a clear assignment
Subagents work best on a focused task with one owner and one result, such as finding an implementation, organizing evidence, or completing an independent change. Keep unresolved decisions that require your judgment in the main task.
- Choose a role. Type
@in the composer, open Agents, and select Agent, Explore, Plan, or an enabled custom Agent. - Define the work. State the objective, inputs, allowed scope, expected deliverable, and required checks.
- Let it run. Levin starts the subagent in an independent context. Independent work can run separately.
- Return to the main task. Review the conclusion, file locations, and verification evidence before the main Agent decides whether to use it.
An independent context does not automatically include every detail from the main conversation. Put the required background, files, and constraints in the assignment.
What to delegate
| Delegate | Keep with the main Agent |
|---|---|
| Code, documentation, or configuration work with clear inputs and a deliverable. | Work that requires the user to decide the direction, tradeoff, or final scope. |
| Broad read-only search, call-chain tracing, and evidence collection. | A small lookup that takes only a few minutes and needs no separate explanation. |
| Several independent checks that can run without depending on one another. | Steps that must run in order or would edit the same files at the same time. |
| A specialist role with stable responsibilities, tool boundaries, and output format. | Open-ended work whose objective, inputs, or completion condition is still unclear. |
Delegation does not transfer responsibility. The main Agent still reviews the evidence and decides how to integrate the result.
Roles in the Agents list
The Agents tab in the capability picker shows the built-in and custom roles available now. A source label tells you where a role comes from, not whether it is running.
| Role | Purpose | Best for |
|---|---|---|
| Agent | The default built-in Agent, working within the current permissions. | A self-contained implementation, targeted fix, verification run, or focused task that needs read and write tools. |
| Explore | A read-only exploration Agent. | Searching code and files, tracing dependencies, locating implementations, and collecting evidence. |
| Plan | An implementation-planning Agent. | Understanding requirements, breaking work into steps, identifying risks, and setting an execution order. |
| Custom Agent | A specialist role from global configuration or a plugin, such as pyrosetta-coder. | Work that needs a stable domain method, dedicated tools, or a consistent output format. |
Role names and sources come from the current Agents list. They change with plugin state and local configuration.
Where custom Agents come from
The Agents list includes built-in roles as well as specialist roles from global configuration or plugins. A plugin stores subagent definitions in its agents/ directory, using frontmatter and system instructions. The role appears in the picker only while the package is enabled.
| Definition | What it controls |
|---|---|
| Name and description | How the role appears in the list and when the main Agent should delegate to it. |
| Model and thinking level | The model configuration for this role. Without an override, it follows the main task. |
| Tool scope | Which file, command, network, MCP, or remote-device tools the role may call. |
| System instructions | The role's responsibilities, execution boundaries, evidence, and output format. |
| Source and enabled state | Whether the role is built-in, globally configured, or plugin-provided, and whether it can be selected now. |
The description answers “when should this role be selected?” System instructions answer “what should it do next?” Make both specific enough for the main Agent to delegate without guessing.
Tools and permissions follow the main task
A subagent is not a way around permissions. It works inside the project and execution mode chosen for the main task. Its ability to read or write files, run commands, access the network, call MCP, or use a remote device depends on both the current permissions and the role's tool scope.
| Boundary | Actual behavior | What to check |
|---|---|---|
| Read-only role | Can search, read, and analyze, but cannot modify files. | Prefer Explore or Plan for discovery and planning. |
| Write tools | Editing, writing, and command execution follow the main task's execution mode and approval policy. | High-risk actions still require confirmation. |
| MCP and remote devices | Only services and devices connected to the current task and allowed by its permissions are visible. | Confirm the service is healthy, the tool is enabled, and the target device is correct. |
| Project files | Uses the working directory selected by the main task. Delegation does not create another workspace. | Keep multiple workers from editing the same file at the same time. |
Subagents do not expand permissions. Confirm the tools, project scope, and approval policy before delegating, then review the actual changes when the work returns.
Start, return, and integrate
The main Agent can delegate automatically from a role description, or you can choose a role directly with @. When the subagent finishes, its result returns to the main conversation. The main Agent then decides whether to accept it, ask a follow-up, or continue editing.
- Separate the work. Give one role an independent check or change.
- Include the context. State the files, scope, constraints, and deliverable in the assignment.
- Wait for the result. Parallel work should be independent. Do not have several workers edit the same file.
- Review the evidence. Check the report, changes, command output, and unresolved issues before integrating the result.
A subagent's return is input, not the final conclusion. Scientific judgment, product decisions, and release approval remain with the main Agent and the user.
Read the result in the main conversation
Subagent status and output stay with the main task. Check whether the work finished, then inspect what it actually did. A one-line summary is not enough to establish that the result is usable.
| Check first | Confirm | Next step |
|---|---|---|
| Status | Running, completed, waiting, or failed. | Wait if it is running. Resolve the missing dependency if it failed or needs input. |
| Task report | Whether it answered the assignment and identified unfinished work. | Narrow the scope and delegate again when needed. |
| Evidence and deliverables | File locations, command output, test results, or cited sources. | Verify them in the main task before accepting the result. |
The returned report supports the main Agent's decision. It does not replace final review.
Write a useful assignment
| Part | State clearly |
|---|---|
| Objective | The question to answer or result to deliver, rather than “take a look.” |
| Inputs | Files, structures, context references, and known assumptions. |
| Boundary | What the worker may access or change, and what it must not do. |
| Completion condition | Which evidence, tests, or files must return, and when the worker must stop and ask. |
The clearer the role description, the more reliable automatic selection becomes. The clearer the assignment, the easier its result is to verify.