Back to Agents

Architecting Hierarchical Agent Teams: Supervisor Routing, Task Handoffs, and Stop Gates

Prevent runaway AI loops and context bloat by structuring hierarchical supervisor-worker agent teams with stateful handoffs and verified stop gates.

Architecting Hierarchical Agent Teams: Supervisor Routing, Task Handoffs, and Stop Gates
Image credit: labs.zeroshot.studio

Contents

The Failure Mode of Monolithic Agent Loops

Most developers begin their vibe-coding journey with a single prompt inside an IDE extension or terminal runner. You hand the model a feature request, grant it shell permissions, and watch it alternate between reading files, running npm scripts, and applying edits.

For tasks touching one or two files, this approach functions well. However, when a task spans multiple modules, database migrations, or third-party integrations, single-agent loops hit a predictable wall. We call this the monolithic context trap:

  1. Context Pollution: Every terminal command, compiler warning, test failure, and diff accumulates inside the session history. As the conversation stretches past 50 turns, attention mechanisms dilute, causing the model to forget initial architectural constraints.
  2. Circular Correction Traps: If an agent attempts to fix a TypeScript error and introduces a runtime bug, it frequently alternates between two conflicting patches. It forgets the underlying design intent and begins thrashing.
  3. Branch Contamination: A single runaway agent modifies unstaged files across disparate directories. When a fatal error occurs, rolling back requires discarding both valid and broken modifications simultaneously.

To escape this trap, production systems decouple planning from execution. By establishing a hierarchical architecture, a high-level supervisor agent orchestrates short-lived, single-purpose worker subagents that operate inside isolated sandboxes.

Architecture Flow
flowchart TD
    User([Task Specification]) --> Supervisor[Supervisor Orchestrator]
    Supervisor --> Planner[Phase Decomposition]
    Planner --> Routing{State Machine Router}
    
    Routing -->|Phase 1: Database Migration| WorkerDB[DB Worker Worktree]
    Routing -->|Phase 2: API Endpoints| WorkerAPI[API Worker Worktree]
    Routing -->|Phase 3: Integration Tests| WorkerTest[Test Worker Worktree]
    
    WorkerDB --> Gate1{Stop Gate 1: Migrations & Linters}
    WorkerAPI --> Gate2{Stop Gate 2: Schema & Unit Tests}
    WorkerTest --> Gate3{Stop Gate 3: E2E Verification}
    
    Gate1 -->|Pass| Supervisor
    Gate2 -->|Pass| Supervisor
    Gate3 -->|Pass| GitMerge([Atomic Merge to Main])
    
    Gate1 -.->|Fail: Max Turns| CircuitBreaker[Circuit Breaker / Alert]
    Gate2 -.->|Fail: Max Turns| CircuitBreaker
    Gate3 -.->|Fail: Max Turns| CircuitBreaker

Before orchestrating autonomous subagents across a codebase, ensure you have reviewed Prompt injection guardrails to prevent untrusted inputs from altering tool execution flags.

Hierarchical Architecture: Supervisor vs Worker Roles

In a hierarchical multi-agent system, agents are categorized into two strict functional classes:

The Supervisor Orchestrator

The supervisor does not write application code directly. Its primary responsibilities are:

  • Ingesting user requirements and breaking them into a dependency-ordered directed acyclic graph (DAG) of discrete milestones.
  • Spawning worker subagents with isolated, scoped instruction sets.
  • Receiving structured execution reports and diff summaries from workers.
  • Evaluating milestone completion against acceptance criteria.
  • Halting runaway tasks when an execution threshold is breached.

The Specialized Worker Subagent

Worker subagents are stateless, ephemeral processes configured to execute a single atomic objective (for example, generating a database migration or writing a specific API route handler).

  • A worker receives only the context necessary for its milestone, avoiding historical context bloat.
  • It operates inside a dedicated branch or worktree, preventing collision with uncommitted workspace changes.
  • It terminates immediately upon reaching its goal or exhausting its turn budget.

For teams deploying worker sandboxes, our companion guide on agent runtime workspace isolation details how to automate branch-level worktrees for background runners.

Step 1: Designing the Supervisor Routing Graph

The supervisor maintains a deterministic state machine representing the lifecycle of the overall feature. Rather than leaving the control flow to open-ended LLM decisions, the transition rules are hardcoded in the orchestration harness.

Here is a practical state machine implementation in TypeScript:

typescript
// supervisor-router.tsexport type PhaseStatus = 'pending' | 'in_progress' | 'passed' | 'failed';export interface Milestone {  id: string;  name: string;  workerType: 'architect' | 'coder' | 'tester';  dependencies: string[];  status: PhaseStatus;  maxTurns: number;  worktreePath?: string;}export class SupervisorEngine {  private milestones: Map = new Map();  constructor(plan: Milestone[]) {    for (const m of plan) {      this.milestones.set(m.id, m);    }  }  public getNextEligibleMilestone(): Milestone | null {    for (const [, milestone] of this.milestones) {      if (milestone.status === 'pending') {        const depsResolved = milestone.dependencies.every(          depId => this.milestones.get(depId)?.status === 'passed'        );        if (depsResolved) {          return milestone;        }      }    }    return null;  }  public updateStatus(id: string, status: PhaseStatus): void {    const m = this.milestones.get(id);    if (m) {      m.status = status;    }  }  public isComplete(): boolean {    return Array.from(this.milestones.values()).every(      m => m.status === 'passed'    );  }}

By enforcing that dependencies must be verified before the next milestone executes, the supervisor prevents workers from building on top of broken or unverified foundations.

Step 2: Schema-Validated Task Handoff Contracts

Unstructured English briefs passed between agents lead to misinterpretations and missed edge cases. To ensure consistency, task handoffs between the supervisor and worker must follow a typed JSON schema.

When the supervisor dispatches a milestone, it writes a task-contract.json into the worker's working directory:

json
{  "$schema": "https://json-schema.org/draft/2020-12/schema",  "taskId": "phase-02-auth-routes",  "objective": "Implement JWT authentication route handlers with bcrypt password hashing",  "targetFiles": [    "src/routes/auth.ts",    "src/lib/jwt.ts"  ],  "readOnlyFiles": [    "src/db/schema.ts",    "src/types/user.ts"  ],  "acceptanceCriteria": [    "POST /api/auth/login returns HTTP 200 with JWT on valid credentials",    "POST /api/auth/login returns HTTP 401 on invalid password",    "pnpm test tests/auth.test.ts exits with code 0"  ],  "resourceLimits": {    "maxTurns": 12,    "maxTokensPerTurn": 4096,    "timeoutSeconds": 300  }}

Upon completion, the worker must return a structured result file (task-result.json):

json
{  "taskId": "phase-02-auth-routes",  "status": "success",  "turnsUsed": 7,  "modifiedFiles": [    "src/routes/auth.ts",    "src/lib/jwt.ts"  ],  "verificationCommand": "pnpm test tests/auth.test.ts",  "verificationExitCode": 0,  "summary": "Implemented login and token refresh handlers. All 6 integration tests passing."}

If the worker fails to produce a valid task-result.json matching the schema, the supervisor marks the phase as failed and triggers remediation rather than guessing the outcome.

Step 3: Stateful Workspace Isolation with Git Worktrees

Allowing multiple subagents to write into a shared git directory causes file locking conflicts and accidental overwrites. Instead, each worker operates in an ephemeral Git worktree.

Here is a bash utility script to provision and tear down worker environments safely:

Terminalbash
#!/usr/bin/env bash# provision-worktree.sh: Create an isolated workspace for a worker subagentset -euo pipefailTASK_ID="$1"BRANCH_NAME="worker/${TASK_ID}"WORKTREE_DIR="/tmp/agent-worktrees/${TASK_ID}"echo "Provisioning isolated worktree for ${TASK_ID}..."# Ensure parent directory existsmkdir -p /tmp/agent-worktrees# Create a clean branch from current maingit branch -D "${BRANCH_NAME}" 2>/dev/null || truegit worktree add -b "${BRANCH_NAME}" "${WORKTREE_DIR}" main# Copy localized non-committed configuration if requiredif [ -f .env.test ]; then  cp .env.test "${WORKTREE_DIR}/.env"fiecho "Worktree ready at ${WORKTREE_DIR}"

Once the worker completes its task and passes all stop gates, the supervisor merges the branch back into the working tree and removes the worktree:

Terminalbash
#!/usr/bin/env bash# teardown-worktree.sh: Verify and merge worker changesset -euo pipefailTASK_ID="$1"BRANCH_NAME="worker/${TASK_ID}"WORKTREE_DIR="/tmp/agent-worktrees/${TASK_ID}"# Remove the worktree mountgit worktree remove --force "${WORKTREE_DIR}"# Merge cleanly with squash to keep commit history atomicgit merge --squash "${BRANCH_NAME}"git commit -m "feat(${TASK_ID}): verified milestone completed by subagent"git branch -D "${BRANCH_NAME}"echo "Successfully merged and cleaned up ${TASK_ID}"

Step 4: Deterministic Stop Gates and Verification Hooks

The most dangerous assumption in autonomous development is trusting an agent's claim that its code works. Workers will often report success when compiler errors or unhandled promise rejections exist in modified files.

A stop gate is an automated verification suite that runs strictly outside the agent's LLM context. Before any task result is accepted, a verification hook executes three deterministic checks:

  1. Static Syntax and Type Checking: Compilers (tsc --noEmit, mypy, cargo check) prove type soundness.
  2. Deterministic Test Execution: Unit tests and regression suites prove functional requirements. For a structured approach to writing agent tests, see our guide on Eval-driven unit testing.
  3. Secret and Lint Scanning: Linters ensure no credentials or debug logging statements were introduced.
python
#!/usr/bin/env python3"""stop_gate_validator.py: Deterministic verification runner for subagent tasks."""import sysimport subprocessimport jsonfrom pathlib import Pathdef run_gate(worktree_dir: str, task_contract_path: str) -> bool:    with open(task_contract_path, "r", encoding="utf-8") as f:        contract = json.load(f)    worktree = Path(worktree_dir)    print(f"[stop-gate] Validating {contract['taskId']} in {worktree}...")    # Gate 1: Type Checking    print("[stop-gate] Running type checker...")    type_res = subprocess.run(        ["pnpm", "exec", "tsc", "--noEmit"],        cwd=worktree,        capture_output=True,        text=True    )    if type_res.returncode != 0:        print(f"[stop-gate] Type check failed:\n{type_res.stdout}\n{type_res.stderr}")        return False    # Gate 2: Deterministic Test Command    for criterion in contract.get("acceptanceCriteria", []):        if criterion.startswith("pnpm test"):            test_cmd = criterion.split(" exits")[0].split()            print(f"[stop-gate] Running test gate: {' '.join(test_cmd)}")            test_res = subprocess.run(                test_cmd,                cwd=worktree,                capture_output=True,                text=True            )            if test_res.returncode != 0:                print(f"[stop-gate] Test gate failed:\n{test_res.stdout}\n{test_res.stderr}")                return False    print("[stop-gate] All deterministic gates passed.")    return Trueif __name__ == "__main__":    if len(sys.argv)  ")        sys.exit(1)    passed = run_gate(sys.argv[1], sys.argv[2])    sys.exit(0 if passed else 1)

Step 5: Error Triage and Circuit Breaker Policies

When a stop gate fails, the supervisor must handle the failure systematically rather than entering an infinite retry loop.

The 2-Strike Triage Rule

  1. Strike 1 (Localized Retry): The supervisor passes the compiler or test failure log back to the same worker with a targeted retry prompt: "Your implementation failed the stop gate with exit code 1. Address the following compiler error without altering other files."
  2. Strike 2 (Role Pivot / Reset): If the worker fails a second consecutive time with identical or related errors, do not retry a third time. The worker's branch is discarded (git worktree remove --force), and the supervisor either spawns a specialized diagnostic agent with a clean context or halts execution.

Hard Circuit Breakers

  • Maximum Total Turns: A worker is capped at a strict turn budget (typically 10 to 15 turns). If the limit is reached without passing all gates, the process terminates immediately.
  • Token Ceiling: If cumulative token usage for a subtask exceeds a predetermined budget (e.g., 50,000 tokens), the supervisor trips the circuit breaker and notifies the developer.
  • File Boundary Violations: If a worker modifies files outside the targetFiles array specified in its contract, the changes are rejected automatically.

When coordinating webhooks or third-party event listeners within your architecture, review our runbook on Resilient webhook handlers to ensure external callbacks survive agent restarts.

Production Reference Implementation

Below is a complete orchestrator script showing the full supervisor-worker cycle with worktree management, schema handoffs, and verification gates:

python
#!/usr/bin/env python3"""orchestrator.py: Production supervisor loop for multi-agent vibe coding."""import osimport sysimport jsonimport subprocessimport shutilfrom pathlib import Pathdef dispatch_worker(task_id: str, prompt: str, target_files: list, max_turns: int = 10) -> bool:    worktree_dir = Path(f"/tmp/agent-worktrees/{task_id}")    worktree_dir.parent.mkdir(parents=True, exist_ok=True)    branch_name = f"worker/{task_id}"    try:        # Step 1: Provision Worktree        subprocess.run(["git", "branch", "-D", branch_name], stderr=subprocess.DEVNULL)        subprocess.run(["git", "worktree", "add", "-b", branch_name, str(worktree_dir), "main"], check=True)        # Step 2: Write Contract        contract = {            "taskId": task_id,            "objective": prompt,            "targetFiles": target_files,            "maxTurns": max_turns        }        contract_path = worktree_dir / "task-contract.json"        with open(contract_path, "w", encoding="utf-8") as f:            json.dump(contract, f, indent=2)        # Step 3: Run Worker (CLI invocation with bounded turns)        print(f"[supervisor] Launching worker for {task_id}...")        worker_cmd = [            "openclaw", "run",            "--workspace", str(worktree_dir),            "--max-turns", str(max_turns),            "--prompt", f"Complete task described in task-contract.json. Modify only: {', '.join(target_files)}"        ]        worker_proc = subprocess.run(worker_cmd, capture_output=True, text=True)        # Step 4: Verification Gate        print(f"[supervisor] Running stop gates on {task_id}...")        gate_cmd = ["pnpm", "test"]        gate_proc = subprocess.run(gate_cmd, cwd=worktree_dir, capture_output=True, text=True)        if gate_proc.returncode == 0:            print(f"[supervisor] Gate passed for {task_id}. Merging changes...")            subprocess.run(["git", "worktree", "remove", "--force", str(worktree_dir)], check=True)            subprocess.run(["git", "merge", "--squash", branch_name], check=True)            subprocess.run(["git", "commit", "-m", f"feat({task_id}): automated subagent completion"], check=True)            subprocess.run(["git", "branch", "-D", branch_name], check=True)            return True        else:            print(f"[supervisor] Gate failed for {task_id}. Discarding worktree.")            subprocess.run(["git", "worktree", "remove", "--force", str(worktree_dir)], check=True)            subprocess.run(["git", "branch", "-D", branch_name], check=True)            return False    except Exception as e:        print(f"[supervisor] Unhandled exception in {task_id}: {e}")        if worktree_dir.exists():            subprocess.run(["git", "worktree", "remove", "--force", str(worktree_dir)], stderr=subprocess.DEVNULL)        return Falseif __name__ == "__main__":    success = dispatch_worker(        task_id="phase-01-schema",        prompt="Add refresh_tokens table to schema.prisma and generate Prisma client",        target_files=["prisma/schema.prisma"]    )    sys.exit(0 if success else 1)

Common Pitfalls in Multi-Agent Topologies

When transitioning from single prompts to hierarchical agent teams, watch for these implementation traps:

  • Over-Splitting Tasks: Decomposing a 20-line utility function into three subagents creates excessive orchestration overhead. Reserve multi-agent hierarchies for features spanning multiple files or distinct operational concerns (e.g., migrations vs routes vs tests).
  • Leaking Main Context to Workers: If you pass the entire conversational history of the supervisor to the worker, you negate the benefits of isolation. Workers must start with clean system prompts and only the specific file references they require.
  • Ignoring Concurrency Limits: Spawning five worker subagents in parallel on a single development machine can exhaust memory, trigger model API rate limits, or cause database port collisions. Keep concurrent worker swarms bounded (1 to 2 active workers concurrently).
  • Missing Merge Verification: Even if each individual subagent passes its isolated tests, merging two branches can cause semantic conflicts. Always run the full integration test suite on the main branch after merging.

Explore more practical guides and systems runbooks across our index of ZeroLabs technical resources.

FAQ

When should I use hierarchical subagents instead of a single agent session?

Use hierarchical subagents whenever a task requires touching more than three files, involves schema migrations, or exceeds 15 interaction turns. For quick scripts, single-file edits, or localized bug fixes, a single conversational agent session is faster and carries less overhead.

Why use Git worktrees instead of regular branch switching?

Regular branch switching (git checkout or git switch) modifies your active working tree in place. If an agent is running in the background while you inspect code, files will change under your fingers. Git worktrees create physically separate filesystem directories linked to the same repository, allowing agents to edit, build, and test in total isolation without disturbing your editor.

How does the supervisor prevent worker hallucination loops?

The supervisor enforces a hard ceiling on conversational turns (e.g., 10 turns max) and runs deterministic test gates outside the LLM context. If the worker fails to produce code that compiles and passes tests within the turn budget, the branch is discarded automatically, preventing circular retry patterns.

Can worker subagents communicate directly with each other?

In a clean hierarchical topology, workers should not communicate peer-to-peer. All state transitions, artifacts, and decisions flow through the supervisor. Peer-to-peer agent communication rapidly devolves into uncoordinated debates and makes deterministic debugging nearly impossible.

Share