Subagents

The agent can delegate self-contained work to subagents. A subagent is an ordinary malac agent with its own, fresh context window. It gets a complete brief, works on its own, and reports back. Several subagents can run at the same time, so a research question, a refactor and a test run can proceed side by side.

You don’t call subagents directly; you ask for work, and the agent decides when to delegate. Asking for it explicitly helps: “use subagents to review each crate in parallel”.

The delegation tools

Tool	What it does
agent_spawn	Start a subagent with a brief. By default it waits and returns the report.
agent_wait	Wait for subagents and collect their reports
agent_send	Send a follow-up to a subagent, which keeps its context
agent_list	List your subagents with status and current activity

agent_spawn takes:

Argument	Meaning
task	The complete brief: goal, context, files, what done looks like. The subagent cannot see the parent’s conversation.
label	A short name shown in the UI, such as tests
agent	An agent type, such as reviewer
model	A different model for this subagent, as provider/model
read_only	Only allow tools that cannot change anything
background	Return immediately; collect the report later with agent_wait

The delegation tools never ask for permission. The subagent’s own tool calls go through the same permission checks as the main agent’s, and its prompts are labelled with its name.

Running in parallel

Several agent_spawn calls in one response run in parallel, up to agents.max_concurrent at a time; the rest wait for a free slot. agent_wait waits for up to 30 minutes by default (timeout, in seconds).

[agents]
max_concurrent = 4   # subagents running at the same time
max_depth = 3        # how deep subagents may nest (the default)

With max_depth = 3, subagents can nest three levels below the main agent; agents at depth 3 do not get the delegation tools.

Picking a model per subagent

Give your models a description, and the agents that can delegate see an Available models section in their system prompt: every model in your providers’ models lists, plus every model with a description, and advice to match the model to the task (a fast, cheap one for searches, summaries and mechanical edits; the strongest one for design, hard debugging and reviews; one with vision for screenshots). The main agent then passes the model it chose to agent_spawn as model.

[models."lora/fast"]
description = "fast and cheap: searches, summaries, mechanical edits"

[models."lora/smart"]
description = "strongest reasoning: design, hard bugs, reviews"

[models."lora/vision"]
description = "reads screenshots and images"

Without a model (or an agent type that sets one), a subagent uses the default model. You can also ask for one directly: “use lora/fast for the test runner”.

What a subagent gets

• A fresh context with the brief as its first message, and a system prompt that tells it it is a subagent.
• The same tools as the main agent, minus the delegation tools at the depth limit. With read_only, only Safe tools: reading, searching, memory, the todo list, malac_settings and delegation; any subagent it starts is read-only too. With an agent type, the tools that type lists.
• The model from model, else from the agent type, else the main model.
• The same working directory, configuration, memory and MCP servers.

Watching subagents

Everything a subagent does is an event on the same bus as the main agent, so every front end can show it:

Terminal. In the line mode, each step is one indented line, and the finish is marked:

● agent_spawn tests: Run the workspace tests and report every failure…
  ↳ tests started (lora/fast)
  ↳ tests · bash cargo test --workspace
  ↳ tests · read crates/core/src/parser.rs
  ✓ tests finished

The terminal UI shows a live card per subagent with its current step; click it (or select it and press Enter) to open its transcript, and Esc to come back. The sidebar shows the tab’s agent tree. F3 opens every agent of the workspace as a list or as the agent map (press F3 again to switch): each agent a box with its model, state, current step, tokens and cost, subagents to the right of their parent. Enter opens an agent, x (or Ctrl+X in the list) stops it. In the line mode, /agents prints the tree with each agent’s status and current activity.

Web UI. The Agents page is a tree of every live agent with its status, model, activity and cost, and a live preview of the selected one; click a subagent card in a transcript to open its full live transcript. See Web UI.

Logs. Each subagent has its own transcript. malac sessions show <id> prints a session and all of its subagents, indented. malac sessions list --all includes subagent sessions.

Stopping

Ctrl+C (or Stop in the web UI) cancels the current turn and every subagent it started. Cancelling an agent always cancels its whole subtree.

Tips

• Delegation pays off for work that is self-contained and parallel: reviewing several modules, researching several options, running a slow test suite while editing elsewhere.
• Keep briefs complete. The subagent sees nothing of the parent conversation.
• Use read_only for research and review, and describe your models so the agent picks a cheaper one for mechanical work.
• Define reusable roles as agent types.

The tutorial Delegating to subagents shows a full run.