AI Filters

This page documents filters for customizing the AI assistant — who can use it, prompts, models, and request parameters.

Filter	Description
unblock/ai/chat/can_use	Who can use the AI assistant chat
unblock/ai/mcp/can_use	Who can open MCP sessions
unblock/ai/prompts	System prompt parts before assembly
unblock/ai/agents	AI agents configuration
unblock/ai/skills	AI skills configuration
unblock/ai/timeout	AI request timeout
unblock/ai/max_tokens	Maximum tokens for responses
unblock/ai/max_tool_rounds	Maximum agent-loop rounds per chat call
unblock/ai/model_preference	AI model override
unblock/ai/image/model_preference	Image-generation model override

ai/chat/can_use

Filter whether the current user can use the AI assistant chat. Gates the chat REST endpoints and hides the panel from excluded users.

Parameter	Type	Description
$allowed	bool	Whether the current user can use the chat

Default: current_user_can( 'edit_posts' ) — anyone who can open the block editor.

Helper: unbk_ai_chat_can_use()

Example: Restrict the Chat to Editors

add_filter( 'unblock/ai/chat/can_use', fn( $allowed ) => current_user_can( 'edit_others_posts' ) );

note

The filter narrows who gets the chat inside an enabled feature. When the assistant is turned off in the Unblock settings, nobody gets it, whatever the filter returns.

Each tool then follows the capability of the action it persists, exactly like manual editing: update_styles needs css/can_write, update_script needs unfiltered_html, and generate_image needs upload_files. A user missing one of them chats without that tool.

ai/mcp/can_use

Filter whether the current user can open MCP sessions. Gates the MCP REST endpoints, every Unblock ability registered on the Abilities API, and the session control in the chat panel.

Parameter	Type	Description
$allowed	bool	Whether the current user can open MCP sessions

Default: current_user_can( 'manage_options' ) — administrators only.

Helper: unbk_ai_mcp_can_use()

Example: Open MCP Sessions to Editors

add_filter( 'unblock/ai/mcp/can_use', fn( $allowed ) => $allowed || current_user_can( 'edit_others_posts' ) );

Watch out

An MCP session lets an external client drive the editor with the permissions of the user who opened it. Keep it to roles you trust with automation, and remember the MCP Adapter's own transport permission applies on top.

The unblock/update-styles ability additionally requires css/can_write: a user allowed to open MCP sessions but not to write CSS gets every other ability, and the editor drops the CSS of insert-blocks / replace-blocks calls.

ai/prompts

Filter AI system prompt parts before assembly.

apply_filters( 'unblock/ai/prompts', array $parts, string $agent );

Parameter	Type	Description
$parts	string[]	Array of prompt instruction strings
$agent	string	Agent identifier ('builder', 'designer', 'content')

Example: Add Custom Instruction

add_filter( 'unblock/ai/prompts', function( $parts, $agent ) {

    $parts[] = 'Use {{ product.price|currency }} for product prices.';

    return $parts;

}, 10, 2 );

Example: Agent-Specific Prompt

add_filter( 'unblock/ai/prompts', function( $parts, $agent ) {

    if ( 'content' === $agent ) {
        $parts[] = 'Always write in British English.';
    }

    return $parts;

}, 10, 2 );

ai/agents

Filter AI agents configuration.

apply_filters( 'unblock/ai/agents', array $agents );

Parameter	Type	Description
$agents	array	Registered agents configuration

Each agent is keyed by its identifier and supports: label, description, icon, role (prompt key for system role), prompts (prompt part keys), tools (tool names).

Built-in agents: builder, designer, content (writer).

Example: Restrict Designer Tools

add_filter( 'unblock/ai/agents', function( $agents ) {

    // Only allow style changes, no attribute updates.
    $agents['designer']['tools'] = [ 'update_styles' ];

    return $agents;

} );

ai/skills

Filter AI skills (slash commands) configuration.

apply_filters( 'unblock/ai/skills', array $skills );

Parameter	Type	Description
$skills	array	Registered skills configuration

Each skill is keyed by its slug and supports: label, description, icon, prompts (prompt part keys), tools (tool names), capability (required capability), server_tool (bool).

Example: Register Custom Skill

add_filter( 'unblock/ai/skills', function( $skills ) {

    $skills['seo-audit'] = [
        'label'       => __( 'SEO audit', 'flavor' ),
        'description' => __( 'Check headings, alt text, and meta tags', 'flavor' ),
        'icon'        => 'search',
        'prompts'     => [ 'skill-seo' ],
        'tools'       => [],
    ];

    return $skills;

} );

Example: Remove a Built-in Skill

add_filter( 'unblock/ai/skills', function( $skills ) {

    unset( $skills['generate-images'] );

    return $skills;

} );

ai/timeout

Filter the AI request timeout.

apply_filters( 'unblock/ai/timeout', int $timeout );

Parameter	Type	Description
$timeout	int	Timeout in seconds. Default: 600

Example: Reduce Timeout

add_filter( 'unblock/ai/timeout', fn( $timeout ) => 120 );

ai/max_tokens

Filter the maximum tokens for AI responses.

apply_filters( 'unblock/ai/max_tokens', int $max_tokens );

Parameter	Type	Description
$max_tokens	int	Maximum token count

Example: Limit Response Length

add_filter( 'unblock/ai/max_tokens', fn( $max_tokens ) => 2048 );

ai/max_tool_rounds

Filter the maximum number of agent-loop rounds per chat call. The AI assistant re-prompts the model after each server-side tool execution (e.g. image generation) until the request is fully resolved or this budget is exhausted. Set to 1 to disable the loop entirely (single round, no continuation).

apply_filters( 'unblock/ai/max_tool_rounds', int $max_rounds );

Parameter	Type	Description
$max_rounds	int	Maximum round count. Default: 5. Minimum: 1

Example: Tighten the budget on rate-limited providers

add_filter( 'unblock/ai/max_tool_rounds', fn() => 3 );

ai/model_preference

Filter the AI model preference. Return a model identifier to override the default.

apply_filters( 'unblock/ai/model_preference', string $model );

Parameter	Type	Description
$model	string	Model identifier

Example: Use a Specific Model

add_filter( 'unblock/ai/model_preference', fn( $model ) => 'claude-sonnet-4-20250514' );

ai/image/model_preference

Filter the model preference for AI image generation. Return a model identifier, or an array of identifiers for ordered fallback. Empty string lets the SDK pick any compatible model.

apply_filters( 'unblock/ai/image/model_preference', string|string[] $model );

Parameter	Type	Description
$model	string | string[]	Model identifier or ordered list. Default: ''

Example: Force Gemini multimodal

add_filter( 'unblock/ai/image/model_preference', fn() => 'gemini-2.5-flash-image' );

Example: Fallback list

add_filter(
    'unblock/ai/image/model_preference',
    fn() => [ 'gemini-2.5-flash-image', 'dall-e-3', 'imagen-4.0-generate-001' ]
);

Next steps

• Data filters — register custom providers and functions
• Actions — plugin lifecycle hooks