Human Gate

The human-gate pattern inserts human approval checkpoints into your agent workflow. When an agent's work reaches a gate, execution pauses until a human reviews and approves. If the human rejects, the gate's on-fail action determines what happens next.

When to Use Human Gate

Publishing workflows — human approves content before it goes live
Code deployment — human reviews changes before they are merged or deployed
Financial decisions — human signs off on transactions above a threshold
Compliance — regulatory requirements demand human oversight at certain steps
Any workflow where automated output needs human judgment before proceeding

Human gate is the right choice when certain decisions are too important to fully automate. If your workflow is fully automated, you do not need this pattern.

How It Works

The gates block defines checkpoints that sit between two agents in the flow. Each gate specifies which agent it comes after, which agent it comes before, a script to run for the approval process, and what happens if approval fails.

topology publish-workflow : [pipeline, human-gate] {
  meta {
    version: "1.0.0"
    description: "Content publishing with human approval"
  }

  orchestrator {
    model: opus
    handles: [intake, published]
  }

  agent writer {
    model: sonnet
    phase: 1
    tools: [Read, Write]
    writes: ["workspace/draft.md"]
  }

  agent reviewer {
    model: opus
    phase: 2
    tools: [Read, Grep]
    reads: ["workspace/draft.md"]
    outputs: { verdict: approve | revise }
  }

  agent publisher {
    model: haiku
    phase: 3
    tools: [Read, Write, Bash]
    reads: ["workspace/draft.md"]
  }

  flow {
    intake -> writer
    writer -> reviewer
    reviewer -> writer    [when reviewer.verdict == revise, max 2]
    reviewer -> publisher [when reviewer.verdict == approve]
    publisher -> published
  }

  gates {
    gate human-approval {
      after: reviewer
      before: publisher
      run: "scripts/human-approve.sh"
      on-fail: halt
    }
  }
}

Key Concepts

Gate Declaration

Each gate is declared inside the gates block with a unique name:

gates {
  gate human-approval {
    after: reviewer
    before: publisher
    run: "scripts/human-approve.sh"
    on-fail: halt
  }
}

Gate Properties

Property	Description
`after`	The agent whose output triggers the gate
`before`	The agent that runs only after the gate passes
`run`	Script or command executed for the approval process
`on-fail`	Action when approval is denied: `halt`, `retry`, or `route`

On-Fail Actions

The on-fail property controls what happens when the gate rejects:

Action	Behavior
`halt`	Stop the entire topology
`retry`	Re-run the `after` agent and present for approval again
`route`	Send to an alternative flow path (specified with `route-to`)

Example with route:

gates {
  gate compliance-check {
    after: analyzer
    before: deployer
    run: "scripts/compliance-review.sh"
    on-fail: route
    route-to: manual-fix
  }
}

Approval Scripts

The run script receives the gate context (upstream agent output, file paths) as environment variables. It should exit with code 0 for approval and non-zero for rejection:

#!/bin/bash
# scripts/human-approve.sh
echo "Review the draft at: $GATE_FILE_PATH"
echo "Approve? (y/n)"
read answer
[ "$answer" = "y" ] && exit 0 || exit 1

Flow Diagram

intake -> writer -> reviewer --[gate: human-approval]--> publisher -> published
                       |                                     ^
                       +-------------------------------------+
                             (revise, max 2)

The gate sits on the edge between reviewer and publisher. Execution pauses at this point until the human approves.

Multiple Gates

You can define multiple gates in a single topology:

gates {
  gate editorial-review {
    after: writer
    before: reviewer
    run: "scripts/editorial-check.sh"
    on-fail: retry
  }

  gate final-approval {
    after: reviewer
    before: publisher
    run: "scripts/final-approve.sh"
    on-fail: halt
  }
}

Combining with Other Patterns

Human gate works well with:

pipeline — add approval checkpoints between pipeline phases
fan-out — gate after parallel results are merged
supervisor — require approval before the orchestrator routes to high-risk workers

Human Gate

On this page