> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Approvals and Human-in-the-Loop

> Operating the approval surface — how approvals are triggered, the state machine, the approval lifecycle from hold to resumed work, resolution channels, and the policy rules behind them.

This page is for operators who own the approval surface — duty managers, compliance leads, ops engineers tuning policy. Approvals bridge the gap between full autonomy and full manual control. They let agents execute freely for routine work while ensuring high-stakes, high-risk, or policy-sensitive actions get human review before proceeding.

For where in the pipeline approvals fire, read the [Governance pipeline](https://docs.gloo.com/forge/architecture/flows/governance-pipeline.md). The [approval lifecycle](#approval-lifecycle) below covers what happens between a hold and the resumed work.

> [!NOTE]
>
> **When to reach for something else.** If you need to **block** an action outright (not pause for review), use a `block` policy instead. If you need a hard cap on spend, configure budget envelopes — they `block` automatically when exhausted, no approval involved. A financial or irreversible write has no automatic second-agent gate; configure an explicit approval policy or a workflow review step where human review is required.

***

## Human tasks

A **human task** is any point where Forge waits for a person. An approval is one kind of human task; it is not a separate queue. Every human task has a kind, the people who may answer it, a form for the answer and a due date, and every kind is answered the same way.

| Kind | When Forge creates it |
| - | - |
| `trust_fabric_hold` | A governance decision holds an action for approval. This is an approval. |
| `workflow_human_node` | A run reaches an Agent node whose worker is a person. |
| `agent_question` | An agent asks a person a question during its work. |
| `architect_plan` | The Workflow Architect asks a person to confirm a plan. |
| `synthesis_confirmation` | Synthesis asks a person to confirm what it is about to build. |
| `synthesis_review` | A synthesized skill, agent or procedure waits for review. |
| `procedure_review` | A procedure waits for review before it can be used. |
| `judge_admission` | A synthesized skill, agent or procedure waits for a person to admit or reject it on its judge panel's verdict. |
| `curator_recommendation` | The Curator recommends a change for a person to accept or reject. |
| `agent_setup` | An agent's setup needs a fix from someone who can make it. |
| `foreman_approval` | A Foreman plan or request waits for a person's approval. |
| `external_app_request` | An External App or platform API key asks a named person. |

People find their open human tasks in **My Work** in Forge Console, and some kinds are also delivered to Slack or email. From an MCP host, `forge_list_my_work` lists them and `forge_handle_human_task` answers one. When several people may answer a task, the first answer closes it; a later answer is refused because the task is already closed.

Human-in-the-loop (HITL) is the general practice of putting a person in the path of an automated decision. In Forge it always takes the form of a human task.

***

## How approvals are triggered

Approvals enter the system through two paths:

| Path | Trigger | Disposition |
| - | - | - |
| **Policy-triggered** | Dispatch policy with `action: require_approval` matches, or approval-policy trigger condition matches | `hold` |
| **Workflow-triggered** | Step configured with the `hitl` flag — requires human approval regardless of policy evaluation | `hold` |

When an approval is created, the workflow run's `pendingApprovals` counter increments and its `operatorStatus` is recalculated. The waiting step does not continue until its approvals are resolved. The run's status stays `running` throughout; `pendingApprovals` and `operatorStatus` show that it is waiting on people.

***

## The state machine

Every approval follows a four-state machine:

| State | Meaning | Transitions out |
| - | - | - |
| **Pending** | Awaiting human decision. Execution is paused. | Approved · Rejected · Canceled |
| **Approved** | Execution resumes. Original step proceeds. | Terminal |
| **Rejected** | Step fails. Workflow handles per its error policy. | Terminal |
| **Canceled** | Nobody decided by the final due date, the run ended, or the requester withdrew it. Never approved. The step fails with `approval_canceled`. | Terminal |

Every approval has a due date. The people it names have 72 hours (or the SLA window when one is set), with one reminder after 24 hours. Then it escalates to the policy's releasers for another 72 hours. If nobody decides by then, it is canceled — never approved, and never recorded as a person's rejection. A queue that grows unbounded becomes a queue nobody looks at; the due date keeps every item actionable. A canceled request is re-requested if the work is still wanted.

***

## Approval lifecycle

An approval is a durable release decision for **one** protected action. When the Trust Fabric holds an action, Forge creates the approval and a human task, sends the task to its configured surfaces, and parks the workflow or command that asked. Completing the task resolves both in one step before the caller resumes.

### Approved is not done

Approved is terminal for that approval. Resuming the caller does not reset it to pending, and a later hold creates its own approval.

Approved means the specific hold has a valid release. It does not mean the protected operation has already happened: the owner still resumes, uses the release once, and records the attempt's outcome. A wake-up without a matching approved release cannot run the action.

### One task, every surface

Workflow approvals, policy holds, questions and confirmations share one human-task record. It owns the prompt, the people who may answer, where the prompt was presented, due dates, completion, recall and outputs. An approval adds its run and step, its source, its release rule and the evidence for its resolution.

Notifications are delivery surfaces, not decision authorities. The Console, Slack, email and the HTTP routes all complete the task the same way. If delivery to one surface fails, the task stays pending and reachable on the others.

### Who can decide

* **In the Console**, a person a workflow step asks answers it from **My Work** without `approvals:approve`: being asked is the authority. Approving a Trust Fabric hold is stricter: a hold with a release rule is decided by that rule, and any other hold needs `approvals:approve` at the hold's org unit or above. Rejecting a hold needs neither. Anyone else needs `approvals:approve` to see or take over a hold or a workflow step that does not ask them. Forge still enforces current scope, the action's own permissions, and any independent-approver exclusion.
* **With a Personal key**, a person can decide through the human-task HTTP routes when the key has an owner, the key's scopes include `approvals:approve`, the task asks the owner (or the owner claimed or requested it), and the task is in scope. The owner needs no `approvals:approve` grant of their own to answer a workflow step that asks them or to reject a hold; approving a hold follows the Console rule above, judged on the owner's grants narrowed to the key's scopes. Key scopes only narrow the owner's authority; they never create it.
* **Platform API keys and External App credentials** cannot decide. These routes require a person.

### What happens when someone decides

1. Forge loads the pending task and its approval.
2. It resolves the person, how they authenticated, their current permissions, and whether they may release this hold.
3. It refuses an inaccessible or ineligible request without revealing out-of-scope work.
4. It records the task outcome, the approval status, who decided, and the audit evidence together.
5. It withdraws the prompt from every other surface and wakes the waiting work.
6. The specific command or workflow attempt resumes; a rejection or cancellation follows its terminal path.

Approving and rejecting use the same path. Approval has the stricter consequence, so it runs the full release check; an independent-approver rule refuses the person whose action was held even when they otherwise could approve. Completion is idempotent, and a stale button cannot reopen a task. A decision made with a Personal key records both the person and the key.

Due dates send reminders and escalate to other candidates; escalation never approves anything. A final due date with no decision cancels the hold. While it waits, a durable workflow uses no model tokens.

***

## Response deadlines and reminders

A human step in a workflow is authored on the Agent node's **Worker** panel, alongside the person or role it routes to. Three fields govern what happens when nobody answers.

| Field | What it does |
| - | - |
| **Response deadline** | How long the step waits for an answer. Entered as a number plus a unit (hours or days). Leave it empty for no deadline. |
| **On deadline** | The policy that runs when the deadline elapses. Only shown once a deadline is set. |
| **Escalation channel** | Slack channel the reminder is posted to. Defaults to the channel the prompt was sent to. |

The **On deadline** policies:

* **Remind & keep waiting** (`escalate`) — the default. Posts a reminder and leaves the step open. The step stays actionable.
* **Skip this step** (`skip`) — the step is marked skipped and the run advances past it.
* **Fail the run** (`fail`) — the step fails and the workflow handles it per its error policy.

> [!NOTE]
>
> **No deadline means waiting, not dying.** A step with no deadline waits **indefinitely** — but never silently. Forge sends a reminder every 6 hours, up to 14 times (roughly three and a half days), then keeps waiting quietly. `skip` and `fail` are explicit operator choices; a human step is never killed by silence alone. If a step must not stall, say so with a deadline and a policy — do not rely on a timeout you did not configure.

Because "waits forever" is a legitimate authoring choice, the graph validator does not block on it. It raises a **warning** — `HUMAN_NODE_NO_DEADLINE` — on any human step that surfaces a prompt without a deadline, so the choice is visible before publish rather than discovered during an incident. Set a deadline and a policy to clear it, or publish through it if indefinite waiting is what you meant.

In the run inspector, an open request shows **Waiting since** with the time it was raised, and appends **· reminder sent** once the reminder loop has nudged it. Together with the `attempt N` tag, that tells you at a glance whether you are looking at a fresh request, a long-ignored one, or a re-request from a rerun.

***

## Resolution channels

Pending approvals can be resolved through any registered surface. The decision is the same — what differs is where the operator sees the request and clicks Approve.

| Channel | Use case |
| - | - |
| Forge Console (**Production → Approvals**, `/production/approvals`, or **My Work**) | The canonical operator surface. Full reasoning, audit trail, all metadata. |
| Slack | Inline approval cards posted to a designated channel. Resolves through interactive buttons. |
| Email | For approvals that need to reach people who do not live in Forge Console. Reply with a verification token. |
| Platform API and MCP | A person deciding with their own Personal key: [`POST /api/v3/governance-human-tasks/{humanTaskId}/complete`](https://docs.gloo.com/forge/reference/http-api/governance/completeHumanTask) or `forge_complete_human_task`, judged on the owner's permissions narrowed to the key's scopes. A platform API key or an External App cannot decide. |

Whichever channel resolves the approval, the resulting record lands in `auditEvents` with the resolver's identity, timestamp, and reason. The resolution is a single source of truth — multiple channels resolving the same approval is not a possible race; the first resolution wins, and subsequent attempts return a structured "already resolved" response.

***

## Approval policies — declarative rules

Behind every policy-triggered approval is a declarative policy, managed under **Trust Fabric → Policies**. Policies are how operators define governance rules without writing code. Every policy has six core properties:

| Property | Description | Example |
| - | - | - |
| **name** | Human-readable policy name | `Refunds over $1,000 require approval` |
| **category** | The domain this policy governs | `trust_boundary` |
| **scope** | Where the policy applies | `gateway` · `agent` · `environment` · `workflow_version` · `global` |
| **condition** | Expression evaluated against dispatch context | `action.amount > 1000 && action.type == "refund"` |
| **action** | What happens when the condition matches | `block` · `require_approval` · `warn` · `log` |
| **enforcement** | How strictly the action is applied | `hard` · `soft` · `audit` |

The four actions cover the full spectrum from advisory to blocking:

* **`block`** — hard stop. Step fails with `policy_blocked`. Disposition: `block`.
* **`require_approval`** — hold for HITL. Execution pauses. Disposition: `hold`.
* **`warn`** — record a warning in the audit trail; let dispatch proceed.
* **`log`** — silent observation. No operator-visible signal. Disposition: `pass` with a logged audit event.

The three enforcement levels gate how the action is applied:

* **`hard`** — strictly enforced. The action runs as written.
* **`soft`** — advisory. Reported only; the action is not enforced. Useful for rolling out new policies in shadow mode.
* **`audit`** — observation only. The match is logged but neither blocks nor approves.

**Operating discipline**: ship new policies in `audit` mode for at least a week. Read the audit log. Confirm the policy matches the cases you intended and does not match cases you did not. **Then** flip to `soft` for another week — operators see warnings but dispatches still proceed. Then flip to `hard`. Skipping audit mode is how policies block legitimate work the first day they ship.

***

## Financial actions and review

The retired two-agent rule does not add a hold at a financial threshold, and an agent cannot co-sign a governance approval. A financial or destructive write is evaluated as a write under the agent's autonomy rung. An explicit approval policy can require a qualified person to release a hold, and a published workflow can include its own human review step. The person approving a governance hold must be active and hold `approvals:approve` plus the held action's permissions at its scope; an upstream person who qualifies may release it, with `self_released` audit attribution.

A governance hold resolves on its first decision: an approval policy holds for one decision, and there is no quorum. Approval policies no longer store `approverRole` or `requiredApprovals`; the platform accepts both on a create or update and ignores them. Use a workflow review process for a business process that requires multiple human decisions.

***

## Operator runbook

When you start operating the approval surface:

1. **Triage the queue daily.** Pending approvals are paused work. Check the queue every morning. If you see items piling up, the policy may be too aggressive or the wrong people are receiving the notifications.
2. **Watch the cancellation rate.** Approvals canceled at their due date (`cancelReason: "due_date"`) mean either nobody owned the queue or the policy fires more than expected. Both are fixable; the `approval_canceled` audit events make the pattern visible.
3. **Document approval reasoning.** When you approve or reject, the audit trail captures your reason. **Write it.** "approved" is a worthless audit record; "approved — verified customer ID and refund matches purchase history" is a real one. Compliance asks for these.
4. **Audit your policies quarterly.** Policies accrete. List them (`GET /api/v3/governance-approval-policies`) and read each one. Anything that has not fired in 90 days is either a placeholder, a stale policy from a long-resolved incident, or a real policy guarding against rare events. Decide which.
5. **Give the steps that matter a deadline.** Triage catches what you look at; a deadline catches what you don't. Any human step on a run with a real due date should carry a **Response deadline** and an explicit **On deadline** policy. Treat the `HUMAN_NODE_NO_DEADLINE` warning as a question — "is indefinite waiting genuinely fine here?" — and answer it deliberately.
6. **Re-approve after a rerun.** Restarting a run from a step re-dispatches any Agent node assigned to a person at or downstream of that step, which issues a **new** request. The earlier decision stays in the record but does not carry forward — the rerun is waiting on a fresh answer. The run inspector shows the live request and tags it `attempt 2`, `attempt 3`, and so on, so you can tell a re-requested approval from the original. If a rerun looks stalled on a step you remember approving, this is why: approve the current attempt.

***

## Do it over the API

These calls use the `FORGE_BASE` and `ACCESS_TOKEN` set up in the Raw HTTP tab of the [quickstart](https://docs.gloo.com/forge/quickstart.md). Answering a human task is person-relative, so put your [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md) in `ACCESS_TOKEN` in place of the External App token: it acts as you, and a platform API key or an External App is refused with `403` and `error.personRequired: true`.

List the open human tasks that ask you, with the actions each one's form accepts:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/me/work?limit=25" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data.items[] | {kind, title, humanTaskId, actions: [.form.actions[]? | {id, label, effect}]}'
```

This needs `approvals:read`. A page can be short while `meta.hasMore` is true; follow `meta.nextCursor` to read on.

Answer one task: set `HUMAN_TASK_ID` from the list and `ACTION_ID` to one of that task's action `id` values.

```bash theme={null}
curl -sS -X POST "$FORGE_BASE/api/v3/governance-human-tasks/$HUMAN_TASK_ID/complete" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: complete-$HUMAN_TASK_ID-v1" \
  -d "{\"action\": \"$ACTION_ID\", \"reason\": \"Verified the customer ID and the refund against the purchase history\"}" \
  | jq '.data'
```

This needs a key whose scopes include `approvals:approve`. For a workflow step that asks you, or to reject a hold, your place on the task is the authority and you need no `approvals:approve` grant. Approving a hold needs its release rule, or `approvals:approve` at the hold's org unit or above, judged on your grants narrowed to the key's scopes. A hold's release rule and its approval policy's approver limits apply as in Console. `data.outcome` is `completed`, `declined` or `canceled`. Without an `Idempotency-Key` a second decision is refused with `409`, because the first decision wins. A hold that sends outside Forge is approved only in Console: its approve answers `403` with the task's Console link, and its reject is taken.

Over MCP, `forge_handle_human_task` reads and answers a task; it is in the default `start` job. Read the task first to get its `formFingerprint`:

```json theme={null}
{ "humanTaskId": "<human task id>" }
```

Then act with that fingerprint:

```json theme={null}
{
  "humanTaskId": "<human task id>",
  "verb": "complete",
  "action": "<form action id>",
  "reason": "Verified the customer ID and the refund against the purchase history",
  "formFingerprint": "<formFingerprint from the read>",
  "idempotencyKey": "complete-<human task id>-v1"
}
```

The act is refused if the task changed since your read; read it again and retry.

***

## Related

* [Trust Fabric in production](https://docs.gloo.com/forge/run/trust-fabric.md)
* [Governance pipeline](https://docs.gloo.com/forge/architecture/flows/governance-pipeline.md)
* [Workflow execution](https://docs.gloo.com/forge/architecture/flows/workflow-execution.md)
* [Audit](https://docs.gloo.com/forge/run/audit.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.