Human in the Loop

The Human in the Loop block pauses a running workflow and waits for a person to make a decision. The reviewer sees the workflow's output so far, then either approves (the workflow resumes) or rejects (the workflow stops). Use it for sign-offs, approvals, and any step where a human must decide before automation continues.

When to use it

• Approvals — a refund, a contract, a publish step that needs sign-off.
• Quality gates — a person checks an AI-generated draft before it goes out.
• Compliance — a required human decision is recorded before the process continues.

What the author configures

Choosing reviewers at runtime

Sometimes the right reviewers are only known once the workflow runs: the experts for this contract's jurisdiction, or the owners of the affected system. Compute the list in an earlier block (a Function block, an Agent, an API call) and hand it to the Human in the Loop block:

1. Declare the pool as usual: Specific Approvers, or a Reviewer Role (admin or member). This is the widest set of people who may ever review this step.
2. Turn on Narrow reviewers at runtime.
3. Set Runtime reviewer selection to the upstream output, for example <pick_reviewers.result>. The value must be a list of user ids, such as ["user_123", "user_456"].

When the block pauses, exactly the selected people are notified, and only they can resolve it.

The selection can only narrow the pool. The block fails with an explanatory error, and nobody is notified, when:

• a selected user is not in the declared pool. A runtime value can never add an approver the template did not declare;
• the selection names the run's own user or the user who started the process instance. A run may not choose itself as its approver;
• a selected user is not a member of the organization;
• the selection is empty or malformed: an unresolved reference, a single id instead of a list, an object, or more than 50 ids. There is no fallback to the whole pool; fix the upstream block instead.

If organization membership cannot be verified at that moment, the pause is retried rather than failed.

Approvals required is capped at the number of people actually selected, so a gate that asks for three sign-offs and receives two reviewers releases once both approve. It never hangs.

Every selection and every refusal is recorded in the organization's audit log (workflow.hitl.reviewers_selected and workflow.hitl.reviewer_selection_refused). Each entry lists the pool, the chosen reviewers and the run identities that were excluded. If the selection cannot be recorded, the block does not pause.

What the reviewer sees

When a reviewer opens a paused workflow, the review panel shows, in order:

Approve vs. reject

• Approve / Resume — the workflow continues from where it paused. Any resume-form values are passed to downstream blocks.
• Reject — the gate refuses. When the refusal settles the gate (see below), the workflow stops and cannot be continued: the status becomes Rejected and the workflow will not resume. You can add an optional reason, which is recorded with the decision.

When does one rejection stop the workflow?

It depends on the approval rule, and the answer is the plain reading of the rule you chose:

A quorum gate also closes when the approvals it needs can no longer arrive. With 2 of 3 required and two reviewers rejecting, one approval is the ceiling — so the gate resolves as rejected at that point rather than waiting for a third answer that cannot change the result. The reviewer who had not answered is told the review closed, exactly as when a quorum is reached early.

Decision options

Approve / Reject answers a yes-or-no question. Many decisions are not one: go, no go or defer; low, medium or high severity. Decision Options lets you declare the choices, and each one says how the gate should count it:

Each option is a row with three columns:

Declare two or more options — a single option is not a choice. There are no weights: every reviewer's vote counts once. Deploying a workflow with an invalid option (a single option, a bad value, an unknown outcome, a duplicate) fails with a message naming the option; a ballot with no approve option is allowed but flagged, because that gate can never be approved. Leave the table empty to keep plain Approve / Reject.

How a decision with options is released

• Approvals required = 1 — the first vote decides. An other vote releases the gate with the verdict undecided, and the workflow continues.
• All approvers must approve — a reject vote settles it as a refusal, and an other vote settles it as undecided: either way, not everyone approved.
• A set number must approve (2 or more) — only approve votes count toward the number. When enough reject and other votes have arrived that the number can no longer be reached, the gate closes: as rejected if anyone chose a reject option (the workflow stops), otherwise as undecided (the workflow continues).

Route on the result with a Condition or Router block: <gate.verdict> is approve, reject or undecided, and <gate.aggregate.byOption.defer> is the number of reviewers who picked Defer — 0 when nobody did.

Who the reviewers are

The Reviewer Role is always an organization role, admin or member. It cannot name a custom process-flow persona. A persona can be assigned by the running workflow itself, so a gate that reviewed as one would let the workflow choose who approves it. A gate whose reviewer role is anything else is refused when the extension is built or imported, when the workflow is deployed, and again when the gate runs.

Outside a process flow, the reviewers are the members of that organization role.

Inside a process flow, reviewers resolve in this order:

1. the people assigned to a persona of the same name (admin or member) on this process-flow instance;
2. otherwise, the members of the organization role itself.

The organization's administrators are not a fallback here. Reviewers are the people allowed to resume the workflow, and that is approval authority, which only a persona holder gives. If nobody resolves, the pause fails with a configuration error instead of waiting on an empty reviewer list. Assign someone to the persona, then re-run the workflow.

When a reviewer is checked

A reviewer role that is not an organization role is refused before the gate opens. The check runs at each of these points:

An organization role is only admin or member. The retired owner role matches nobody.

Opening a review

Reviewers receive a notification when a workflow pauses. Opening the notification takes you straight to the workflow with the review panel open, where you can read the context and decide.

Multiple reviewers

With All must approve or Quorum, the workflow stays paused until enough reviewers have submitted. The AI advisory is generated once per pause and shared across all reviewers — everyone sees the same brief.

Only the gate's reviewers count toward its threshold. Someone with edit access to the workflow who is not a reviewer — typically its owner — can still submit; that answer is kept in responses, but it is not one of the reviewers' answers: it does not count as an approval, does not use up a reviewer's place in a quorum, and does not end an All must approve gate on its own. With a single sign-off (First claim, or Approvals required = 1) any authorized answer settles the gate, as before.

When a quorum closes early

A Quorum gate releases as soon as the required number of reviewers respond — that is the point of it. Reviewers who had not yet responded are notified that the review closed, so nobody discovers it by trying to submit.

If a response arrives after the gate has closed, it is recorded, not discarded. The reviewer is told the review had already closed and that their answer did not change the outcome, and the answer is kept on the paused-execution record alongside the responses that did count. Late responses never alter the released decision or restart the workflow.

What downstream blocks can read

Every released gate carries the same outputs, at every approval rule:

responses and aggregate used to appear only when more than one sign-off was required, so a multi-reviewer design that set Approvals required = 1 kept only the first answer and silently lost the rest. They are now always present.

Reserved resume-form field names

These names belong to the block's own output and are overwritten at runtime, so a resume-form field must not use one:

approved · decision · reason · verdict · responses · aggregate · submission · response · url · option