Feature Spotlight: How HITL gates stop bad agent output before it ships

Humans in the loop (HITL) gates are checkpoints in a Modulo pipeline where execution pauses until a person reviews an agent's output. They give you a decision point in front of any high-stakes step: merging a pull request, shipping a config change, or sending a customer-facing message. When a run reaches a HITL checkpoint, it pauses, a reviewer inspects the artifact and its context, then approves it to continue or rejects it to stop.

In short

• What it does: a HITL checkpoint pauses the run and sends a review request to a person. The pipeline continues only after approval.
• When you'd use it: high-stakes write steps - merging code, shipping config, changing billing - where a mistake is expensive.
• When you wouldn't: read-only steps, or high-volume work where deterministic gates already catch the failure modes.
• Rejections create a FeedbackRecord and can trigger a correction run.

The problem it solves

Say you run an agent that drafts and merges pull requests. It is fast. It can open a PR with a working diff, pass the tests, and land the change while you are in another meeting. Most of the time that is fine. Then one day it merges a PR that contains a hardcoded API key, or a change to the billing service nobody intended to ship. The merge is done, the secret is in the repo, and the only question left is how far the damage spreads before someone notices.

An agent making a mistake is normal. The damage happens when nothing stands between the agent's output and the step that makes it permanent. Automated gates (regex, schema, or function checks) catch patterns and structure - a regex can flag a key in a diff - but they cannot judge whether a change should ship at all. That judgment needs a person, at a specific moment: after the work is produced and before the step that makes it irreversible.

How it works

A HITL gate is a checkpoint node in a pipeline. Here is the flow, and why each step exists.

The run pauses and creates a review request

Place a HITL checkpoint node in the pipeline wherever a mistake would be expensive. When the run reaches it, execution stops and the system creates a review request. The pause keeps the work still until a person has seen it - a run cannot slip past the step while nobody is looking.

A reviewer claims the request

Each request carries a claim_token that expires after 15 minutes. A reviewer claims the request, and while it is claimed, the rest of the team sees it as taken. The window auto-expires so a request is never held forever by a reviewer who walked away.

The review shows the artifact and its context

The review screen shows the artifact the agent produced - a diff, text, JSON, or file - alongside the prompt that generated it and the full run context. It also shows previous review history for the pipeline, and an approval checklist you can configure per pipeline. All of it exists so the reviewer decides with the same information the agent had.

Approve or reject

Approving continues the run from the checkpoint. Rejecting stops it. A rejection creates a structured FeedbackRecord, which can trigger a correction run. The feedback becomes the input to a new attempt, with the reviewer's objections in hand.

The pipeline notifies your team

When a run reaches a HITL checkpoint, Modulo sends a webhook to the URLs you configure, so a request is not waiting silently inside the product. The event is hitl.awaiting_review, with the pipeline, run, and agent that raised it:

{
  "event": "hitl.awaiting_review",
  "pipeline_id": "...",
  "run_id": "...",
  "agent_name": "draft-email",
  "url": "https://modulo.run/runs/..."
}

Set the governance tier

Checkpoints appear according to the tier you set. Full autonomy lets agents proceed without human review. Guarded requires review on write operations. Gated requires review on every action. The tiers let one pipeline start strict and loosen as evidence builds - review every action first, then only writes, then run without review once the record shows the gates rarely fire. This is how Modulo treats autonomy as earned, not default - see the principles.

Journey example: before and after

Before

Imagine a support team (run by a manager named Marta) that uses an agent to draft replies to customers and sends them automatically. On a bad week, a draft for an angry customer read as dismissive, nobody saw it before it went out, and the customer canceled. Repairing that meant apologizing to a customer who had already made a decision, and it cost far more than the time the automation saved. The team had to walk the mistake back in public, write a correction, and explain to the account team what had gone wrong.

After

Marta adds a HITL checkpoint before every send. Each draft pauses, the review screen shows the proposed reply with the full customer thread as context, and she or a teammate approves it before it ships. That is a few minutes of review per reply. A bad draft now costs a rejection click instead of a lost customer, and the FeedbackRecord from the rejection feeds the next draft the agent produces.

When to use it vs. when not to

Use HITL gates on the steps where a mistake is expensive or hard to undo: merging code, changing billing or permissions, moving money, sending customer-facing messages, or any write that touches production data. Use them for a new agent too, until its record is long enough to judge.

Do not put a HITL gate on every step. Reviewing a read-only or trivial step adds minutes for nothing. A pipeline gated at every node turns your team into a click-through queue - the reviews stop being careful and the gate loses its value. When an automated gate already covers a failure mode, a regex catching secrets or a schema check catching shape, let the gate handle it and keep the checkpoint for the judgment calls.

Where it fits in a pipeline

HITL gates sit between deterministic gates and the audit trail. Automated gates catch the patterns they were written to catch, checkpoints catch the judgment calls, and audit records both so every decision carries evidence. Together they are how a pipeline earns the right to run with less oversight over time. For the gate types that run before a person ever looks, see Every gate type in Modulo and when to use each.

Go deeper

Read the HITL docs for the full checkpoint flow, or the related docs on pipelines, feedback, and agents. Try the hosted demo at demo.modulo.run, or use the contact page to talk to us about putting a HITL gate in your own pipeline.