# src/subagents KNOWLEDGE BASE
## OVERVIEW
Bounded child-agent runtime: parallel task tool, identity profile binding, child cwd/session/activity isolation.
## WHERE TO LOOK
| Module boundary | `mod.rs` | Public dispatch entry; depth gate before scheduler. |
| Tool DTO/limits | `dto.rs` | Max tasks/concurrency/depth constants; task/result JSON shape. |
| Run config | `config.rs` | Parent agent/provider/tools/cwd/cancellation/hooks/profile bundle. |
| Cwd safety | `cwd.rs` | Canonicalizes child cwd; blocks parent escape unless absolute-path policy allows. |
| Identity profiles | `profiles.rs` | Loads `$MC_HOME/subagents/*.md`; validates ids; renders selectable profile prompt. |
| Parallel scheduling | `scheduler.rs` | Prepares `gN` tasks, spawns bounded workers, waits, cancels stalled/unwanted work. |
| Child execution | `worker.rs` | Runner role: builds child agent/provider, sessions, inherited tools/hooks, truncates output. |
| Activity bridge | `activity.rs` | Maps child stream/tool events into parent activity tree. |
| Coverage | `tests.rs` | Safety limits, cwd, identity, scheduler, output truncation regressions. |
## CONVENTIONS
- Keep `subagents` bounded: tasks ≤ 10, concurrency ≤ 4, default max depth 2.
- Check depth before child scheduling; nested tool enablement must respect parent `ToolRuntime` limits.
- Resolve child cwd through `resolve_child_cwd`; canonical path first, policy second.
- Preserve `g1`, `g2`, ... stable result ids from scheduler order.
- Identity assignment stays opt-in via `SubagentTask.identity`; plain `agent` remains label/persona only.
- Validate identity ids with `validate_subagent_identity_id`; no path-ish or whitespace ids.
- Load identities only from regular markdown files under `$MC_HOME/subagents`; no symlinks.
- Profile prompt appends to parent agent; provider/model/reasoning overrides come from profile metadata.
- Provider runtime inherited unless profile model override resolves explicit provider selection.
- Child tools inherit parent safety, cwd, hooks, cancellation, and subagent depth.
- Child sessions live under `sessions_root/subagents`; parent result stores session id/path only.
- Activity events must form batch → task → assistant/tool tree; report progress during child streaming.
- Output returned to parent is bounded; preserve truncation marker semantics.
## ANTI-PATTERNS
- Do not widen cwd/root access to make failing child paths work.
- Do not bypass `resolve_child_cwd` or canonicalization.
- Do not increase task, concurrency, depth, timeout, or output limits without focused safety tests.
- Do not treat `agent` as identity; only `identity` selects profile prompt/model.
- Do not auto-select identities from descriptions, labels, or filenames outside validated profile map.
- Do not let child provider loops ignore parent cancellation or semantic-progress timeout.
- Do not expose raw child tool output beyond truncation caps.
- Do not make profile files executable, symlink-following, or cwd-relative.
- Do not route child hooks/tools outside inherited parent safety boundaries.
- Do not add public API from this module unless external tests prove need.