Subagents, teams, and parallel work

Choose the smallest delegation tool that fits the work:

Tool	Use it for	Workspace behavior
Subagent	One focused task	Read-only isolation by default, or direct writes with mode: "read-write"
Parallel	Isolated implementations or competing approaches	One temporary writable workspace per branch
Team	Specialists that must coordinate	One isolated workspace per member

A child's transcript stays out of the parent context. The parent receives a bounded result and status events. Use InspectSubagent for a Subagent or Parallel branch, and InspectMember for a team member.

For how Mecatl isolates child workspaces and handles direct writes, see Execution environments.

Watch a delegation in mecatui

A Subagent parent detail shows one-line status summaries for up to 128 recent child tool calls. /toolcalls lists only top-level calls, with no child drilldown. The f6 Agents view shows bounded activity for Subagent children, Parallel branches, and Team members. Each lane retains up to 128 tool calls and 12 separate message previews; messages do not evict calls. An early observed result updates its matching retained call provisionally; the canonical result can confirm or replace it. Older ID-less results match only a unique ID-less pending call by name. Unmatched and evicted results are dropped. These are capped previews, not complete child arguments or results, and do not enter the parent's model context. See Work in the TUI for navigation and unavailable-activity guidance. Interactive clients can surface child permission requests with an attributed, bounded summary; raw child arguments are withheld.

Subagent

Subagent runs one self-contained task in a fresh context. Use it for a focused investigation or change that does not require coordination with other workers. Issue several read-only Subagent calls in one model turn to run them concurrently.

By default, a child can read files and run commands in a temporary worktree. It cannot use Edit or Write, and Mecatl discards any changes made through Shell.

Argument	Purpose
prompt	Provide the complete task and expected result. The child cannot see the parent conversation unless you use fork.
description	Label the work in status views.
agent	Use a named specialist definition.
provider	Select an exact provider together with model, or use model-router with an exact discovered category. Omit it to preserve inherited/operator routing.
model	Use a literal model on the inherited provider or a configured alias. A provider-aware alias carries its pair.
max_turns, max_tool_calls	Tighten the configured limits.
max_run_tokens	Tighten the child's cumulative token limit. Values below 25,000 are raised to that floor.
timeout_ms	Set a wall-clock deadline.
output_schema	Require a JSON result through SubmitResult. Invalid submissions receive up to two correction attempts.
fork	Copy the parent conversation into the child. This cannot be combined with provider, model, agent, or resume.
resume	Continue a previous child in a fresh workspace while preserving its conversation and cumulative token use.
background	Return the child ID immediately and collect the result with SubagentStatus.

Every result includes an agentId, including errors and timeouts. Use it with InspectSubagent, SubagentStatus, or resume.

Direct-write subagents

mode: "read-write" gives the child Edit and Write access to the parent's real workspace. Changes appear immediately, with no fork or merge. An interrupted child can leave partial edits, so use Git to inspect or recover them.

Direct-write calls run serially and never overlap sibling tool calls. They work with fork, resume, and output_schema, but not background. See Agent definitions for routing restrictions on explicit agent and model combinations.

Background subagents

background: true returns immediately while the child continues. Use SubagentStatus with:

• No arguments to list this run's children.
• agent_id to collect one stored result. A result is delivered once.
• wait_ms to wait for up to 120 seconds instead of polling.

Mecatl cancels a running background child when the parent run ends. Its transcript persists and can be resumed later. To cancel it sooner, use the gRPC cancel_child field, POST /v1/sessions/{id}/cancel-child, or x in mecatui.

Parallel

Parallel runs up to 16 self-contained branches, with eight active by default. Each branch has a writable isolated workspace and cannot communicate with other branches. One optional provider/model selector applies to all branches; the judge stays on the parent model.

Use Parallel for competing approaches or isolated implementation branches. For independent read-only research, use concurrent Subagent calls. For workers that must exchange findings, use Team.

join value	Result
all	Return every summary, then remove all branch workspaces. This is the default.
first	Return the first successful branch and preserve its workspace.
judge or best	Use the parent model to choose one branch against criteria and preserve it.

A single branch with join: first or join: judge merges its change into the parent by default. Mecatl applies the diff with git apply and refuses changes to .gitattributes. Multi-branch calls never merge automatically. A merge conflict preserves the winning workspace for manual recovery.

Each branch result includes a branch ID for InspectSubagent.

Team

Team coordinates specialists that need to share tasks and findings. It costs more than an independent Subagent or Parallel call, so use it only when ongoing coordination matters.

Each member has a name, role, optional mutating flag, and optional provider/model selector. The first member is the lead: describe the final report it must produce. Other members should record findings and notify the lead. A named specialist accepts a model-only override, not a provider-bearing selector.

Members are read-only by default. A mutating member gets a private writable copy of the workspace. Team workspaces are never merged or preserved, so the durable deliverable is the lead's consolidated report. Use InspectMember when you need one member's detail, passing the ID from the result's Team id: line.

--max-team-tokens sets a cumulative team budget. A call can tighten that value with max_team_tokens. When the team crosses the limit, it stops scheduling rounds but lets the current round and lead synthesis finish.

Automatic model routing

An operator can map task categories to model aliases in user-global settings. For setup and examples, see Model routing.

Routing fills only an unset target. It does not override an explicit selector, a pinned specialist, fork, or resume. To select a category without classification, use provider: "model-router" and its discovered category as model; an unavailable explicit category fails instead of inheriting. Automatic classification or model-build failures fall back to the child's ordinary model. --subagent-model-router=false disables a configured router.

Operator defaults

• --subagent-model sets the fallback model for children that do not have a pinned or routed model.
• --enable-parallel=false removes the Parallel tool.
• Child permission rules determine which delegated calls run automatically. See Permissions and posture.
• --subagent-ask-reviewer lets a headless model review eligible child permission requests.

Next steps

• Permissions and posture for delegated approval behavior.
• Agent definitions to define named specialists.
• Core tools for the rest of the default catalog.