Abilities API: add execution lifecycle filters to WP_Ability methods

[gziolo]

Summary

Adds four new filters to WP_Ability to give plugins hook points across the execution
lifecycle. Today the only execution-phase hooks are observation-only actions
(wp_before_execute_ability, wp_after_execute_ability); plugins that need to
transform input, modify output, override permission decisions, or short-circuit
execution have no place to do that in core, and have built parallel hook systems
on top.

This PR closes that gap by introducing four filters that live inside their
owning WP_Ability methods (so they apply consistently across execute() and
direct callers, including REST permission checks), plus one orchestration-level
filter at the top of execute() for short-circuiting.

Filters added

Filter	Where	Purpose
wp_pre_execute_ability	top of execute()	Short-circuit. Returning a value other than the received default bypasses the entire pipeline. Uses a WP_Filter_Sentinel instance as the default so null, false, and arbitrary objects are valid short-circuit results.
wp_ability_normalize_input	inside normalize_input()	Transform input — prompt enrichment, parameter defaulting beyond JSON Schema, caller metadata injection. Returning WP_Error halts execution.
wp_ability_permission_result	inside check_permissions()	Override the registered permission_callback result. Applies consistently across execute() and direct check_permissions() callers.
wp_ability_execute_result	inside do_execute()	Transform the result before output validation. Can also recover from execute callback failures by returning a successful value in place of WP_Error.

Pipeline ordering inside execute()

wp_pre_execute_ability  (filter, can short-circuit)
  → normalize_input()   → wp_ability_normalize_input  (filter)
  → validate_input()
  → check_permissions() → wp_ability_permission_result (filter)
  → wp_before_execute_ability  (existing action)
  → do_execute()        → wp_ability_execute_result   (filter)
  → validate_output()
  → wp_after_execute_ability   (existing action)
  → return

Schema validation remains the final integrity gate: wp_ability_normalize_input
fires before validate_input(), and wp_ability_execute_result fires before
validate_output(). Filters cannot bypass schema validation except by
short-circuiting via wp_pre_execute_ability, where the caller takes
responsibility for the returned value's shape.

WP_Filter_Sentinel

Introduces a small, reusable marker class (src/wp-includes/class-wp-filter-sentinel.php)
loaded alongside WP_Hook in wp-includes/plugin.php. Each instance is unique by
identity, so callers can pass one as a filter's default value and compare returns
with === to detect "no filter modified this" — even when valid replacement values
include null, false, or arbitrary objects. Used by wp_pre_execute_ability,
and available for any future filter that needs the same pass-through detection.

REST behavior

WP_REST_Abilities_V1_Run_Controller::check_ability_permissions() now propagates
WP_Error results from normalize_input() directly instead of feeding them into
validate_input(). When the filter does not set its own status, the controller
defaults to 400; filter-set statuses (e.g., 422, 429) are preserved.

Test plan

• npm run env:composer -- format — clean
• npm run env:composer -- lint — clean
• npm run env:composer -- compat — clean
• npm run typecheck:php — 0 errors
• PHPUnit Abilities suite — 1138 tests passing

New tests cover:

• Each filter's transformation contract (input rewrite, permission grant/deny override, WP_Error recovery, result transform), with filter args verified via args-as-guards on the transformed value rather than side-effect captures.
• Short-circuit semantics for wp_pre_execute_ability: pipeline configured to fail (permission denial) so the short-circuit value coming through cleanly proves the bypass.
• null short-circuit preserved by the WP_Filter_Sentinel pattern.
• Arbitrary object short-circuit values are not confused with the WP_Filter_Sentinel default.
• Ordering: wp_ability_execute_result runs before output validation and before wp_after_execute_ability.
• WP_Error propagation from wp_ability_normalize_input halts execution.
• wp_ability_permission_result firing when check_permissions() is called directly.
• REST: normalization filter errors default to status 400 and preserve filter-set statuses.

Trac ticket

https://core.trac.wordpress.org/ticket/64989

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code, Codex
Model(s): Claude Opus 4.7 (1M context)
Used for: Planning, implementation, unit tests, code review, commit messages, and PR description.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props gziolo, westonruter, migueluy.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[lezama]

This is super useful for any substrate that mediates ability execution on behalf of agents. Sharing four concrete use cases from that perspective so the filter shapes can be validated against them:

Filter	Use case in an agent runtime
wp_pre_execute_ability	Approval boundary: an agent runtime that ships a pending-action approval gate can hook here to short-circuit with an "approval required" envelope when a sensitive ability is invoked, instead of running. Also useful for contract tests: a recording harness can short-circuit with canned tool results so non-conversation behavior (provider call → tool call → provider call) gets locked into baselines without real execution.
wp_ability_normalize_input	Agent context injection: the runtime can inject the current execution principal (calling agent ID, user, workspace, caller-chain context) into the ability's input. Abilities that need agent context don't have to receive it as an explicit parameter — it's normalized in by the substrate layer.
wp_ability_permission_result	Tool access policy: an agent-level access policy (e.g. "this agent's bearer token doesn't authorize destructive abilities") can override the ability's registered permission_callback without modifying the ability itself. Cleaner than wrapping every ability with a delegating permission_callback.
wp_ability_execute_result	Transcript / observability: tool calls + results get captured into the agent's transcript or routed to a telemetry sink without each ability having to opt in. The fact that this fires before validate_output() is exactly right — it preserves the integrity gate.

The "schema validation remains the final integrity gate" framing matches what a substrate wants downstream: filters can transform but can't bypass the contract.

One small thing I'd double-check: when the agent runtime hooks wp_pre_execute_ability and short-circuits with an approval envelope, the caller (an AgentConversationLoop or similar) needs to be able to distinguish "approval pending" from "ability returned a value" in the response shape. A typed sentinel value object would be clearest there, but with the current mixed return + sentinel approach the runtime can wrap with a typed value object on its side — the filter API doesn't need to bake that in.

cc / FYI: this would be consumed by Automattic/agents-api once it lands in core.

[gziolo]

Thanks for the feedback. I'm glad the four shapes map cleanly to a substrate's needs. Keeping the short-circuit return as mixed is deliberate so consumers like agents-api can define their own envelope (approval-pending vs. value) without core picking a shape.

[westonruter]

Clever. I was thinking at first this wouldn't be good since it doesn't match filters like pre_option which work by using false as the sentinel value. But since the ability can return any value at all, then this wouldn't work.

[gziolo]

I discovered the same pattern used in Customizer where similarly null is a valid output.

We still might need to iterate on it based in feedback shared in WordPress/ai#477 (reply in thread) by @ibrahimhajjaj:

The stdClass sentinel is fine in isolation but hard to compose. A filter callback can't hold a reference to the per-call sentinel, so all we have is instanceof stdClass. If two plugins both want "pass through, no opinion" they can't tell each other's sentinels apart from core's. Worth a line in the docblock maybe.

I'm considering a formal WP_Filter_Sentinel class to made it first-class concept removing the ambiguity. That would be similar to WP_Error on the naming level, but very specialized.

[westonruter]

I discovered the same pattern used in Customizer where similarly null is a valid output.

Oh, yeah:

wordpress-develop/src/wp-includes/class-wp-customize-setting.php

Lines 338 to 345 in 7938204

	/*
	* Check if the setting has a pre-existing value (an isset check),
	* and if doesn't have any incoming post value. If both checks are true,
	* then the preview short-circuits because there is nothing that needs
	* to be previewed.
	*/
	$undefined = new stdClass();
	$needs_preview = ( $undefined !== $this->post_value( $undefined ) );

I added that in e158ff2 😊

[gziolo]

Improved with 28f5f48.