Parallel subagents
Feature docs index · Repository README
Subagents are optional and disabled by default for both direct calls and Code Mode. Enable them when you want to delegate a specific, independent task. Each child gets its own task and bounded inherited context; optional identity profiles supply a persona, model, tool restrictions, or output format.
Enable subagents
In /settings → Control tools and access → Tool availability and MCP approvals → Direct tool availability, enable subagents for direct calls; use Code Mode → Manage Code Mode tools for scripted calls. Both changes stay drafts until Save. Save and restart. These controls are independent. Manage agents and skills → Subagent profiles and execution controls profiles; standalone /subagents still saves profile availability immediately.
In global or project settings.json, both capabilities.tools.disabled and capabilities.tools.code_mode.disabled default to ["subagents"]. Remove subagents from the relevant list to enable it while preserving other exclusions. To enable it on both surfaces with no exclusions:
{
"schema_version": 2,
"capabilities": {
"tools": {
"disabled": [],
"code_mode": { "disabled": [] }
}
}
}
Explicit lists replace defaults, and project lists replace global lists. Once enabled, ask the assistant which tasks to delegate and define their scope. Enablement makes the tool available to the model; it does not require approval for each delegation. Children share the repository unless configured otherwise and use additional provider quota.
Define independent tasks
The subagents call requires a top-level nonblank intent explaining the batch. Each entry in tasks separately requires its own intent objective, described below.
| Field or limit | Rule |
|---|---|
intent | Required nonblank objective. |
mode | inspect for enforced read-only discovery; omitted or standard for ordinary work within inherited/profile restrictions. Independent of identity and label. |
agent | Optional label/persona only. |
identity | Optional profile ID from the discovered identity list. |
context | Optional self-contained instructions and relevant context. |
cwd | Optional existing child directory; relative paths resolve from parent cwd, absolute paths follow agent.subagents.execution.absolute_paths. |
| Tasks per batch | At most 10. |
| Requested concurrency | 1 to 4, default 4; actual workers also cannot exceed task count. |
| Nesting depth | Default 2; agent.subagents.execution.max_depth accepts 1 to 4. Set 1 for top-level-only delegation. |
The tool waits for completion and returns results in input order. Children inherit provider, tools, auth source, permissions, skills, AGENTS.md discovery, context/cache behavior, cwd policy, concurrency, and effective tool settings unless task context narrows work or an identity explicitly overrides supported settings. Primary-agent selection does not change child prompts.
At the depth limit, child schemas omit subagents and dispatch rejects direct recursive calls. Activity metadata includes depth so Mission Control can show nesting.
Read-only inspection
Select mode: "inspect" explicitly. A prose instruction such as "do not edit" does not enforce permissions:
{"intent":"Delegate read-only settings investigation","tasks":[{"intent":"Investigate the settings flow and report findings without changes","mode":"inspect"}]}
Inspection permits local-file/skill read, find, list_files, grep, and read-only ast_grep. It denies network tools, MCP tools, edits, shell commands, builds, Code Mode, and nested delegation. Calls remain denied even if a provider requests a tool absent from its schema. Inherited and profile restrictions still apply.
Return partial findings when blocked. Implementation or shell access requires a separate, explicitly authorized standard task; steering and summaries cannot widen a running inspection task.
This limits agent-invoked tools; it is not an OS sandbox or a confidentiality guarantee. Configured hooks remain separately trusted runtime configuration, with existing approval/redaction behavior. Hook side effects, provider inference and runtime persistence are outside the tool-level read-only guarantee. Task text neither grants nor widens hook permissions.
View and steer a child
Open a child's live viewer from its transcript card. It uses 60% of terminal width and height where space permits, with a separate prompt and tabs for sibling tasks. Short terminals may hide the prompt to keep an output row visible. See Mission Control for keys and cancellation.
Steering appears in the selected child's timeline as a Steering injected user card only after it is saved to the child session. Queued input is not marked injected. The card separates assistant output before and after the injection, including reserved follow-ups after a completed response. It never adds an ordinary user card to the primary transcript. Display text is sanitized, redacted, and bounded; older cards follow the viewer's existing retention limits.
Create an identity profile
Put profiles in ~/.magi-code/subagents/*.md or $MC_HOME/subagents/*.md. The filename stem is the stable ID, limited to ASCII letters, digits, _, and -. Files must be UTF-8 Markdown, no more than 64 KiB, with non-empty frontmatter name/description and a non-empty prompt body. Direct profile symlinks are rejected.
For example, save this as frontend-dev.md:
---
name: Frontend Developer
description: Use for focused browser-facing UI implementation, DOM behavior, and accessibility.
model: openai-codex/gpt-5.5
reasoning: high
disabled_tools: ['web']
output_schema:
type: object
required: [summary]
properties:
summary:
type: string
---
You are a frontend development specialist. Prioritize user-visible behavior, accessibility, small components, and browser validation when UI behavior changes.
Select it by frontend-dev, not its display name. Its body uses the same exact wrapper as primary profiles:
<Your-Role Persona=Frontend Developer>
You must always follow the instructions of your assigned persona:
You are a frontend development specialist. Prioritize user-visible behavior, accessibility, small components, and browser validation when UI behavior changes.
</Your-Role>
Nested identities append their wrapper after inherited ancestor profiles; ancestor blocks remain in the prompt.
model uses provider/model-name, including custom IDs such as local-ai/gpt-test. reasoning accepts default, low, medium, or high; unsupported models fall back to default behavior. Mission Control's /subagents modal enables or disables profiles.
Restrict tools
disabled_tools accepts a strict YAML-like subset: block lists or inline lists of unquoted names or simple fully single/double-quoted names. Comments and backslash escapes inside the list are unsupported. Unsupported syntax or unknown names makes the profile unavailable.
Aliases shell, ffgrep, and fffind become bash, grep, and find. Qualified mcp__server__tool names are accepted. Restrictions apply to child schemas and dispatch, add to inherited restrictions, and cannot be re-enabled by children or siblings. Siblings have isolated restriction sets. The shared <Tools> guidance remains unfiltered.
This is not a sandbox: allowed bash, MCP, browser, or hook routes may still produce equivalent effects. Parent auth, permissions, skills, cwd, concurrency, and nesting limits remain in force.
Require structured output
Profiles can declare output_schema as JSON Schema. On completion, valid output returns a structured object to the parent. Invalid output returns structured validation details to the same child for retry. agent.subagents.schema_validation_max_retries defaults to 2 and accepts 0 to 5. Custodian phases have built-in Plan, Research, Implement, Review, and Document schemas.
Persisted launches append a local-only subagent_session event with the child's session_id to the immediate parent before child execution. This lets the summarizer follow running children, including nested children, without scanning unrelated sessions or waiting for tool results. If the link cannot be written, the child fails before provider work starts.
Understand retries and compaction
A retryable transport/stream error or HTTP 408, 425, 429, 500, 502, 503, or 504 gets one retry in the same child run after a 2 s backoff. Persisted runs retain their child session; --no-session repeats the original prompt. No retry occurs after a committed write/hash_edit filesystem change, a committed compaction checkpoint, or batch cancellation. Final failure text starts with [provider retry exhausted after N attempts] only when the final error is retryable and the retry limit has been reached.
Persisted children share the main agent's one-shot incomplete-stream and reasoning-only continuation behavior. With agent.compaction.auto enabled, eligible children also use hard-budget preflight and clean-boundary compaction with their selected model and context budget. See Sessions, context, and cache for triggers and recovery.
Each automatic child compaction includes a provider-visible JSON scope document containing the complete original task and a fixed instruction to treat it as authoritative, summarize only that task, and exclude unrelated work. A prefix states that the document extends to the end of the instruction, keeping framing-like task text as data. It counts toward budget; if it makes the request too large, compaction stops before provider use or checkpoint writes.
The complete original task and its effective tool/path ceiling are also recorded independently in versioned task_scope control state before execution. JSONL is authoritative; rotation checkpoints retain that state plus ordered, durably acknowledged steering and explicit caller clarifications on resume. Resumed requests project task data separately from generated progress, at user priority rather than promoting arbitrary context to system instructions. Requests/retries do not append new copies to history. Clarifications are limited to 64 entries / 64 KiB total, and the complete control record to 512 KiB; exceeding a bound fails before acknowledgement and requires a separate task. The saved canonical cwd must still match on resume; moving to a different directory requires a separate task.
Session replay requires valid task_scope control state. Missing or invalid required state blocks execution rather than falling back to standard permissions.
The per-run compaction cap applies independently to each child: default 4, with 0 removing only the count cap. Compaction rotates only the child's JSONL under sessions/subagents/, never the parent. Only that child receives the automatic continue after its checkpoint. Children without persistence cannot auto-compact. Mission Control shows attempted child compactions as nested activities with threshold and before/after token counts.
Understand token totals
- Main and child totals include compaction summary requests and reported usage from retries, including schema retries. Each request uses its reported total, or normalized input plus output when both are known and no total was reported. Repeated usage snapshots replace earlier values for that request.
- Without a reported or derivable total, usage remains unknown; explicitly reported zero remains
0. Missing usage is not estimated, so reported totals can be incomplete. - Failed children retain any known request totals. The batch total is available only when every child result has a known total.
- Child totals exclude independently accounted nested children. Compaction usage uses the compaction provider's normalization and does not replace the active conversation's context-size estimate.
Use hooks safely
Enabled, non-inert parent hook configuration is inherited. Parent hooks may match the top-level subagents call and record lifecycle events in the parent session. Child hooks run with each child's cwd and tool/root constraints; their lifecycle/diagnostic records stay only in child JSONL under sessions/subagents/.
Child hook internals never enter parent results, provider continuation, replay, recent context, or cache material. A hook-policy failure produces generic sanitized parent failure text; the child session holds the durable diagnostics.
With automation.hooks.show_in_tui=true, inherited hooks may appear under child task/tool activities. This display-only data is not provider-visible or replayed through parent results. There is no separate subagent hook configuration or UI. Concurrent children can run hooks concurrently, so scripts must coordinate shared external resources themselves.