How an approval works

The lifecycle

1. An agent requests an Ability whose decision is require approval.
2. The request is held. Nothing executes, and nothing in WordPress changes.
3. The request appears in the Approval Center with its context and a redacted input preview.
4. A person approves, rejects, or lets it expire.
5. If approved, the agent retries. The approval is claimed atomically and the exact reviewed request executes.

Step five is the important one. Approval does not run the action; it authorizes exactly one retry of it.

Four properties worth memorising

Input-bound

The approval covers the exact request fingerprint that was reviewed. Different arguments produce a different fingerprint and need a new decision.

One-time

The approval is claimed when used, so the same grant cannot authorize a second call.

Time-bounded

Pending and approved requests expire on their own. An unused approval does not quietly become a permission.

Attributable

Who decided, when, and on what evidence stays in the audit trail.

What the agent sees

WordPress returns HTTP 403 for a permission-callback error, so a held request reaches the agent as a 403. The approval identifier and the retry instructions are carried in the response’s additional data rather than in the status code.

A well-behaved agent should treat that as “waiting on a human” and retry the identical request later — not as a hard failure to be worked around, and not as a prompt to try different arguments.

Three routes to the same queue

A request can require approval because the permission matrix says so, because the contextual risk engine escalated it, or because policy escalation applied. All three resolve through one path, so an approval created for any of them authorizes the retry.

Related guides

• ApprovalRequest waiting for approval

  What the Approval Center shows you, what to check before deciding, and how to make a judgement you could defend later.

• ApprovalApproval not found

  The agent retried but no approval matched. Almost always the inputs changed, the approval expired, or the retry came from a different identity.

• ApprovalKeep the approval queue meaningful

  A queue that is always approved has stopped being a control. How to tell the difference between real review and rubber-stamping, and what to change.