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

# Require human approval before an AI agent acts

> Pause an agent workflow until a person approves. Gate the change on an approval node, handle approve, deny and timeout, and ask questions mid-run.

By the end of this guide you will have a workflow where an agent proposes a change, the run stops until a person approves it, and only an approved change is applied. Denied, timed-out and unattended runs change nothing. You will also add a question with options, for when yes or no is not enough.

An approval is a workflow node, so you can test every branch with scenarios before anyone waits on a real run.

## Before you begin

* [A workflow in `.reliant/workflows/`](https://docs.reliantlabs.io/guides/workflows/first-multi-agent-workflow) that you can validate and run.
* The Reliant CLI, signed in (`reliant auth status`), and a project on a connected machine to run it in.
* [The Inbox](https://docs.reliantlabs.io/automations/overview.md#the-inbox), where approvals and questions wait for you.

**1. Gate the change on an approval node**

The first agent runs in `plan` mode, where it has only read-only tools. The `approve` node holds the run until someone decides. Only the `approved` edge reaches the agent that edits files.

```yaml .reliant/workflows/propose-then-apply.yaml theme={null}
name: propose-then-apply
title: Propose, approve, apply
description: An agent proposes a change without editing anything, a person approves or denies it, and only an approved proposal is applied.

inputs:
  approval_timeout:
    type: string
    default: 4h
    description: How long to wait for a decision, as a Go duration (30m, 4h)

entry: [propose]

nodes:
  - id: propose
    type: workflow
    ref: builtin://agent
    args:
      mode: plan
    thread:
      mode: inherit
      inject:
        role: user
        content: |
          Propose the change for the request above. Do not edit anything.
          End with the exact files and edits you would make.

  - id: approve
    type: approval
    args:
      title: Apply the change the agent proposed?
      timeout: "{{inputs.approval_timeout}}"

  - id: apply
    type: workflow
    ref: builtin://agent
    args:
      mode: auto
    thread:
      mode: inherit
      inject:
        role: user
        content: Approved. Make exactly the change you proposed, nothing else.

  - id: denied
    type: save_message
    args:
      role: assistant
      display_style: warning
      content: "Not applied: the change was denied."

  - id: undecided
    type: save_message
    outcome: failure
    args:
      role: assistant
      display_style: warning
      content: "Not applied: nobody decided ({{nodes.approve.status}})."

edges:
  - from: propose
    default: approve
  - from: approve
    cases:
      - to: apply
        condition: nodes.approve.status == 'approved'
        label: approved
      - to: denied
        condition: nodes.approve.status == 'denied'
        label: denied
    default: undecided
```

The `title` is what the approver is asked to decide. The proposal is the agent's message just above the approval in the run, because both agents share the run's thread (`mode: inherit`).

**2. Route every status**

`nodes.approve.status` takes one of four values, and the `default:` edge catches the last two:

| Status | When |
| - | - |
| `approved` | A person approved. |
| `denied` | A person denied. |
| `timeout` | Nobody decided within `timeout`. With no `timeout`, or one that is not a valid Go duration, the node waits one hour. |
| `unattended` | The run was started by an automation, so nobody can answer. The node resolves at once without a decision ([Unattended by design](https://docs.reliantlabs.io/automations/overview.md#unattended-by-design)). |

Always gate on `== 'approved'`, never on `!= 'denied'`. That way a timeout or an unattended run can never apply the change. `undecided` declares `outcome: failure`, so those runs show as failed in **Workflows → Runs**.

**3. Test approve and deny with scenarios**

A scenario mocks each node's output, including the decision. Put one file per path in `.reliant/workflows/propose-then-apply/scenarios/`:

```yaml .reliant/workflows/propose-then-apply/scenarios/denied_change_is_not_applied.yaml theme={null}
name: denied_change_is_not_applied
description: A person denies the proposal, so nothing is applied
events:
  - node: propose
    output:
      response_text: "Rename getUser to fetchUser in api/users.go and its two callers."
  - node: approve
    output:
      approval_id: appr-1
      status: denied
      action_taken: deny
expect:
  outcome: completed
  completed: [propose, approve, denied]
  not_reached: [apply, undecided]
```

Add the same with `status: approved` (expect `apply`) and `status: timeout` (expect `outcome: failed` and `undecided`). An unattended scenario sets `inputs: {unattended: true}` and gives no `approve` event. Always give the approval a `status`: with none, the scenario resolves it as approved and prints a warning. Then check everything (the `pick-a-fix` scenarios belong to the workflow in step 5):

```bash terminal theme={null}
reliant workflow validate && reliant workflow lint && reliant workflow scenario run
```

```text theme={null}
2 workflow(s): 0 lint error(s), 0 warning(s)
Running 6 scenario(s) across 2 workflow(s)

  ✓ pick-a-fix/person_picks_root_cause (532ms)
  ✓ pick-a-fix/person_stops (31ms)
  ✓ propose-then-apply/approved_change_is_applied (13ms)
  ✓ propose-then-apply/denied_change_is_not_applied (13ms)
  ✓ propose-then-apply/timeout_applies_nothing (12ms)
  ✓ propose-then-apply/unattended_run_applies_nothing (9ms)

✅ All scenarios passed
```

**4. Run it and decide**

`--exit-on-gate` stops following and exits `3` as soon as the run waits on you:

```bash terminal theme={null}
reliant workflow run propose-then-apply --project-path . \
  -m "Fix the typo in NOTES.md (helo -> hello)." -i approval_timeout=45m --exit-on-gate
```

Open the approval from the Inbox or the run, and choose **Approve** or **Deny**. Approvals are decided only in the Reliant app ([who can decide an approval](https://docs.reliantlabs.io/automations/overview.md#who-can-decide-an-approval)). `reliant workflow watch <id>` shows the gate and the decision:

```text theme={null}
07:13:09  ⏸ approval required (id 2fca0b5b-f1ae-4f42-a4b3-83cccbdebcfc, activity 61)
     Apply the change the agent proposed?
07:13:21  ▶ approval approved (id 2fca0b5b-f1ae-4f42-a4b3-83cccbdebcfc) — 12s in gate
07:13:23  ▶ node call_llm started
...
07:13:37  ✓ workflow completed
```

After the approval, the `apply` agent made the edit (`-Greeting: helo world` / `+Greeting: hello world` in `git diff`). A second run with `approval_timeout=3m` that nobody decided ended in `undecided`, and `reliant workflow status` showed `Outcome: ✗ FAILURE`.

**5. Ask a question when yes or no is not enough**

An `ask_question` node offers options and also accepts free text. Its `response` is the text the person typed, or else the label they clicked. The metadata must include `"type":"ask_user"`. Without it, the run waits on a question that has no options to answer.

```yaml .reliant/workflows/pick-a-fix.yaml theme={null}
  - id: choose
    type: ask_question
    args:
      metadata: '{"type":"ask_user","questions":[{"question":"Which fix should the agent make?","options":[{"label":"Root cause","description":"Fix the cause the agent found"},{"label":"Workaround","description":"Make the smallest change that stops the symptom"},{"label":"Stop","description":"Make no change"}]}]}'

edges:
  - from: choose
    cases:
      - to: stopped
        condition: nodes.choose.response == 'Stop' || nodes.choose.response == ''
    default: fix   # an agent prompted with "Make this fix: {{nodes.choose.response}}"
```

An unanswered question resolves with an empty `response` after 24 hours, which is why `''` also stops. Unlike approvals, the CLI can answer questions:

```bash terminal theme={null}
reliant workflow questions <id>
reliant workflow answer <id> --select "Root cause"
```

```text theme={null}
  1. Which fix should the agent make?
       - Root cause — Fix the cause the agent found
       - Workaround — Make the smallest change that stops the symptom
       - Stop — Make no change
Answered question 06c6e86d-2985-4257-b090-5c1cd6069e41
  Which fix should the agent make? -> Root cause
```

**6. Get a Slack or SMS message when a run is waiting**

A run that stops on an approval fires a [workflow event](https://docs.reliantlabs.io/automations/workflow-events.md) with outcome `blocked`. A second workflow can post it to [Slack](https://docs.reliantlabs.io/integrations/slack.md), or text it with [Twilio](https://docs.reliantlabs.io/integrations/twilio.md)'s `twilio/message.send@1`:

```yaml .reliant/workflows/notify-on-approval.yaml theme={null}
name: notify-on-approval
description: Post in Slack when a propose-then-apply run is waiting on an approval
entry: [post]
triggers:
  - name: waiting
    workflow_event:
      workflows: [propose-then-apply]
      outcomes: [blocked]
    filter: "trigger.payload.blocked_on == 'approval'"
nodes:
  - id: post
    type: action
    uses: slack/message.post@1
    with:
      channel: C0123ABCD
      text: "Waiting on your approval: {{ trigger.payload.prompt }} ({{ trigger.payload.chat_title }})"
  - id: posted
    type: save_message
    args: {role: assistant, content: Posted.}
  - id: post_failed
    type: save_message
    outcome: failure
    args: {role: assistant, content: "Could not post to Slack."}
edges:
  - from: post
    cases:
      - to: post_failed
        condition: nodes.post.is_error
    default: posted
```

This validates. Lint still asks for an `on_failure:` handler and a scenario before you [enable it](https://docs.reliantlabs.io/automations/overview.md).

## Keep the decision with a person

Do not add a workflow step that calls `ApprovalService/Approve` or `Deny` to satisfy a human approval gate. If lint reports [`approval-decider`](https://docs.reliantlabs.io/workflows/lint#approval-decider), remove the decision step and have a person decide in the app instead.

Declaring `permissions: [approvals:decide]` or suppressing a lint finding does not authorize automation to decide a human approval. The server refuses a decision made with the credentials a run holds: the CLI login every agent shell inherits, a daemon's credential, a token bound to a machine, and an ordinary `reliant:api` token ([who can decide an approval](https://docs.reliantlabs.io/automations/overview.md#who-can-decide-an-approval)). The only token that can decide is an API token you mint yourself with the `approvals:decide` scope, not bound to a machine ([SDK scopes](https://docs.reliantlabs.io/sdk/overview.md)); whatever holds it can approve, so give it only to software you mean to decide. That reference also explains the shared-key limitation of self-hosted `AUTH_MODE=apikey` deployments; a shared key is not proof of a human decision.

## What this does not do

* Automation runs never wait for approval. They resolve as `unattended`, so a gated change in a triggered workflow is never applied. Notify someone instead, and have them start the run.
* An approval node carries only a `title` and a `timeout`. Put the details the approver needs in the run, before the gate.
* The built-in agent's `manual` mode asks before every tool call. An approval node asks once, at the point you choose.

## Troubleshooting

> [accordion] question has no structured ask\_user prompts
>
> Add `"type":"ask_user"` to the `ask_question` metadata. Validation does not catch this yet.

> [accordion] CEL compilation error: undefined field 'denial\_reason'
>
> The approval's declared outputs are `approval_id`, `status`, `action_taken` and `data` ([nodes reference](https://docs.reliantlabs.io/reference/nodes.md#approval)). Route on `status`.

> [accordion] permission\_denied: this credential lacks the approvals:decide scope
>
> Do not try another workflow-held token or add a scope to bypass the gate. Open the approval in the Reliant app and have a signed-in person choose **Approve** or **Deny** ([who can decide an approval](https://docs.reliantlabs.io/automations/overview.md#who-can-decide-an-approval)).

## Next steps

> [card] [Write your first multi-agent workflow](https://docs.reliantlabs.io/guides/workflows/first-multi-agent-workflow.md)
>
> Planner, implementer and reviewer agents in one workflow.

> [card] [Testing workflows](https://docs.reliantlabs.io/workflows/testing.md)
>
> Scenarios, mocked activities and expectations.

> [card] [Workflow control](https://docs.reliantlabs.io/workflows/workflow-control.md)
>
> Pause, resume and steer a run.

> [card] [Node reference](https://docs.reliantlabs.io/reference/nodes.md)
>
> Every field of `approval` and `ask_question`.


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