Parallel Subagents
Relevant source files
The following files were used as context for generating this wiki page:
Parallel Subagents are specialized child AI entities spawned by the M31A primary agent to handle complex tasks concurrently in isolated environments. These subagents operate with a recursion depth limit and are confined to dedicated Git worktrees to prevent interference with the main codebase until their work is verified.
Sources: README.md:120-122, internal/tools/extra_test.go:1037-1040
Architecture and Isolation
Subagents are managed by a SubagentManager that orchestrates their lifecycle, including creation, execution, and cleanup. The system enforces strict isolation and resource constraints to ensure system stability.
Worktree Isolation
Each subagent operates within a unique Git worktree. This provides a clean, independent filesystem state for the agent to perform its tasks without affecting the primary session's working directory. The manager is responsible for cleaning up these orphaned worktree directories upon completion or failure.
Recursion and Concurrency Limits
To prevent runaway agent spawning and resource exhaustion, the system imposes a maximum nesting depth of 2. Additionally, tool execution within subagents is governed by a global concurrency semaphore and per-risk-level rate limits.
The following diagram illustrates the relationship between the primary agent and its parallel sub-components:
Component Overview
| Component | Description |
|---|---|
| Subagent Manager | Orchestrates the lifecycle, worktree isolation, and depth limits for child agents. |
| Git Worktree | Provides the isolated filesystem environment where the subagent performs modifications. |
| Agent Tool | The mechanism through which the LLM invokes a child agent, providing a task description and prompt. |
| Dispatcher Adapter | Bridges the subagent to the primary toolset with governed permissions. |
Sources: internal/tools/extra_test.go:1075-1085, internal/tools/subagent/manager.go, internal/tools/subagent/worktree.go
Agent Tool Execution
The Agent tool is the interface used to initialize a subagent. It requires a task description and a specific prompt to begin execution.
Execution Flow
- Validation: The tool checks if a manager is configured and ensures required parameters (description, prompt) are present.
- Isolation Setup: The manager initializes a new Git worktree for the requested isolation mode.
- Execution Loop: The subagent enters an iterative "autonomous" mode where it uses tools to complete the assigned task.
- Cleanup: Once the task is finished or a timeout occurs, the worktree is dismantled.
Behavior and Constraints
Subagents follow specific behavioral rules defined in their autonomous prompts:
- No Narration: Subagents must avoid describing future actions; they are instructed to use tools directly (e.g., call
FileReadinstead of saying "I will read the file"). - Read-Before-Write: Before modifying any file, subagents are required to read the target file and all related dependencies (imports, callers, configs).
- Resource Budget: Subagents operate under a token budget; the manager enforces cleanup if budgets are exhausted.
- Destructive Safety: Destructive commands like
rm -rforgit reset --hardrequire explicit confirmation, even within the isolated worktree.
Sources: internal/engine/workflow/prompts/autonomous.md:12-30, internal/tools/extra_test.go:1037-1040
Technical Specifications
| Parameter | Type | Description |
|---|---|---|
description | string | High-level goal of the subagent task. |
prompt | string | Specific instructions for the subagent to follow. |
isolation | string | Environment type (typically worktree). |
MaxAgentDepth | integer | Maximum nesting limit (Default: 2). |
Sources: internal/tools/extra_test.go:1042-1055, README.md:282
Parallel subagents allow M31A to scale its capabilities by delegating sub-tasks to isolated, concurrent processes. This architecture ensures that large-scale refactors or multi-component features can be explored in parallel before being integrated into the main branch.