AI Filters

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

Filter	Description
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/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'] = [ 'create_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