WordPress 7.1: políticas e auditoria para Abilities de agentes de IA

No artigo anterior, criamos uma Ability parametrizada que devolve o resumo de um post somente quando o usuário pode editar aquele objeto. O WordPress 7.1 acrescenta uma segunda camada: filtros globais capazes de intervir em todo o ciclo de execução.

Isso permite que um plugin de infraestrutura aplique manutenção, limites, políticas extras de autorização e sanitização sem modificar cada Ability registrada no site. Para agentes de IA, essa separação é valiosa: a função continua pequena, enquanto as regras organizacionais ficam centralizadas.

O WordPress 7.1 tem lançamento programado para 19 de agosto de 2026. Os exemplos deste tutorial foram testados no WordPress 7.1-RC1 e mantêm compatibilidade com o WordPress 7.0.2.

Os quatro filtros novos

O pipeline passa a oferecer quatro pontos de intervenção, nesta ordem:

1. wp_pre_execute_ability: interrompe toda a execução;
2. wp_ability_normalize_input: transforma a entrada antes da validação;
3. wp_ability_permission_result: aplica uma política após a permissão original;
4. wp_ability_execute_result: transforma o resultado antes do schema de saída.

As actions wp_before_execute_ability e wp_after_execute_ability, já existentes, continuam sendo o lugar apropriado para observação e auditoria.

1. Bloqueio emergencial com wp_pre_execute_ability

O primeiro filtro roda antes de normalização, schema e permissão. Ele recebe um valor sentinela de uso interno. Para continuar o pipeline, devolva exatamente $pre.

add_filter( 'wp_pre_execute_ability', 'wp24_pre_execute', 10, 4 );

function wp24_pre_execute( $pre, $ability_name, $input, $ability ) {
    $disabled = (array) get_option( 'wp24_abilities_demo_disabled', array() );

    if ( in_array( $ability_name, $disabled, true ) ) {
        return new WP_Error(
            'wp24_ability_disabled',
            __( 'Esta capacidade foi temporariamente desativada.', 'wp24-abilities-demo' )
        );
    }

    return $pre;
}

Esse mecanismo serve para manutenção, incidentes, aprovação manual ou um circuit breaker. Como ele ignora todo o restante do pipeline, a decisão deve depender apenas de condições estreitas e confiáveis. Não use a entrada bruta para autorizar um objeto aqui.

2. Normalização antes do schema

Clientes HTTP e ferramentas de automação nem sempre preservam tipos com perfeição. O filtro de normalização pode converter um ID numérico recebido como string antes da validação:

add_filter( 'wp_ability_normalize_input', 'wp24_normalize_input', 10, 3 );

function wp24_normalize_input( $input, $ability_name, $ability ) {
    if (
        'wp24/get-post-summary' === $ability_name &&
        is_array( $input ) &&
        isset( $input['post_id'] ) &&
        is_numeric( $input['post_id'] )
    ) {
        $input['post_id'] = (int) $input['post_id'];
    }

    return $input;
}

O valor transformado ainda precisa obedecer ao input_schema. Essa é uma garantia importante: normalização não se torna uma porta para parâmetros não documentados.

O filtro também pode retornar WP_Error. Na REST API, o WordPress 7.1 propaga esse erro e permite definir um status como 429 para rate limiting.

3. Política adicional de autorização

Uma Ability deve continuar tendo sua própria permission_callback. A política global atua depois dela e acrescenta uma exigência organizacional:

add_filter( 'wp_ability_permission_result', 'wp24_permission_policy', 10, 4 );

function wp24_permission_policy( $permission, $ability_name, $input, $ability ) {
    if ( false === $permission || is_wp_error( $permission ) ) {
        return $permission;
    }

    $admin_only = (array) get_option( 'wp24_abilities_demo_admin_only', array() );

    if ( in_array( $ability_name, $admin_only, true ) && ! current_user_can( 'manage_options' ) ) {
        return new WP_Error(
            'wp24_additional_permission_required',
            __( 'Esta capacidade exige acesso de administrador.', 'wp24-abilities-demo' )
        );
    }

    return $permission;
}

A regra mais importante está no início: preserve false e WP_Error. Retornar true sem cuidado pode substituir uma negativa da permissão original e ampliar acesso acidentalmente.

Nos testes, check_permissions() preservou o código interno wp24_additional_permission_required. A execução pública devolveu ability_invalid_permissions, evitando expor detalhes desnecessários ao consumidor.

4. Filtrando o resultado antes da validação

O callback pode receber dados de um serviço interno e devolver metadados que não deveriam sair. O filtro remove esse material antes do output_schema:

add_filter( 'wp_ability_execute_result', 'wp24_filter_result', 10, 4 );

function wp24_filter_result( $result, $ability_name, $input, $ability ) {
    if ( is_array( $result ) ) {
        unset( $result['internal_debug_data'] );
    }

    return $result;
}

Depois do filtro, o resultado passa pela validação de saída. Se você enriquecer, recuperar ou reformatar uma resposta, o novo valor ainda precisa cumprir o contrato registrado pela Ability.

Auditoria sem guardar prompts ou conteúdo

Auditar não significa copiar toda a entrada para um log. Prompts, conteúdo editorial, pedidos e dados pessoais podem ser sensíveis. Registre o mínimo necessário para investigação operacional:

add_action( 'wp_before_execute_ability', 'wp24_start_audit', 10, 2 );
add_action( 'wp_after_execute_ability', 'wp24_finish_audit', 10, 3 );

function wp24_start_audit( $ability_name, $input ): void {
    $GLOBALS['wp24_audit'][ $ability_name ] = microtime( true );
}

function wp24_finish_audit( $ability_name, $input, $result ): void {
    $started = $GLOBALS['wp24_audit'][ $ability_name ] ?? microtime( true );

    error_log( wp_json_encode( array(
        'event'       => 'wp24_ability_executed',
        'ability'     => $ability_name,
        'user_id'     => get_current_user_id(),
        'success'     => ! is_wp_error( $result ),
        'error_code'  => is_wp_error( $result ) ? $result->get_error_code() : null,
        'duration_ms' => round( ( microtime( true ) - $started ) * 1000, 2 ),
        'timestamp'   => gmdate( 'c' ),
    ) ) );
}

Em produção, envie esse registro para um logger com retenção, rotação e acesso controlado. O exemplo usa error_log() apenas para manter o plugin didático independente de serviços externos.

O que foi validado em Docker

A versão 0.3.0 do plugin-base foi executada com PHP 8.3 em dois ambientes isolados.

No WordPress 7.1-RC1, foram aprovados:

• coerção de post_id numérico;
• bloqueio emergencial com wp24_ability_disabled;
• política adicional e negativa pública segura;
• remoção de dados internos antes do schema;
• registro de ability, usuário, resultado, duração e timestamp.

No WordPress 7.0.2, as duas Abilities continuaram funcionando. Registrar callbacks para filtros que ainda não existem é inofensivo; as actions de auditoria existentes continuam ativas.

Checklist para uma camada de governança

1. mantenha a permission_callback em cada Ability;
2. nunca transforme uma negativa em true por padrão;
3. use o bloqueio antecipado somente para decisões estreitas;
4. valide novamente qualquer entrada ou saída transformada;
5. não grave prompts ou conteúdo integral por conveniência;
6. associe o log a usuário, Ability, tempo e resultado;
7. defina retenção e acesso para os registros;
8. teste a política com papéis diferentes;
9. mantenha um caminho de desativação emergencial;
10. trate filtros globais como infraestrutura de segurança.

Plugin completo

O pacote wp24-abilities-demo-0.3.0.zip reúne as duas Abilities dos artigos anteriores e a nova camada de políticas e auditoria. Ele é uma base educacional: adapte armazenamento, interface administrativa e observabilidade às exigências do seu projeto.

No próximo artigo, vamos expor essas capacidades a uma ferramenta compatível com agentes, mantendo autenticação, descoberta e execução sob controle do WordPress.

Fontes oficiais

• Novos filtros do ciclo de execução no WordPress 7.1
• Abilities API Handbook
• Endpoints REST da Abilities API
• Calendário oficial do WordPress 7.1