That moment is where we spend our days, and it turns out to be much stranger and more interesting than "add an approval step." So we're going to write about it here.

What this blog is about#

Concretely, the problems we keep running into and the ones our design partners bring us:

• Approval design. What a reviewer needs to see before they can honestly say yes. Why a bare approve/reject button is a liability rather than a control.
• Policy. How to express "a human decides this" as a rule rather than a hard-coded if, and how to keep an AI from quietly deciding it doesn't need one.
• Routing, quorum, and escalation. Who gets asked, how many of them, and what happens when nobody answers. Silence is a design problem, not an error case.
• Provenance. What has to be recorded so that, a year later, someone can reconstruct not just who approved something but what they were looking at when they did.
• Workflow engines. What Inngest, Temporal, Trigger.dev, and Hatchet give you, where their primitives stop, and why that boundary sits exactly where it does.

Some of it will be opinionated. Some will be things we got wrong and had to change. Where we haven't shipped something yet, we'll say so — the same way we do on the rest of this site.

Why we think it's worth your time#

Human-in-the-loop is treated as a checkbox on a compliance form, and it deserves better. The difference between an approval system that works and one that decays into a rubber stamp within a quarter is a hundred small design decisions, almost none of which are written down anywhere.

We are making those decisions in public, on a product that lets agents move real money. We'd rather share what we learn than pretend we arrived at it obviously.

If you're building something similar, disagree with us loudly. That's the point.

Ratifia pauses an AI workflow for a human decision, gives the reviewer the full context, and resumes with the verdict. It runs on top of the workflow engine you already use and never executes your code. Request early access.

The difference between those two outcomes is entirely determined by what you put in front of the reviewer. So it is worth being precise about it.

The test#

Before adding a field to an approval payload, ask: would a reviewer decide differently if this were absent?

If no, it is decoration. Decoration is not free — it costs attention, and attention is the scarce resource in a queue of forty pending approvals. Every field that does not change the decision makes the fields that do harder to find.

That test kills more than you would expect. Workflow run IDs, internal trace links, the model's token count, the queue name — all real, all logged elsewhere, none of them changing whether a human approves a $12,400 refund.

The five that survive#

1. The action, stated as an action#

Not "review request #48213." The reviewer needs the verb and the object: issue a $12,400 refund to account 8841. Write it the way a person would say it out loud. If the action cannot be stated in one sentence, the approval is scoped wrong and you should be gating something smaller.

2. The exact operation to be performed#

The literal tool call, with its literal arguments:

{
  "tool": "issueRefund",
  "args": { "account": "8841", "amount": 12400, "currency": "USD" }
}

This is the thing that will actually execute. Not a summary of it, not a rendering of it — it. A reviewer who approves a prose description and gets a different call has approved nothing, and your audit trail records a consent that was never given.

3. The state delta#

What is true before, what is true after:

- account_balance: $41,900
+ account_balance: $29,500

Reviewers reason about consequences, not operations. issueRefund(12400) is an operation. "The account drops below the $30,000 covenant floor" is a consequence, and it is the one that changes the answer.

4. The model's reasoning, marked as the model's#

Include it. Label it. Never let it render like a system-generated fact.

An AI recommendation is evidence, and the reviewer should weigh it as such. The failure mode here is automation bias: a confident "Approve — policy match" in neutral typography reads as a verdict rather than a suggestion, and reviewers rubber-stamp it. Attribute it to the model, name the model, and put it below the delta — never above.

5. Why this stopped#

Which policy fired, and on what clause. payouts-over-5k · amount exceeds $5,000 threshold.

Reviewers who understand why a decision reached them make better decisions, and they escalate the right ones. Reviewers who see approvals arrive for no legible reason learn to treat the queue as noise. That learning is permanent, and it is how an approval system decays into a rubber stamp within a quarter.

The three that must never appear#

Credentials, tokens, or keys. Approval payloads get forwarded to Slack, rendered in email, and retained for years under compliance holds. They are the least appropriate place in your system for a secret.

Anything you cannot show in an audit. If a field would be redacted from the record a regulator reads, it should not be in the record the reviewer reads either. The whole value of the payload is that the reviewer's view and the auditor's view are the same view. Divergence there means nobody can reconstruct the decision.

Unbounded data. A 40,000-row export is not context. It is an invitation to approve without looking, and it will be the exhibit in the postmortem. Summarize, link out, and let the reviewer pull the detail if they want it.

Why this is not a form#

The instinct is to define a schema — amount, account, reason — and render it as a table. It works for one workflow and collapses at the second, because a refund approval and a content-moderation approval and a model-deployment approval share almost no fields.

What they share is a shape: a headline action, an operation, a consequence, evidence, and a reason for stopping. So the payload should be a list of typed blocks — text, diff, code, table, key-value — that a workflow composes as it needs. The system renders blocks; the workflow decides which blocks the decision requires.

That is why Ratifia takes a free-form context payload rather than a fixed approval schema. The engines you already run can tell a reviewer that something is waiting. What they cannot tell them is what it means, because they were never given a place to put it.

The pause is real. It is also about five percent of the work. Everything that makes an approval trustworthy lives in the gap between the pause and the resume, and none of it is in the engine.

What does waitForEvent actually give you?#

A correlation ID and a timeout. Your workflow stops, and it will start again when something posts a matching event, or when the clock runs out.

That is genuinely hard infrastructure and the engines do it well. But notice what it does not say anything about:

• Who is allowed to send that event.
• What the person saw before they sent it.
• Whether one signature was enough.
• What happens when nobody sends it at all.
• Whether any of it can be reconstructed a year later, under audit.

The engine's contract ends at "a matching event resumed the run." Everything above is now yours.

The four things you end up building#

An interface that shows the decision#

The moment an agent is the thing proposing the action, a yes/no button is malpractice. The reviewer needs the model's actual output, the tool call it wants to make, and the records that change if it runs. Concretely: the issueRefund({ amount: 12400 }) call, the balance before and after, and the model's stated reasoning — on one screen, at decision time.

None of that is in the event payload. You will build the queue, the detail view, the rendering of arbitrary context, and the mobile layout, because approvals happen on phones.

Authorization on the resume path#

waitForEvent resumes on any matching event. Which means your approval endpoint is a public "make this workflow continue" button unless you put real authorization in front of it, and bind the approver's identity to the specific decision rather than to the event name.

Email action-links make this sharper. A signed link that approves a $12,400 payout with one click is a bearer token for money. It needs to be single-use, scoped to one decision, expiring, and unforgeable — and you have to log which one was redeemed.

Quorum#

"Two people from Finance must both approve" cannot be expressed as one event. You need to track partial state — who has signed off so far — reject duplicate votes from the same person, handle one approve and one reject, and only then emit the resume.

That state lives somewhere. The engine will not hold it for you, because from its perspective there is exactly one event and it has not arrived yet.

Escalation#

This is the one that bites in production, because it is invisible until it happens: a reviewer is on vacation, and a claim sits in a queue for nine days.

A timeout is not an escalation. A timeout fails the workflow. An escalation reroutes — after four hours with no quorum, widen to the whole Finance role; after twelve, page the on-call manager; after twenty-four, auto-reject and notify the customer. Each of those is a policy decision with a different blast radius, and every one of them is a new timer, a new notification path, and a new audit entry.

Note that this also means "the timeout" has two entirely different meanings that teams routinely conflate. There is auto-escalate in 3h 40m — nobody has acted, so widen the approver pool — and there is expires in 24h — nobody ever acted, so take the default action. Collapsing these into one number is how you end up either paging a VP over a $40 refund or silently approving a $40,000 one.

So when is waitForEvent the right answer?#

When the human is a teammate, the stakes are low, and the audit trail is a Slack thread. Internal tools, staging gates, "ping me before you deploy." Reach for the engine primitive, wire it to a Slack button, move on. Adding a system here is overhead with no return.

It stops being the right answer at the point where the decision is a decision of record — where someone will later ask who approved this, what they saw when they approved it, and what would have happened if they had not. That question has a compliance answer, not an engineering one, and a correlation ID does not supply it.

The actual dividing line#

waitForEvent treats the human as a signal source. Something out there will eventually emit an event; the workflow does not care what, or who, or why.

Human-in-the-loop treats the human as a decision-maker. The system owes them context before the decision, owes them authority scoped to their role, and owes the organization a record afterward.

Those are different problems. One is solved by durable execution. The other is solved by policy, presentation, and provenance — three things that have nothing to do with how your workflow engine persists state, which is exactly why your workflow engine does not ship them.

Ratifia is the second layer. It runs on top of the engine you already have, it never executes your code, and it turns the pause you already know how to write into a decision you can defend.