Coordinated Gated Pipelines

Introduction

Welcome to Lesson 3 of Codex Subagents & Multi-Agent Orchestration! In our previous lessons, we established the fundamentals of subagent isolation with strict contracts and then scaled up to parallel execution for concurrent analysis. These patterns enable fast, reliable, tightly scoped operations across a codebase. This lesson introduces a fundamentally different pattern: Multi-Stage Pipelines with Gated Writes . Here, we chain multiple subagents sequentially, where each stage validates the previous one before proceeding. The final stage performs controlled write operations with strict safety checks. By the end, you will understand how to build pipelines that analyze, plan, and modify code while maintaining rigorous guardrails against unintended changes.

The Case for Sequential Stages

When dealing with code modifications, running a single subagent with write permissions carries risks. Without structure, an agent might change unexpected files, introduce bugs, or stray beyond its intended scope. A multi-stage approach mitigates these risks by separating concerns. Consider a pipeline that writes unit tests. First, we identify which code lacks coverage. Next, we design a test plan based on those findings. Finally, we implement the tests. Each stage produces artifacts that feed into the next, creating a clear audit trail. If any stage fails or produces questionable results, we halt before making changes. This staged approach offers several advantages: we can review intermediate outputs, each stage has a narrow responsibility, and failures are caught early, before write operations occur. The result is a more predictable, safer automation workflow.

Pipeline Architecture Overview

Our pipeline consists of three sequential stages, each with distinct responsibilities. Stage A analyzes existing code to identify areas needing tests. Stage B generates a detailed test plan using Stage A's findings. Stage C implements the tests according to the plan, with strict validation afterward. Between stages, we enforce gating logic : Each stage must report "status": "success" for the pipeline to continue. If Stage A or Stage B fails, we halt immediately rather than proceeding to write operations. After Stage C completes, we run validation checks on the modified files, ensuring changes stay within allowed boundaries. This combination of sequential dependencies and post-write validation creates a robust safety framework.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

The Codex Execution Helpers

To run subagents, we use one helper for analysis stages and another for the write stage:

Python

def codex_exec(prompt: str, approval_mode: str = "never") -> str:
    proc = subprocess.run(
        [
            "codex",
            "-a",
            approval_mode,
            "-s",
            "workspace-write",
            "exec",
            "--json",
            prompt,
        ],
        capture_output=True,
        text=True,
    )
    if proc.returncode != 0:
        raise RuntimeError(
            proc.stderr.strip() or f"codex exec failed: {proc.returncode}"
        )
    return proc.stdout


def codex_exec_full_auto(prompt: str) -> str:
    proc = subprocess.run(
        [
            "codex",
            "exec",
            "--full-auto",
            "--json",
            prompt,
        ],
        capture_output=True,
        text=True,
    )
    if proc.returncode != 0:
        raise RuntimeError(
            proc.stderr.strip() or f"codex exec failed: {proc.returncode}"
        )
    return proc.stdout

def codex_exec(prompt: str, approval_mode: str = "never") -> str:
    proc = subprocess.run(
        [
            "codex",
            "-a",
            approval_mode,
            "-s",
            "workspace-write",
            "exec",
            "--json",
            prompt,
        ],
        capture_output=True,
        text=True,
    )
    if proc.returncode != 0:
        raise RuntimeError(
            proc.stderr.strip() or f"codex exec failed: {proc.returncode}"
        )
    return proc.stdout


def codex_exec_full_auto(prompt: str) -> str:
    proc = subprocess.run(
        [
            "codex",
            "exec",
            "--full-auto",
            "--json",
            prompt,
        ],
        capture_output=True,
        text=True,
    )
    if proc.returncode != 0:
        raise RuntimeError(
            proc.stderr.strip() or f"codex exec failed: {proc.returncode}"
        )
    return proc.stdout

The codex_exec() helper is used for Stage A and Stage B. It keeps the familiar -a never approval behavior while still returning structured output.

For Stage C, we use codex_exec_full_auto(). This allows the implementation stage to actually carry out file edits. The safety model still depends on constrained prompts, validation after execution, and git-based auditing.

As in the previous unit, stdout is a JSONL event stream produced by codex exec --json, not the final contract object directly. So in this lesson we continue using the same extraction helper pattern you already implemented earlier to scan the event lines, find the completed agent_message, and parse its text as the contract.

Also note that -a never is an approval policy, not the same as true read-only execution. In this lesson, Stage A and Stage B are analysis-only by task framing, while Stage C uses --full-auto because it must actually modify files.

Introduction

The Case for Sequential Stages

Pipeline Architecture Overview

Join the 1M+ learners on CodeSignal

Defining Safety Boundaries

The Codex Execution Helpers

Stage A: Identifying Test Targets

Parsing and Persisting Stage A

The JSON Validation Helper

Stage B: Generating the Test Plan

Persisting and Gating Stage B

Stage C: Implementing Tests

Persisting Stage C Output

Detecting Changed Files

Enforcing File Count Limits

Enforcing Directory Restrictions

Running the Validation

Capturing the Git Diff

The Complete Safety Framework

Conclusion and Next Steps