Changeset 62397

Timestamp:

05/21/2026 07:56:31 AM (45 hours 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.
      *