Changeset 62397

Timestamp:

05/21/2026 07:56:31 AM (3 months ago)

Author:

gziolo

Message:

Abilities API: Add execution lifecycle filters to WP_Ability methods

Introduce four filters that give plugins hook points across the ability execution lifecycle, complementing the existing observation-only actions
(wp_before_execute_ability, wp_after_execute_ability):

• wp_pre_execute_ability: short-circuits execute() when it returns a value other than the supplied default.
• wp_ability_normalize_input: transforms input inside normalize_input(), and returning WP_Error halts execution.
• wp_ability_permission_result: overrides the permission_callback result inside check_permissions(), consistently for execute() and direct callers.
• wp_ability_execute_result: transforms the result inside do_execute() before output validation, and can recover from execute callback failures.

The input and result filters fire before their respective schema validation steps, so validate_input() and validate_output() remain the final integrity gates. Only wp_pre_execute_ability can bypass validation, with the caller owning the returned value's shape.

Add WP_Filter_Sentinel, a reusable marker class loaded alongside WP_Hook, whose per-instance identity lets a filter default be distinguished from any
user value — including null, false, or arbitrary objects — via ===.

Update WP_REST_Abilities_V1_Run_Controller::check_ability_permissions() to propagate WP_Error results from normalize_input() directly, defaulting to
status 400 while preserving filter-set statuses (e.g. 422, 429).

Props gziolo, westonruter, migueluy.
Fixes #64989.

Location:

trunk

Files:

• src/wp-includes/abilities-api/class-wp-ability.php (modified) (7 diffs)
• src/wp-includes/class-wp-filter-sentinel.php (added)
• src/wp-includes/plugin.php (modified) (1 diff)
• src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-run-controller.php (modified) (1 diff)
• tests/phpunit/tests/abilities-api/wpAbility.php (modified) (1 diff)
• tests/phpunit/tests/rest-api/wpRestAbilitiesV1RunController.php (modified) (1 diff)

trunk/src/wp-includes/abilities-api/class-wp-ability.php

@@ -437 +437 @@
          * this method returns null. If input is provided, it is returned as-is.
          *
-         * @since 6.9.0
+         * The {@see 'wp_ability_normalize_input'} filter fires after the built-in default-value handling,
+         * allowing plugins to transform the result.
+         *
+         * @since 6.9.0
+         * @since 7.1.0 Added the `wp_ability_normalize_input` filter.
          *
          * @param mixed $input Optional. The raw input provided for the ability. Default `null`.
-         * @return mixed The same input, or the default from schema, or `null` if default not set.
+         * @return mixed The normalized input, or a `WP_Error` if a filter returned one.
          */
         public function normalize_input( $input = null ) {
-                if ( null !== $input ) {
-                        return $input;
-                }
-
-                $input_schema = $this->get_input_schema();
-                if ( ! empty( $input_schema ) && array_key_exists( 'default', $input_schema ) ) {
-                        return $input_schema['default'];
-                }
-
-                return null;
+                if ( null === $input ) {
+                        $input_schema = $this->get_input_schema();
+                        if ( array_key_exists( 'default', $input_schema ) ) {
+                                $input = $input_schema['default'];
+                        }
+                }
+
+                /**
+                 * Filters the normalized input for an ability.
+                 *
+                 * Fires after `normalize_input()` has applied any default value declared in the input schema,
+                 * giving plugins a chance to adjust the input before it is consumed downstream. Common uses
+                 * include defaulting beyond what JSON Schema can express, prompt enrichment, and injecting
+                 * caller metadata.
+                 *
+                 * Returning a `WP_Error` causes callers that propagate it (such as `execute()`) to halt
+                 * before validation, permission checks, and the registered execute callback.
+                 *
+                 * @since 7.1.0
+                 *
+                 * @param mixed      $input        The normalized input data.
+                 * @param string     $ability_name The name of the ability.
+                 * @param WP_Ability $ability      The ability instance.
+                 */
+                return apply_filters( 'wp_ability_normalize_input', $input, $this->name, $this );
         }
 
@@ -532 +551 @@
          * Use `validate_input()` method to validate input before calling this method if needed.
          *
-         * @since 6.9.0
+         * The {@see 'wp_ability_permission_result'} filter fires after the registered
+         * `permission_callback` returns, allowing plugins to override the result.
+         *
+         * @since 6.9.0
+         * @since 7.1.0 Added the `wp_ability_permission_result` filter.
          *
          * @see validate_input()
@@ -548 +571 @@
                 }
 
-                return $this->invoke_callback( $this->permission_callback, $input );
+                $permission = $this->invoke_callback( $this->permission_callback, $input );
+
+                /**
+                 * Filters the result of an ability's permission check.
+                 *
+                 * Fires after the registered `permission_callback` returns. Plugins can use this to layer
+                 * additional authorization rules on top of the ability's own permission logic — for example,
+                 * multi-factor authorization gates or temporary permission elevation for trusted contexts.
+                 *
+                 * Filters can return `true` to grant, `false` to deny, or a `WP_Error` to deny with a specific
+                 * error code and message. The filter receives whatever the `permission_callback` produced.
+                 * Any other return value is coerced to `false`.
+                 *
+                 * @since 7.1.0
+                 *
+                 * @param bool|WP_Error $permission   The permission result returned by `permission_callback`.
+                 * @param string        $ability_name The name of the ability.
+                 * @param mixed         $input        The input data for the permission check.
+                 * @param WP_Ability    $ability      The ability instance.
+                 */
+                $result = apply_filters( 'wp_ability_permission_result', $permission, $this->name, $input, $this );
+                if ( ! is_bool( $result ) && ! is_wp_error( $result ) ) {
+                        $result = false;
+                }
+                return $result;
         }
 
@@ -554 +601 @@
          * Executes the ability callback.
          *
-         * @since 6.9.0
+         * The {@see 'wp_ability_execute_result'} filter fires before this method returns, allowing
+         * plugins to transform the result produced by the registered `execute_callback`.
+         *
+         * @since 6.9.0
+         * @since 7.1.0 Added the `wp_ability_execute_result` filter.
          *
          * @param mixed $input Optional. The input data for the ability. Default `null`.
@@ -561 +612 @@
         protected function do_execute( $input = null ) {
                 if ( ! is_callable( $this->execute_callback ) ) {
-                        return new WP_Error(
+                        $result = new WP_Error(
                                 'ability_invalid_execute_callback',
                                 /* translators: %s ability name. */
                                 sprintf( __( 'Ability "%s" does not have a valid execute callback.' ), esc_html( $this->name ) )
                         );
-                }
-
-                return $this->invoke_callback( $this->execute_callback, $input );
+                } else {
+                        $result = $this->invoke_callback( $this->execute_callback, $input );
+                }
+
+                /**
+                 * Filters the result returned by an ability's execute callback.
+                 *
+                 * Fires after the registered execute callback runs. Plugins can use this to transform the
+                 * result — response formatting, stripping internal metadata, content safety filtering,
+                 * response enrichment, or recovering from a failure by returning a successful value.
+                 *
+                 * The filter receives whatever the registered callback produced, including a `WP_Error`
+                 * if execution failed. Filters may pass the `WP_Error` through unchanged, override it with
+                 * a recovered result, or convert a successful result into a `WP_Error`.
+                 *
+                 * @since 7.1.0
+                 *
+                 * @param mixed      $result       The result returned by the registered `execute_callback`,
+                 *                                 or a `WP_Error` if execution failed.
+                 * @param string     $ability_name The name of the ability.
+                 * @param mixed      $input        The normalized input data.
+                 * @param WP_Ability $ability      The ability instance.
+                 */
+                return apply_filters( 'wp_ability_execute_result', $result, $this->name, $input, $this );
         }
 
@@ -606 +678 @@
          *
          * @since 6.9.0
+         * @since 7.1.0 Added the `wp_pre_execute_ability` filter.
          *
          * @param mixed $input Optional. The input data for the ability. Default `null`.
@@ -611 +684 @@
          */
         public function execute( $input = null ) {
-                $input    = $this->normalize_input( $input );
+                /**
+                 * Filters whether to short-circuit ability execution.
+                 *
+                 * Returning a value other than the received default bypasses the rest of `execute()` —
+                 * input normalization, input validation, permission checks, the registered execute callback,
+                 * output validation, and the surrounding actions — and the value is returned to the caller
+                 * as-is. Useful for cached responses, rate limiting, maintenance mode, and test mocking.
+                 *
+                 * To continue with normal execution, return `$pre` unchanged. This preserves any value
+                 * (including `null`, `false`, or arbitrary objects) as a valid short-circuit result.
+                 *
+                 * Because validation is bypassed, callers that short-circuit are responsible for the
+                 * integrity of any value they consume from `$input`.
+                 *
+                 * @since 7.1.0
+                 *
+                 * @param mixed      $pre          The pre-computed result. Return this value unchanged to continue execution.
+                 *                                 Default `WP_Filter_Sentinel` instance unique to this invocation.
+                 * @param string     $ability_name The name of the ability.
+                 * @param mixed      $input        The raw input passed to `execute()`.
+                 * @param WP_Ability $ability      The ability instance.
+                 */
+                $pre_execute_sentinel = new WP_Filter_Sentinel();
+                $pre                  = apply_filters( 'wp_pre_execute_ability', $pre_execute_sentinel, $this->name, $input, $this );
+                if ( $pre !== $pre_execute_sentinel ) {
+                        return $pre;
+                }
+
+                $input = $this->normalize_input( $input );
+                if ( is_wp_error( $input ) ) {
+                        return $input;
+                }
+
                 $is_valid = $this->validate_input( $input );
                 if ( is_wp_error( $is_valid ) ) {

trunk/src/wp-includes/plugin.php

@@ -24 +24 @@
 // Initialize the filter globals.
 require __DIR__ . '/class-wp-hook.php';
+require __DIR__ . '/class-wp-filter-sentinel.php';
 
 /** @var WP_Hook[] $wp_filter */

trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-abilities-v1-run-controller.php

@@ -159 +159 @@
                 }
 
-                $input    = $this->get_input_from_request( $request );
-                $input    = $ability->normalize_input( $input );
+                $input = $this->get_input_from_request( $request );
+                $input = $ability->normalize_input( $input );
+                if ( is_wp_error( $input ) ) {
+                        $error_data = $input->get_error_data();
+                        if ( ! is_array( $error_data ) || ! isset( $error_data['status'] ) ) {
+                                $input->add_data( array( 'status' => 400 ) );
+                        }
+
+                        return $input;
+                }
+
                 $is_valid = $ability->validate_input( $input );
                 if ( is_wp_error( $is_valid ) ) {

trunk/tests/phpunit/tests/abilities-api/wpAbility.php

@@ -827 +827 @@
                 $this->assertInstanceOf( WP_Error::class, $result, 'Should return WP_Error for output validation failure' );
         }
+
+        /**
+         * Tests that the wp_ability_normalize_input filter can transform input and receives the
+         * expected ability name and instance (verified via args-as-guards on the transformation).
+         *
+         * @ticket 64989
+         */
+        public function test_normalize_input_filter_can_transform_input() {
+                $args = array_merge(
+                        self::$test_ability_properties,
+                        array(
+                                'input_schema'     => array(
+                                        'type'        => 'string',
+                                        'description' => 'Test input string.',
+                                        'required'    => true,
+                                ),
+                                'output_schema'    => array(
+                                        'type'        => 'integer',
+                                        'description' => 'Result integer.',
+                                        'required'    => true,
+                                ),
+                                'execute_callback' => static function ( string $input ): int {
+                                        return strlen( $input );
+                                },
+                        )
+                );
+
+                $callback = static function ( $input, $ability_name, $ability ) {
+                        if ( self::$test_ability_name !== $ability_name || ! $ability instanceof WP_Ability ) {
+                                return $input;
+                        }
+                        return $input . '-transformed';
+                };
+
+                add_filter( 'wp_ability_normalize_input', $callback, 10, 3 );
+
+                $ability = new WP_Ability( self::$test_ability_name, $args );
+                $result  = $ability->execute( 'hello' );
+
+                remove_filter( 'wp_ability_normalize_input', $callback, 10 );
+
+                $this->assertSame( strlen( 'hello-transformed' ), $result, 'Result should reflect the transformed input flowing through the execute callback.' );
+        }
+
+        /**
+         * Tests that returning a WP_Error from wp_ability_normalize_input halts execution.
+         *
+         * @ticket 64989
+         */
+        public function test_normalize_input_filter_wp_error_halts_execution() {
+                $args = array_merge(
+                        self::$test_ability_properties,
+                        array(
+                                'input_schema'     => array(
+                                        'type'        => 'string',
+                                        'description' => 'Test input string.',
+                                        'required'    => true,
+                                ),
+                                'execute_callback' => static function ( string $input ) {
+                                        return strlen( $input );
+                                },
+                        )
+                );
+
+                $filter = static function () {
+                        return new WP_Error( 'normalize_halt', 'Halted from filter.' );
+                };
+
+                add_filter( 'wp_ability_normalize_input', $filter );
+
+                $ability = new WP_Ability( self::$test_ability_name, $args );
+                $result  = $ability->execute( 'hello' );
+
+                remove_filter( 'wp_ability_normalize_input', $filter );
+
+                $this->assertInstanceOf( WP_Error::class, $result, 'Filter returning WP_Error should propagate as the execute() result.' );
+                $this->assertSame( 'normalize_halt', $result->get_error_code(), 'WP_Error code should be preserved.' );
+        }
+
+        /**
+         * Tests that the wp_ability_permission_result filter can grant permission that the
+         * callback denied, with the filter's args verified via args-as-guards.
+         *
+         * @ticket 64989
+         */
+        public function test_permission_result_filter_can_grant_permission() {
+                $args = array_merge(
+                        self::$test_ability_properties,
+                        array(
+                                'input_schema'        => array(
+                                        'type'        => 'integer',
+                                        'description' => 'Test input integer.',
+                                        'required'    => true,
+                                ),
+                                'output_schema'       => array(
+                                        'type'        => 'integer',
+                                        'description' => 'Result integer.',
+                                        'required'    => true,
+                                ),
+                                'execute_callback'    => static function ( int $input ): int {
+                                        return $input;
+                                },
+                                'permission_callback' => static function (): bool {
+                                        return false;
+                                },
+                        )
+                );
+
+                $filter = static function ( $permission, $ability_name, $input, $ability ) {
+                        if ( false !== $permission ) {
+                                return $permission;
+                        }
+                        if ( self::$test_ability_name !== $ability_name || 7 !== $input || ! $ability instanceof WP_Ability ) {
+                                return $permission;
+                        }
+                        return true;
+                };
+
+                add_filter( 'wp_ability_permission_result', $filter, 10, 4 );
+
+                $ability = new WP_Ability( self::$test_ability_name, $args );
+                $result  = $ability->execute( 7 );
+
+                remove_filter( 'wp_ability_permission_result', $filter, 10 );
+
+                $this->assertSame( 7, $result, 'Filter should override the permission denial; reaching the execute callback proves all args matched expectations.' );
+        }
+
+        /**
+         * Tests that the wp_ability_permission_result filter can deny permission granted by the callback.
+         *
+         * @ticket 64989
+         */
+        public function test_permission_result_filter_can_deny_permission() {
+                $args = array_merge(
+                        self::$test_ability_properties,
+                        array(
+                                'execute_callback'    => static function (): int {
+                                        return 1;
+                                },
+                                'permission_callback' => static function (): bool {
+                                        return true;
+                                },
+                        )
+                );
+
+                $filter = static function () {
+                        return false;
+                };
+
+                add_filter( 'wp_ability_permission_result', $filter );
+
+                $ability = new WP_Ability( self::$test_ability_name, $args );
+                $result  = $ability->execute();
+
+                remove_filter( 'wp_ability_permission_result', $filter );
+
+                $this->assertInstanceOf( WP_Error::class, $result, 'Denied permission should produce a WP_Error.' );
+                $this->assertSame( 'ability_invalid_permissions', $result->get_error_code() );
+        }
+
+        /**
+         * Tests that the wp_ability_permission_result filter can convert a WP_Error denial from the
+         * callback into a grant, proving the filter receives the WP_Error verbatim.
+         *
+         * @ticket 64989
+         */
+        public function test_permission_result_filter_can_convert_wp_error_to_grant() {
+                $args = array_merge(
+                        self::$test_ability_properties,
+                        array(
+                                'execute_callback'    => static function (): int {
+                                        return 1;
+                                },
+                                'permission_callback' => static function (): WP_Error {
+                                        return new WP_Error( 'callback_denied', 'Denied by callback.' );
+                                },
+                        )
+                );
+
+                $filter = static function ( $permission ) {
+                        if ( ! is_wp_error( $permission ) || 'callback_denied' !== $permission->get_error_code() ) {
+                                return $permission;
+                        }
+                        return true;
+                };
+
+                add_filter( 'wp_ability_permission_result', $filter );
+
+                $ability = new WP_Ability( self::$test_ability_name, $args );
+                $result  = $ability->execute();
+
+                remove_filter( 'wp_ability_permission_result', $filter );
+
+                $this->assertSame( 1, $result, 'Filter received the WP_Error denial and converted it to a grant; execute callback returned its value.' );
+        }
+
+        /**
+         * Tests that the wp_ability_permission_result filter fires when check_permissions() is
+         * called directly (not via execute()).
+         *
+         * @ticket 64989
+         */
+        public function test_permission_result_filter_fires_on_direct_check_permissions_call() {
+                $args = array_merge(
+                        self::$test_ability_properties,
+                        array(
+                                'permission_callback' => static function (): bool {
+                                        return true;
+                                },
+                        )
+                );
+
+                $filter = static function () {
+                        return false;
+                };
+
+                add_filter( 'wp_ability_permission_result', $filter );
+
+                $ability = new WP_Ability( self::$test_ability_name, $args );
+                $result  = $ability->check_permissions();
+
+                remove_filter( 'wp_ability_permission_result', $filter );
+
+                $this->assertFalse( $result, 'check_permissions() should return the filtered value when called directly.' );
+        }
+
+        /**
+         * Tests that a non-bool, non-WP_Error return from the wp_ability_permission_result filter is
+         * coerced to false so check_permissions() honors its documented bool|WP_Error return type.
+         *
+         * @ticket 64989
+         */
+        public function test_permission_result_filter_invalid_value_coerced_to_false() {
+                $filter = static function () {
+                        return 'not-a-bool';
+                };
+
+                add_filter( 'wp_ability_permission_result', $filter );
+
+                $ability = new WP_Ability( self::$test_ability_name, self::$test_ability_properties );
+                $result  = $ability->check_permissions();
+
+                remove_filter( 'wp_ability_permission_result', $filter );
+
+                $this->assertFalse( $result, 'Non-bool, non-WP_Error filter return is coerced to false.' );
+        }
+
+        /**
+         * Tests that returning a custom value from wp_pre_execute_ability short-circuits the
+         * pipeline. The pipeline is configured to fail (permission denial) so a real run would
+         * surface a WP_Error; receiving the short-circuit value proves the bypass. Filter args
+         * are verified via args-as-guards on the short-circuit value.
+         *
+         * @ticket 64989
+         */
+        public function test_pre_execute_ability_filter_short_circuits_pipeline() {
+                $args = array_merge(
+                        self::$test_ability_properties,
+                        array(
+                                'input_schema'        => array(
+                                        'type'        => 'integer',
+                                        'description' => 'Test input integer.',
+                                        'required'    => true,
+                                ),
+                                'execute_callback'    => static function (): int {
+                                        return 1;
+                                },
+                                'permission_callback' => static function (): bool {
+                                        return false;
+                                },
+                        )
+                );
+
+                $filter = static function ( $pre, $ability_name, $input, $ability ) {
+                        if ( self::$test_ability_name !== $ability_name || 99 !== $input || ! $ability instanceof WP_Ability ) {
+                                return $pre;
+                        }
+                        return 'short-circuited';
+                };
+
+                add_filter( 'wp_pre_execute_ability', $filter, 10, 4 );
+
+                $ability = new WP_Ability( self::$test_ability_name, $args );
+                $result  = $ability->execute( 99 );
+
+                remove_filter( 'wp_pre_execute_ability', $filter, 10 );
+
+                $this->assertSame( 'short-circuited', $result, 'Short-circuit value bypasses the pipeline; matching args allowed the filter to set it.' );
+        }
+
+        /**
+         * Tests that returning the default value from wp_pre_execute_ability lets the pipeline run.
+         *
+         * @ticket 64989
+         */
+        public function test_pre_execute_ability_filter_default_value_runs_pipeline() {
+                $args = array_merge(
+                        self::$test_ability_properties,
+                        array(
+                                'execute_callback' => static function (): int {
+                                        return 5;
+                                },
+                        )
+                );
+
+                $filter = static function ( $pre ) {
+                        return $pre;
+                };
+
+                add_filter( 'wp_pre_execute_ability', $filter );
+
+                $ability = new WP_Ability( self::$test_ability_name, $args );
+                $result  = $ability->execute();
+
+                remove_filter( 'wp_pre_execute_ability', $filter );
+
+                $this->assertSame( 5, $result, 'Pipeline should run and return the execute_callback value when filter returns the default value.' );
+        }
+
+        /**
+         * Tests that returning null explicitly from wp_pre_execute_ability short-circuits with null.
+         *
+         * @ticket 64989
+         */
+        public function test_pre_execute_ability_filter_null_short_circuits() {
+                $args = array_merge(
+                        self::$test_ability_properties,
+                        array(
+                                'execute_callback'    => static function (): int {
+                                        return 1;
+                                },
+                                'permission_callback' => static function (): bool {
+                                        return false;
+                                },
+                        )
+                );
+
+                $filter = static function () {
+                        return null;
+                };
+
+                add_filter( 'wp_pre_execute_ability', $filter );
+
+                $ability = new WP_Ability( self::$test_ability_name, $args );
+                $result  = $ability->execute();
+
+                remove_filter( 'wp_pre_execute_ability', $filter );
+
+                $this->assertNull( $result, 'Null from filter should be returned as-is and bypass the pipeline.' );
+        }
+
+        /**
+         * Tests that returning a freshly constructed object from wp_pre_execute_ability is treated as a
+         * short-circuit value, not confused with the WP_Filter_Sentinel default. This proves the
+         * sentinel disambiguates arbitrary object returns.
+         *
+         * @ticket 64989
+         */
+        public function test_pre_execute_ability_filter_object_short_circuits() {
+                $args = array_merge(
+                        self::$test_ability_properties,
+                        array(
+                                'execute_callback'    => static function (): int {
+                                        return 1;
+                                },
+                                'permission_callback' => static function (): bool {
+                                        return false;
+                                },
+                        )
+                );
+
+                $envelope = (object) array( 'status' => 'approval_pending' );
+                $filter   = static function () use ( $envelope ) {
+                        return $envelope;
+                };
+
+                add_filter( 'wp_pre_execute_ability', $filter );
+
+                $ability = new WP_Ability( self::$test_ability_name, $args );
+                $result  = $ability->execute();
+
+                remove_filter( 'wp_pre_execute_ability', $filter );
+
+                $this->assertSame( $envelope, $result, 'Object from filter is returned as-is; WP_Filter_Sentinel keeps it distinct from the default.' );
+        }
+
+        /**
+         * Tests that returning a WP_Error from wp_pre_execute_ability short-circuits with the error.
+         *
+         * @ticket 64989
+         */
+        public function test_pre_execute_ability_filter_wp_error_short_circuits() {
+                $args = array_merge(
+                        self::$test_ability_properties,
+                        array(
+                                'execute_callback' => static function (): int {
+                                        return 1;
+                                },
+                        )
+                );
+
+                $filter = static function () {
+                        return new WP_Error( 'pre_short_circuit', 'Cached error.' );
+                };
+
+                add_filter( 'wp_pre_execute_ability', $filter );
+
+                $ability = new WP_Ability( self::$test_ability_name, $args );
+                $result  = $ability->execute();
+
+                remove_filter( 'wp_pre_execute_ability', $filter );
+
+                $this->assertInstanceOf( WP_Error::class, $result, 'WP_Error from filter should be returned as-is.' );
+                $this->assertSame( 'pre_short_circuit', $result->get_error_code() );
+        }
+
+        /**
+         * Tests that the wp_ability_execute_result filter can transform the result, with all
+         * filter args verified via args-as-guards.
+         *
+         * @ticket 64989
+         */
+        public function test_execute_result_filter_can_transform_result() {
+                $args = array_merge(
+                        self::$test_ability_properties,
+                        array(
+                                'input_schema'     => array(
+                                        'type'        => 'integer',
+                                        'description' => 'Test input integer.',
+                                        'required'    => true,
+                                ),
+                                'execute_callback' => static function ( int $input ): int {
+                                        return $input * 2;
+                                },
+                        )
+                );
+
+                $filter = static function ( $result, $ability_name, $input, $ability ) {
+                        if ( 10 !== $result ) {
+                                return $result;
+                        }
+                        if ( self::$test_ability_name !== $ability_name || 5 !== $input || ! $ability instanceof WP_Ability ) {
+                                return $result;
+                        }
+                        return 99;
+                };
+
+                add_filter( 'wp_ability_execute_result', $filter, 10, 4 );
+
+                $ability = new WP_Ability( self::$test_ability_name, $args );
+                $result  = $ability->execute( 5 );
+
+                remove_filter( 'wp_ability_execute_result', $filter, 10 );
+
+                $this->assertSame( 99, $result, 'Filter received expected args and transformed the result.' );
+        }
+
+        /**
+         * Tests that the wp_ability_execute_result filter can repair an invalid execute result so
+         * output validation passes — also proves the filter runs before output validation.
+         *
+         * @ticket 64989
+         */
+        public function test_execute_result_filter_can_fix_invalid_output() {
+                $args = array_merge(
+                        self::$test_ability_properties,
+                        array(
+                                'execute_callback' => static function (): string {
+                                        return 'not-a-number';
+                                },
+                        )
+                );
+
+                $filter = static function () {
+                        return 42;
+                };
+
+                add_filter( 'wp_ability_execute_result', $filter );
+
+                $ability = new WP_Ability( self::$test_ability_name, $args );
+                $result  = $ability->execute();
+
+                remove_filter( 'wp_ability_execute_result', $filter );
+
+                $this->assertSame( 42, $result, 'Filter should repair invalid output before validation runs.' );
+        }
+
+        /**
+         * Tests that the wp_ability_execute_result filter runs before the wp_after_execute_ability action.
+         *
+         * @ticket 64989
+         */
+        public function test_execute_result_filter_runs_before_after_execute_action() {
+                $order = array();
+
+                $args = array_merge(
+                        self::$test_ability_properties,
+                        array(
+                                'execute_callback' => static function (): int {
+                                        return 1;
+                                },
+                        )
+                );
+
+                $filter = static function ( $result ) use ( &$order ) {
+                        $order[] = 'filter';
+                        return $result;
+                };
+
+                $action = static function () use ( &$order ) {
+                        $order[] = 'action';
+                };
+
+                add_filter( 'wp_ability_execute_result', $filter );
+                add_action( 'wp_after_execute_ability', $action );
+
+                $ability = new WP_Ability( self::$test_ability_name, $args );
+                $ability->execute();
+
+                remove_filter( 'wp_ability_execute_result', $filter );
+                remove_action( 'wp_after_execute_ability', $action );
+
+                $this->assertSame( array( 'filter', 'action' ), $order, 'execute_result filter must run before wp_after_execute_ability action.' );
+        }
+
+        /**
+         * Tests that the wp_ability_execute_result filter receives a WP_Error from the execute
+         * callback and can pass it through (verified via args-as-guards on the WP_Error code).
+         *
+         * @ticket 64989
+         */
+        public function test_execute_result_filter_receives_wp_error_from_do_execute() {
+                $args = array_merge(
+                        self::$test_ability_properties,
+                        array(
+                                'execute_callback' => static function () {
+                                        return new WP_Error( 'execute_failed', 'Something went wrong.' );
+                                },
+                        )
+                );
+
+                $filter = static function ( $result ) {
+                        if ( ! is_wp_error( $result ) || 'execute_failed' !== $result->get_error_code() ) {
+                                return new WP_Error( 'unexpected_input' );
+                        }
+                        return $result;
+                };
+
+                add_filter( 'wp_ability_execute_result', $filter );
+
+                $ability = new WP_Ability( self::$test_ability_name, $args );
+                $result  = $ability->execute();
+
+                remove_filter( 'wp_ability_execute_result', $filter );
+
+                $this->assertInstanceOf( WP_Error::class, $result );
+                $this->assertSame( 'execute_failed', $result->get_error_code(), 'Filter saw the expected WP_Error and passed it through.' );
+        }
 }

trunk/tests/phpunit/tests/rest-api/wpRestAbilitiesV1RunController.php

@@ -904 +904 @@
 
         /**
+         * Tests that a normalization filter error defaults to a 400 REST response.
+         *
+         * @ticket 64989
+         */
+        public function test_normalize_input_filter_error_defaults_to_bad_request_status(): void {
+                $filter = static function ( $input ) {
+                        return new WP_Error( 'normalize_rejected', 'Rejected input.' );
+                };
+
+                add_filter( 'wp_ability_normalize_input', $filter );
+
+                $request = new WP_REST_Request( 'POST', '/wp-abilities/v1/abilities/test/calculator/run' );
+                $request->set_header( 'Content-Type', 'application/json' );
+                $request->set_body(
+                        wp_json_encode(
+                                array(
+                                        'input' => array(
+                                                'a' => 5,
+                                                'b' => 3,
+                                        ),
+                                )
+                        )
+                );
+
+                $response = $this->server->dispatch( $request );
+
+                remove_filter( 'wp_ability_normalize_input', $filter );
+
+                $this->assertSame( 400, $response->get_status() );
+                $data = $response->get_data();
+                $this->assertSame( 'normalize_rejected', $data['code'] );
+                $this->assertSame( 'Rejected input.', $data['message'] );
+        }
+
+        /**
+         * Tests that a normalization filter error with custom status keeps that status.
+         *
+         * @ticket 64989
+         */
+        public function test_normalize_input_filter_error_preserves_custom_status(): void {
+                $filter = static function ( $input ) {
+                        return new WP_Error(
+                                'normalize_unprocessable',
+                                'Input cannot be normalized.',
+                                array( 'status' => 422 )
+                        );
+                };
+
+                add_filter( 'wp_ability_normalize_input', $filter );
+
+                $request = new WP_REST_Request( 'POST', '/wp-abilities/v1/abilities/test/calculator/run' );
+                $request->set_header( 'Content-Type', 'application/json' );
+                $request->set_body(
+                        wp_json_encode(
+                                array(
+                                        'input' => array(
+                                                'a' => 5,
+                                                'b' => 3,
+                                        ),
+                                )
+                        )
+                );
+
+                $response = $this->server->dispatch( $request );
+
+                remove_filter( 'wp_ability_normalize_input', $filter );
+
+                $this->assertSame( 422, $response->get_status() );
+                $data = $response->get_data();
+                $this->assertSame( 'normalize_unprocessable', $data['code'] );
+                $this->assertSame( 'Input cannot be normalized.', $data['message'] );
+        }
+
+        /**
          * Test ability without annotations defaults to POST method.
          *