Belayline Agent Governance

Belayline Agent Governance governs other plugins’ agent tool calls, not just its own. It sits between AI

agents (through the WordPress Abilities API, and through MCP servers built on

mcp-adapter, as WooCommerce’s is) and the actions

those agents can take on your site. Every governed call is classified by tier, checked against a

capability pack bound to the calling identity, and written to a tamper-evident, hash-chained

audit log, before it runs.

The plugin is WordPress-general. It ships a core/* module that runs on every site, and a

WooCommerce module that wires in automatically when WooCommerce is active. Neither one trusts a

tool’s own “read-only” or “safe” label; classification comes from the plugin’s own policy map.

Capability packs and tiers

Every governed ability maps to a tier: reversible (read), side-effecting (write), or

irreversible (delete, refund, cancel). A capability pack is a named, scoped view of the verb

catalog for one identity — a WordPress application password, a user or role, or a WooCommerce

REST API key — with an allow list, a hard-denied tier class, a per-tier approval requirement, and

optional rate and spend limits. A credential with no explicit binding falls back to a safe

default pack rather than inheriting full access.

Human approval

When a pack requires approval for a tier (the starter packs do for irreversible calls), a call

at that tier doesn’t execute. It is queued under Tools → Pending Agent Actions for a human

to approve or reject. When an

Approval is requested, Belayline Agent Governance captures a fingerprint of the target’s current state; when

the approval is claimed, it re-checks that fingerprint. A mismatch means the target changed

between request and claim, so the old approval is marked stale and a fresh request is filed. This

narrows the gap between a human’s approval and the write — it does not close it, because the

short window between claiming an approval and executing the call still exists.

Self-service approval status

An agent can call belayline/check-approval with an approval_id to poll its own request

without a human in the loop. It reports a reduced, public status (pending, approved, rejected,

expired, used, or superseded) and a plain-English next_action, and never returns the approver’s

identity, the original arguments, or any token.

Hash-chained audit log

Every gate decision and executed action is appended to an append-only, hash-chained log under

Tools → Agent Audit Log, with a tamper-evidence check that re-verifies the chain on load.

Core coverage

Governs the three abilities WordPress core registers today. Any other core/* ability is denied

until Belayline Agent Governance maps it, so future core write abilities fail closed rather than run

ungoverned.

WooCommerce coverage

When WooCommerce is active, Belayline Agent Governance governs exactly these 16 abilities:

• woocommerce/products-list

• woocommerce/products-get

• woocommerce/products-create

• woocommerce/products-update

• woocommerce/products-delete

• woocommerce/products-query

• woocommerce/product-create

• woocommerce/product-update

• woocommerce/product-delete

• woocommerce/orders-list

• woocommerce/orders-get

• woocommerce/orders-create

• woocommerce/orders-update

• woocommerce/orders-query

• woocommerce/order-add-note

• woocommerce/order-update-status

Everything else under woocommerce/ is refused as an unknown verb. Deleting a product with

force: true is classed irreversible; a plain delete (trash) is side-effecting.

Which MCP endpoint to use

WooCommerce’s own MCP endpoint ( /wp-json/woocommerce/mcp ) is deprecated by WooCommerce itself,

which points clients at the shared mcp-adapter server instead. Belayline Agent Governance governs both the

same way, through the ability permission check, but the two endpoints don’t expose the same

information to an agent:

• On the shared mcp-adapter server, an agent that hits approval_required gets the full error

data, including approval_id, and can call belayline/check-approval to poll it.

• On WooCommerce’s own endpoint, the bundled mcp-adapter 0.3.0 only forwards the error message

text to the client, not the structured error data. An agent sees the message “needs human

approval” but not the approval_id, and belayline/check-approval isn’t reachable on that

transport at all — the approval still exists and is visible on the Pending Actions page, but

the agent can’t self-serve it.

We recommend running agents against the shared mcp-adapter server. WooCommerce’s own endpoint is

supported for as long as WooCommerce ships it, with the limitation above.

Environment awareness

Belayline Agent Governance notices when a site’s address changes (a migration, a staging clone) and treats it

as a new environment: shadow-mode windows, active grants, and approved-but-unclaimed approvals

are all voided rather than carried over silently, and an admin notice stays up until someone

rebinds the site from the settings page. Production sites ( wp_get_environment_type() ===

'production', WordPress’s own default) never default to shadow mode and cap any shadow window at

24 hours.

Multisite

WordPress multisite is not supported. Activation is refused on a multisite install, network-wide

or per site.

External services

This plugin can send data outside your site in two ways.

Email. When a new agent action needs approval, Belayline Agent Governance sends an email through

wp_mail() to the site’s admin email address, or to a recipient set on the Pending Agent

Actions screen, linking to the login-protected review screen. It goes through your site’s own

mail delivery.

Webhook (opt-in). An administrator can set a webhook URL on the Pending Agent Actions

screen. When

set, every new pending approval sends an HTTP POST to that URL with a JSON body containing the

event name, the approval id, the verb (ability) that was called, and a link to the review screen.

No call arguments are sent. The webhook is off until an administrator enters a URL, and the

destination is the site operator’s choice. Nothing is sent to the plugin’s author.

Privacy

Belayline Agent Governance keeps a hash-chained audit log of gate decisions and executed agent actions,

including the identity that made the call. A personal-data export for a WordPress user includes

their matching audit rows. An erasure request does not delete them: they are reported as

retained, with a note that they’re kept as a tamper-evident security record, because rewriting a

row would break the hash chain that proves the log hasn’t been tampered with. Matching is done by

resolving the requester’s email to a WordPress user and matching rows on that user only; recorded

tool inputs are never searched for personal data, but they may contain it, since they can include

data handled by other plugins (customer records, order details) that the calling agent’s tool

touched.