Pro module4 abilities

Approvals ability reference

Reference for the GoBuildWP Pro 1.12.4 source. Installed schemas and policy remain authoritative.

This Approvals ability reference covers how an agent reads and changes the policy that decides which of its writes wait for a person, lists the calls the queue is holding, and passes on a decision a person has made. A held write does not run: the agent gets a request number back instead of a result, and the write happens later, if at all, when someone approves it.

By GoBuildWPContent updated 12 October 2026How we check claims

Read-only, write and destructive groups describe the source annotations. They do not establish a minimum safety profile, human approval or undo support. Those controls are separate: check the installed ability, the connected user and the active site policy before calling it. A read can still return sensitive data. These pages are not evidence that every operation passed an end-to-end runtime test.

What Approvals needs before these load

Approvals is part of GoBuildWP Pro and needs no other plugin. The four abilities register once the licensed queue has loaded. On a site whose licence is inactive, the stored policy is still enforced, but a write it covers is refused outright with wppilot_pro_approval_unavailable rather than parked, and nothing can edit the policy. Every call checks that GoBuildWP is switched on and that the user has manage_options (super admin on multisite). Deciding over MCP additionally needs GoBuildWP's confirmation mode set so that a person approves destructive calls.

What a held call returns, and which rule held it

A write the policy covers comes back as the error wppilot_pro_awaiting_approval with HTTP status 202 and a request_id, and a message naming the request as "Request #N". If the request cannot be saved, the agent gets wppilot_pro_approval_hold_failed and the call still does not run. Reads are never held.

The default mode is off, writes or destructive. destructive holds what the free plugin rates destructive or critical, such as deletes, refunds, plugin lifecycle and account changes, while letting code execution through, which the safety profile governs instead. A client can also be set to trusted: reads and ordinary writes run, destructive writes and code execution wait. Rules (up to 200) hold or release a named ability or a wppilot/ prefix ending in *, for one client or all of them.

Why an agent cannot approve or loosen its own review

wppilot/approval-decide counts a decision when the confirmation came from a person: the MCP client's own prompt, a one-time wp-admin link or Chat. An agent passing confirm=true itself gets wppilot_pro_approval_needs_person (HTTP 403) and nothing is decided. wppilot/approval-set-policy needs confirm=true or dry_run=true, and is refused with wppilot_pro_approval_self_loosening when the change would stop holding any ability for the client making it; that kind of change belongs on the Approvals screen.

Where held input is kept, and for how long

Each held call is a post of the private wppilot_approval type. Its input is encrypted with AES-256-GCM, keyed from the site's auth salt, before it reaches post meta, and is deleted as soon as the request is approved, rejected or fails. Payload-free records of decided requests are kept 7 days by default (the wppilot_pro_approval_retention_days filter accepts 1 to 90); undecided requests are removed after 30 days. When the list call shows an input, keys that look like passwords, tokens or keys read [redacted] and email addresses read [email].

Before accepting the result

Policy precedence separates named ability rules, client modes and the saved default. Off, writes and destructive are site modes; trusted is a client mode. Approval does not grant capabilities: inspect the actor recorded by the actual request. Follow pending through approved, rejected or failed; do not invent an expired status.

Safety profiles and human confirmation

Representative call sequence

This sequence describes the documented calls and checks to perform. It is not a recorded result from an installed WordPress site. Inspect returned errors and partial results, then verify the saved values and affected output before proceeding.

An agent's request to delete an old landing page comes back held, and the site owner wants to approve it from the MCP client.

01 wppilot/approval-get-policy Returns the calling client's key and effective mode, which shows whether the default, the client's mode or an ability rule held the delete.
02 wppilot/approval-list-requests Returns the request by its number with the masked input, who asked, its status, and whether this account can decide it over MCP.
03 wppilot/approval-decide After the owner confirms in the client's own prompt, runs the held delete under current safety rules; the delete is recorded as its own change, with only the undo that the delete ability itself supports.

The approval queue in practice

Who hears about a held write, and how often

A queue nobody looks at stalls the agent, so GoBuildWP Pro emails the site's admin address when a write is held. The email is on by default and can be switched off by an owner who prefers to watch the badge in wp-admin. Two filters change its behaviour: wppilot_pro_approval_notify_recipient sends it somewhere other than the admin email (a shared inbox, for example), and wppilot_pro_approval_notify_cooldown changes the gap between messages, which is 15 minutes by default. A burst of held calls therefore produces one email, and the Approvals screen shows how many are waiting.

The message deliberately leaves the held input out. It names the ability, says which client asked (or that the client was unnamed, or that the request carried no agent credential at all), gives the number of pending requests and links to the Approvals screen. It also states that nothing ran. Draft content, settings values and customer text stay behind the capability check on that screen, because email is often forwarded and is not encrypted.

Approving from inside the AI client instead of wp-admin

MCP clients that render app content can show an approval card for a held request. The card and wppilot/approval-decide sit on the same rule: a decision counts only when the confirmation came from the client's own confirmation prompt, a one-time wp-admin link or Chat's approve button. On a site left in the default argument confirmation mode, no decision sent over MCP can meet that bar, so the card says so and points to the Approvals screen rather than offering a button that would fail. Switching the site to human confirmation is what makes in-client approval possible; see approvals, memory and skills.

wppilot/approval-list-requests reports, per request, whether the current account can decide it and why not. The two reasons are an account without GoBuildWP's manage capability, and the argument confirmation mode. Approving does not borrow the agent's rights: the held ability's own permission check runs again as the person approving, so an approver who lacks a capability the call needs cannot push it through.

How much of a held input the card shows

The list call and the card travel through the MCP client into the model's context, so they show less than the Approvals screen. Strings are cut at 2,000 characters with the full length stated, arrays at 100 items per level with a count of what was left out, and nesting below six levels is hidden. Keys that look like passwords, secrets, tokens, authorisation headers, API or private keys, licences, cookies or credentials are replaced with [redacted], and anything shaped like an email address becomes [email]. A reviewer who needs the whole input opens the request on the Approvals screen.

Following a request through executing, approved and failed

Approving claims the request as executing and sends the held input back through the same gate a live call passes, with today's permissions and safety profile. If that gate refuses (the profile was tightened since, or the approver lacks a capability), the request returns to pending with the reason and nothing runs. The same happens when the installed GoBuildWP Free is older than the version Pro needs to approve requests. Only after the gate passes does the ability run.

The decide result has an ok flag and a message, and the agent should read both rather than the status alone. When the ability returns an error, the request is recorded as approved while ok is false and the message begins Approved, but the ability failed. When the ability throws, the request becomes failed and will not run again. In both cases the encrypted input is cleared, so retrying means sending a new call, which the queue may hold again.

A decision on an id that is not an approval request returns wppilot_pro_approval_not_found with HTTP 404; check the number in the Request #N message. A request already decided is reported as it stands rather than run twice, so an agent that retries after a timeout does not repeat the write.

Questions about Approvals

Can my agent make ordinary edits unreviewed while deletions still wait?

Yes. Set that client's mode to trusted: reads and ordinary writes run, and destructive writes and code execution are held. An ability rule can still hold a specific ability on top of that.

What happens to agent writes if my Pro licence lapses with approvals switched on?

They are refused, not run. The error is wppilot_pro_approval_unavailable, it says retrying will not help, and nothing is added to the queue; read-only calls carry on working.

Approvals reads

Ability What it does

wppilot/approval-get-policyGet Approval Policy Returns the approval policy: the default mode (off, writes, destructive), per-client modes (the same plus trusted), and per-ability rules (hold, never, inherit) whose patterns are ability names or a wppilot/ prefix ending in *. Also returns the calling client's key, its effective mode, and whether the queue holds anything for it. Precedence, most specific first: an ability rule for this client, the client's mode, an ability rule for any client, the default. Reads are never held.

wppilot/approval-list-requestsList Approval Requests Lists agent calls the approval queue is holding, oldest first, or one request by request_id (the number a held call reports as "Request #N"). Each has the ability, its input with secrets and email addresses masked, who asked (WordPress login and client label), when, and its status: pending, executing, approved, rejected or failed. decide says whether this account can approve or reject over MCP and, if not, why; approvals_url is the wp-admin screen where a person can. Nothing is changed.

Ability	What it does
`wppilot/approval-get-policy`Get Approval Policy	Returns the approval policy: the default mode (off, writes, destructive), per-client modes (the same plus trusted), and per-ability rules (hold, never, inherit) whose patterns are ability names or a wppilot/ prefix ending in *. Also returns the calling client's key, its effective mode, and whether the queue holds anything for it. Precedence, most specific first: an ability rule for this client, the client's mode, an ability rule for any client, the default. Reads are never held.
`wppilot/approval-list-requests`List Approval Requests	Lists agent calls the approval queue is holding, oldest first, or one request by request_id (the number a held call reports as "Request #N"). Each has the ability, its input with secrets and email addresses masked, who asked (WordPress login and client label), when, and its status: pending, executing, approved, rejected or failed. decide says whether this account can approve or reject over MCP and, if not, why; approvals_url is the wp-admin screen where a person can. Nothing is changed.

Destructive Approvals calls

Ability What it does

wppilot/approval-set-policySet Approval Policy Changes the approval policy. default_mode replaces the default; clients merges per-client modes by client key (inherit removes a row); rules replaces the whole rule list. Requires confirm=true; dry_run=true returns the resulting policy and writes nothing. This call is itself held for approval whenever the queue covers the calling client, and it is refused when it would stop holding any ability for the calling client: a client cannot relax its own review. An administrator makes that kind of change on the GoBuildWP Approvals screen. Reversible with wppilot/rollback-change.

wppilot/approval-decideDecide an Approval Request Approves (runs) or rejects one held call, as a person would on the GoBuildWP Approvals screen. It counts only when a person confirmed this exact decision - through the MCP client's own confirmation prompt, a one-time wp-admin link, or Chat - so an agent's own confirm=true is refused and nothing is decided. Approving runs the held call under this account's permissions and today's safety rules; the write it makes is recorded as its own change, which can be undone only where that ability's changes are undoable. A request already decided is reported, not decided twice.

Ability	What it does
`wppilot/approval-set-policy`Set Approval Policy	Changes the approval policy. `default_mode` replaces the default; `clients` merges per-client modes by client key (inherit removes a row); `rules` replaces the whole rule list. Requires confirm=true; dry_run=true returns the resulting policy and writes nothing. This call is itself held for approval whenever the queue covers the calling client, and it is refused when it would stop holding any ability for the calling client: a client cannot relax its own review. An administrator makes that kind of change on the GoBuildWP Approvals screen. Reversible with wppilot/rollback-change.
`wppilot/approval-decide`Decide an Approval Request	Approves (runs) or rejects one held call, as a person would on the GoBuildWP Approvals screen. It counts only when a person confirmed this exact decision - through the MCP client's own confirmation prompt, a one-time wp-admin link, or Chat - so an agent's own confirm=true is refused and nothing is decided. Approving runs the held call under this account's permissions and today's safety rules; the write it makes is recorded as its own change, which can be undone only where that ability's changes are undoable. A request already decided is reported, not decided twice.