Hane Platform

Approvals and tasks

Assigning and handling tasks for people's decisions and work, approving operations proposed by agents, and the DeciderPolicy that sets who may decide.

This page explains the Approvals service (/v1/approvals), which handles human decisions. It covers where tasks come from, who they are assigned to, how they are decided, and how operations with external effects proposed by agents are approved.

What a task is

A task is one decision or piece of work for a person. It is assigned to a group or to a specific assignee and closed by choosing one of its predefined outcomes (outcomes). Tasks are created in the following places.

Created by	What the task is
A workflow’s `task` or `escalate` step	A business decision or check. The case proceeds according to the outcome
An operation with an external effect proposed by an agent	An approval task. The outcome is approve (`approve`) or reject (`reject`)
An operation performed by a person	An execution task asking the assignee to carry out an approved operation (mail, phone, counter, and so on) and record the result
A watching agent	A task assigned to an assignment candidate for an item that matched a triage rule

A task’s status is open, completed, or cancelled. Cancelling a case also cancels the case’s open tasks.

Assignment

Who a task is assigned to is set by an assignment rule (AssignmentRule) manifest.

apiVersion: approvals/v1alpha1
kind: AssignmentRule
metadata:
  name: vehicle-manager
spec:
  candidates:                       # follow relations from the record to find candidate people
    path:
      - { relation: managed_by, direction: out }
    email: email                    # field holding the email address on the record reached
    role: operator                  # only members with this role are candidates
  stages:
    - group: fleet-desk             # assign to this group if no candidate remains

Option	Meaning
`stages`	The order of groups to assign to. When a task passes its deadline, it moves to the next stage’s group
`routes`	Conditions on the subject record’s values (CEL) that choose the first stage’s group. If none match, the first stage of `stages` is used
`candidates`	Follow relations from the record to find candidate people. They are filtered by membership, role, and delegation on that day; if none remain, the task goes to the stage’s group

A task with a set assignee (assignee) can be decided only by that person, not by other members of the group. If a delegate is set for a period of absence, assignment candidates go to the delegate member (see Organizations, projects, and environments).

Handling tasks

Operation	API
List	`GET /v1/approvals/tasks`. Filter by `status` and `case_id`; `mine=true` returns only tasks for you or your groups
Get	`GET /v1/approvals/tasks/{id}`
Claim	`POST /v1/approvals/tasks/{id}/claim`
Unclaim	`POST /v1/approvals/tasks/{id}/release`
Close with an outcome	`POST /v1/approvals/tasks/{id}/complete`

Claiming, unclaiming, and closing send the task’s version in If-Match. If two people act at the same time, only one succeeds.

POST /v1/approvals/tasks/tsk_01J…/complete
Authorization: Bearer <access token>
If-Match: "2"
Idempotency-Key: 1b7e…
Content-Type: application/json

{ "outcome": "renew", "comment": "Compared the quotes and chose to renew" }

Only people can decide tasks. It requires the approvals:tasks.decide scope, and even when called from a business app, the decision is checked and recorded against the user who acted, not the app’s service account. For this reason, business apps call these APIs with the user’s access token (see Authentication).

Approving operations with external effects

When an agent proposes an operation with an external effect, such as sending an email, placing a call, or updating an external system, Hane creates an ActionRequest that fixes the operation’s content. An approval decides on this fixed content (the approval subject). It shows what will be done, to whom, for how much, and whether the effect is irreversible, exactly as fixed by the server.

When closing an approval task, send the digest of the approval subject you saw as action_digest. If it differs from the current content, the response is 409 and neither approval nor rejection is recorded.
The person who started an agent run cannot approve the operations with external effects that the run proposed.
When an approval has stages, the same person cannot approve in two stages. A rejection at any stage stops it.
An operation approved after its expiry is not executed.
Even after approval, suspension, the proposer’s permissions, and similar conditions are checked again right before execution, and the operation is not executed if it should be stopped.

When an operation performed by a person (mail, phone, counter, and so on) is approved, an execution task is created for the assignee, who records the result of what they did and closes the task. If they did something different from what was approved, it is recorded as a deviation, is not treated as complete, and goes back for approval.

Who may decide (DeciderPolicy)

Who decides each operation is set by a DeciderPolicy manifest, which an agent refers to with approval.decider in its definition. Without one, people decide every operation.

apiVersion: approvals/v1alpha1
kind: DeciderPolicy
metadata:
  name: lease-application
spec:
  rules:
    - tools: [human.perform]
      when: { amount: { field: input.amount, at_least: 1000000 } }
      decider: human
      stages: [{ group: approvers }, { group: accounting }]   # department head, then accounting
    - tools: [human.perform]
      decider: human
      stages: [{ group: approvers }]

Rules are matched from the top, and the first matching rule sets the decider and the approval stages. An operation that matches no rule is decided once by a person. An amount that cannot be read is treated as unlimited.

Decider (`decider`)	Meaning
`human`	Only people can approve. `stages` can set groups that approve in order
`agent_or_human`	A review agent (`reviewer`) can also approve. The review agent returns approve, reject, or escalate to a person
`policy`	Approves a matching proposal (`when`) at proposal time without creating a task. For email, SMS, and calls, it can be used only for recipients contacted before (`first_contact: false`)

Conditions (when) can include the amount (amount), whether the recipient is internal or external (recipient), and whether the recipient is new (first_contact). Portal flows, writes to your app’s API, and operations performed by people can only be human.

Return to human-only approval immediately

To stop AI-handled approvals, you can return a tool’s approvals to people only without waiting for a ReleaseBundle. It takes effect immediately, including for proposals already awaiting approval.

POST /v1/agents/decider-overrides
Authorization: Bearer <access token>
Idempotency-Key: 8d02…
Content-Type: application/json

{ "tools": ["communication.send_email"], "reason": "Reviewing the content of outgoing mail" }

This requires the approvals:deciders.restrict scope, which operator also has. Only admin can remove the override and return to the DeciderPolicy (DELETE /v1/agents/decider-overrides/{tool}).