Agent Warden
Sign inInstall free
Documentation menu

Make your plugin Agent Warden-aware

Agent Warden governs every ability registered with the WordPress Abilities API. It needs nothing special from your plugin. A few annotations and filters make your abilities safer and clearer for site owners.

1. Register abilities with annotations#

Mark read-only and destructive abilities. Templates allow only read-only abilities automatically, and never auto-allow an ability without a readonly annotation.

php
wp_register_ability( 'myplugin/delete-report', array(
	'label'               => __( 'Delete a report', 'myplugin' ),
	'category'            => 'myplugin',
	'input_schema'        => array( 'type' => 'object', 'properties' => array( 'id' => array( 'type' => 'integer' ) ) ),
	'permission_callback' => static fn() => current_user_can( 'delete_reports' ),
	'execute_callback'    => 'myplugin_delete_report',
	'meta'                => array( 'annotations' => array( 'readonly' => false, 'destructive' => true ) ),
) );

Always keep a real permission_callback. Agent Warden never skips it, even when a policy allows the ability.

2. Say how reversible each ability is#

php
add_filter( 'agentwarden_ability_reversibility', static function ( $classification, string $ability ) {
	return 'myplugin/delete-report' === $ability ? 'irreversible' : $classification;
}, 10, 2 );

Irreversible abilities are refused while the irreversible hard block is on.

3. Journal your tables for undo#

php
add_filter( 'agentwarden_journal_tables', static function ( $tables ) {
	global $wpdb;
	$tables['myplugin_reports'] = array(
		'table' => $wpdb->prefix . 'myplugin_reports', // Physical table name.
		'key'   => 'id',                               // Column that identifies a row.
		'set'   => false,                              // True when a key names a set of rows, like meta for one post.
	);
	return $tables;
} );

Core tables cannot be replaced, and entries with a different shape are ignored.

4. Summaries people can read#

php
add_filter( 'agentwarden_summary_template', static function ( $summary, string $ability, $input ) {
	return 'myplugin/delete-report' === $ability ? sprintf( 'Delete report #%d', (int) ( $input['id'] ?? 0 ) ) : $summary;
}, 10, 3 );

5. Or ship a policy pack#

A pack bundles all of the above: reversibility, hard blocks, capabilities, summaries, journal tables, and scope targets. It registers through agentwarden_policy_packs, implementing the AgentWarden\Policy\Packs\Pack interface. The WooCommerce, ACF, and Yoast packs are working examples.

Every filter's arguments are in the hooks reference. To react to decisions, use agentwarden_request_decided, agentwarden_action_logged, agentwarden_approval_decided, and agentwarden_undo_completed.