10. Human gates
Behaviour
When the interpreter reaches a HUMAN task it records the task as IN_PROGRESS and waits for an external event named after the task reference. The run holds no compute while waiting. The wait limit is the task definition's timeout.
Notification
The engine does not know who should decide or how to reach them. The definition places a task before the gate to send the request:
| Need | Task |
|---|---|
| A quick decision in a chat | HTTP to the Teams bridge, which posts an Adaptive Card with the run id and the choices |
| A formal, recorded approval | HTTP to Graph to create a Teams Approvals request |
| Any other channel | HTTP or PUBLISH_EVENT to that channel's endpoint |
Decision
POST /api/tasks/{workflowId}/{taskRef}/COMPLETED
{ "decision": "approve", "reason": "", "decidedBy": "..." }
The body becomes the task's output. Later tasks read it as ${gate.output.decision}. The Teams bridge posts this when a card button is clicked. Any caller with the right role may post it, including an operator in the UI.
Posting FAILED instead of COMPLETED fails the task and applies the task definition's failure handling.
Timeouts
timeoutPolicy | On timeout |
|---|---|
RETRY | The run repeats from the notification task, which sends a reminder. |
TIME_OUT_WF | The run fails and the failure workflow starts. |
ALERT_ONLY | A metric is recorded and the run keeps waiting. |
Write-tier rule
A CALL_TOOL or CALL_AGENT task that names a write-tier or high-risk tool or agent must have a HUMAN task before it on every path. The engine checks this at registration. The exception is a task marked autonomy: true whose workflow owner holds the autonomy right. Page 14 explains trust tiers.