Skip to main content
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. The approval lifecycle below covers what happens between a hold and the resumed work.
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. 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: 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: 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. 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.
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. 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: 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. Answering a human task is person-relative, so put your Personal key 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:
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.
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:
Then act with that fingerprint:
The act is refused if the task changed since your read; read it again and retry.