# Parallel subagents
[Feature docs index](README.md) · [Repository README](../../README.md)
## Purpose
Delegate bounded independent child-agent tasks and discover optional prompt-only identity profiles.
## Details
`parallel_subagents` delegates independent tasks to child agent sessions.
Limits and behavior:
| Limit | Value |
| --- | ---: |
| Maximum tasks per batch | `10` |
| Default concurrency | `4` |
| Allowed requested concurrency | `1` to `4` |
| Nesting depth limit | `2` by default; configurable with `tools.parallel_subagents.max_depth` (`1` to `4`) |
Each child receives bounded inherited context and explicit task instructions. Children use the same provider, tools, skills, `AGENTS.md` discovery, context/cache behavior, and effective tool settings as the parent unless narrowed by task context or overridden by a selected identity profile. Subagent task activity metadata includes its depth so Mission Control can show where nested work sits. When the current subagent depth reaches `tools.parallel_subagents.max_depth`, `parallel_subagents` is omitted from provider tool schemas for that child; runtime dispatch still rejects direct recursive calls at the same limit.
Hook behavior is inherited by default. Parent tool-call hooks can still match the top-level `parallel_subagents` tool call, and those parent hook lifecycle records persist in the parent session. Child subagent tool calls also inherit the same parent hook configuration when hooks are enabled and non-inert; inherited hooks run with each child task cwd and child tool/root constraints.
Child hook lifecycle and diagnostic records persist only in child session JSONL under `sessions/subagents/`. Parent `parallel_subagents` results, parent provider continuation, parent session replay, recent context, and context cache material exclude child hook internals. If a child run stops because a local hook policy failed, the parent aggregate uses generic sanitized failure text and the child session remains the durable diagnostic source.
When `hooks.show_in_tui=true`, Mission Control may show inherited child hook activity locally under the child task/tool activity. That live activity is display-only; it is not provider-visible and is not replayed through the parent result. No new subagent hook config schema or UI is added. Concurrent subagents may run inherited hook processes concurrently, so hook scripts must coordinate any shared external resources themselves.
Discoverable identity profiles live under `~/.magi-code/subagents/*.md` or `$MC_HOME/subagents/*.md`. The filename stem is the stable identity id and must use only ASCII letters, digits, `_`, or `-`. Each profile is a UTF-8 Markdown file up to 64 KiB with YAML-style frontmatter containing non-empty `name` and `description`, followed by a non-empty prompt body:
```md
---
name: frontend-dev
description: Use for focused browser-facing UI implementation, DOM behavior, and accessibility.
model: openai-codex/gpt-5.5
reasoning: high
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.
```
Optional `model` uses provider-qualified `provider/model-name` syntax, including configured custom provider ids such as `local-ai/gpt-test`. Optional `reasoning` accepts `default`, `low`, `medium`, or `high`; unsupported models fall back to default reasoning behavior. Optional `output_schema` declares a JSON Schema contract for the child response. Profile overrides change only the selected child agent run. Tools, auth source, permissions, skills, cwd, concurrency, and nesting limits stay inherited from the parent runtime. Set `tools.parallel_subagents.max_depth` in `~/.magi-code/settings.json` to control nesting depth; default is `2`, and `1` restores top-level-only subagents.
Schema-validated output:
- Profiles can declare `output_schema` in frontmatter. The schema is validated when the child completes.
- Valid output returns a structured object to the parent instead of untyped text.
- Invalid output returns a structured validation error with details to the same child, then retries.
- Retry count is controlled by `subagents.schema_validation_max_retries`; default `2`, valid range `0` to `5`.
- Custodian delegation phases have built-in schemas for Plan, Research, Implement, Review, and Document outputs.
---
[Back to feature docs](README.md) · [Back to repository README](../../README.md)