Add property for marking Ability hints like destructive, read-only, idempotent

[JasonTheAdams]

Oftentimes we want to give the AI different instructions for when it's about to perform a destructive action, such as framing what's about to happen and requesting confirmation to the user. It would be helpful, therefore, to have a property of an Ability that marks it as a destructive ability.

[gziolo]

@marcochiesi raised the same use case in WordPress/ai#40. The related points he described are:

• Abilities as "One More Way": I envision the abilities API as "one more way" for users to achieve results, as an alternative to the WordPress admin UI. Of course, we must ensure users are fully aware of what's happening and confirm potentially destructive actions. For this, the Model Context Protocol (MCP) standard includes a feature called "elicitation," which allows the MCP server to request additional information from the user (such as confirmation) before executing a task. More information here.
• Handling Destructive Operations: For the reason above, I would not limit plugin management or other destructive operations, as long as we can guarantee that the user is forced to confirm before proceeding. We should simply ensure that LLMs do not perform such actions without explicit confirmation. I believe over-engineering with the possibility of "undo" actions is out of scope. Currently, when using the standard WordPress UI, the user cannot easily undo these destructive operations.

[swissspidy]

Let's go beyond just "destructive" and think about other hints as well. For example, MCP tools annotations include: read-only, destructive, idempotent, requires confirmation, whether it's "open world"

[justlevine]

Recommend that for the initial implementation, we store this in $meta as it gives us more flexibility to iterate without worrying too much about coupling our API to transient concerns from an evolving spec, or one specific implementation (MCP) over another (e.g. Command Palette).

[galatanovidiu]

Should we use user capabilities/roles on the abilities somehow, so we can easily filter abilities based on user capabilities before even presenting them to AI agents (in any form)?

I know we have the has_permission callback for granular permission checks at execution time. Still, a simple capability-based pre-filter could be beneficial for performance, especially in the MCP contexts - avoiding permission callback execution for abilities the user can't access anyway.

Something like:

wp_register_ability( 'delete-post', [
    'label' => __('Delete Post'),
    'hints' => [
        'destructive' => true,
        'requires_confirmation' => true,
    ],
    'required_capabilities' => ['delete_posts'], // New property
    'permission_callback' => function( $input ){...}, // Existing granular check
] );

Following @justlevine's suggestion, this could live in $meta initially.

[swissspidy]

IMO this just adds redundancy and risks getting out of sync. It also does not work for things like contributor user roles, where you can delete your own posts but not others. Executing permission callbacks should be fine performance-wise, even if there are many.