Reference for the WordPress filters used by the Universal Engine to register directives, tools, and authentication providers, and to validate tool configuration.

Modes vs contexts: prior to v0.71.0 the directive-targeting field was named contexts. It was renamed to modes during the AgentMode refactor (#1130). Both RequestBuilder and PromptBuilder now read modes. Old contexts => registrations are silently ignored and treated as all.

Directive System

Modes vs contexts: prior to v0.71.0 the directive-targeting field was named contexts. It was renamed to modes during the AgentMode refactor (#1130). Both RequestBuilder and PromptBuilder now read modes. Old contexts => registrations are silently ignored and treated as all.

datamachine_directives

Modes vs contexts: prior to v0.71.0 the directive-targeting field was named contexts. It was renamed to modes during the AgentMode refactor (#1130). Both RequestBuilder and PromptBuilder now read modes. Old contexts => registrations are silently ignored and treated as all.

Directives inject system messages and contextual information into AI requests. They self-register via a single unified filter with priority-based ordering and mode targeting.

$directives = apply_filters( 'datamachine_directives', array() );

Centralized filter for directive registration.

Hook usage:

$directive = [
    'class'    => DirectiveClass::class, // implements DirectiveInterface
    'priority' => 25,                    // lower = applied first
    'modes'    => ['all'],               // 'all', or array of modes (chat, pipeline, system)
];

Return shape: array of directive configurations.

add_filter( 'datamachine_directives', function ( $directives ) {
    $directives[] = [
        'class'    => MyCustomDirective::class,
        'priority' => 30,
        'modes'    => ['chat', 'pipeline'],
    ];
    return $directives;
} );

Directive configuration:

datamachine_agent_mode_{slug}

Implementation example:

Built-in directives are listed in AI Directives System with current priority and mode assignments. The earlier GlobalSystemPromptDirective, SiteContextDirective, PipelineCoreDirective, ChatAgentDirective, and SystemAgentDirective classes were removed during the AgentMode refactor — their guidance now lives inline in AgentModeDirective and in agent memory files (SITE.md, SOUL.md, MEMORY.md).

$content = apply_filters( "datamachine_agent_mode_{$mode}", $default_content, $payload );

Per-mode guidance composition hook fired by AgentModeDirective (priority 22).

• $default_content (string) — Built-in guidance for that mode (or empty for unregistered modes).
• $payload (array) — Full request payload (agent_id, user_id, agent_mode, etc.).

Hook usage (one filter per mode slug):

Parameters:

Return: Modified guidance text. Returning an empty string suppresses the directive.

add_filter( 'datamachine_agent_mode_chat', function ( $content, $payload ) {
    if ( empty( $payload['agent_id'] ) ) {
        return $content;
    }
    return $content . "nn## Site-specificnnAlways prefer existing taxonomies before creating new ones.";
}, 10, 2 );

Tool System

Built-in modes: chat, pipeline, system. Extensions can register additional modes (e.g. the editor plugin registers editor to inject diff-workflow instructions).

datamachine_tools

Implementation example:

Tools are registered via a single unified filter. Per-mode tool partitioning is handled inside ToolManager, not by separate registration filters.

$tools = apply_filters( 'datamachine_tools', array() );

Single registry for all AI tools. Used by ToolManager::getRawToolsForMode() to assemble the available tool set for a given execution mode.

Hook usage:

[
    'class'            => 'My\Plugin\Tools\MyTool',
    'method'           => 'handle_tool_call',
    'description'      => 'Clear, AI-readable description.',
    'parameters'       => [
        'query' => [
            'type'        => 'string',
            'required'    => true,
            'description' => 'Search query',
        ],
    ],
    'modes'            => ['chat'],             // which modes can see this tool
    'requires_config'  => true,                 // checked via datamachine_tool_configured
    'category'         => 'search',             // optional grouping
]

Return shape: associative array keyed by tool ID.

add_filter( 'datamachine_tools', function ( $tools ) {
    $tools['my_search'] = [
        'class'           => 'My\Plugin\Tools\MySearch',
        'method'          => 'handle_tool_call',
        'description'     => 'Search the My Plugin index.',
        'parameters'      => [
            'query' => [
                'type'        => 'string',
                'required'    => true,
                'description' => 'Search terms',
            ],
        ],
        'modes'           => ['chat'],
        'requires_config' => false,
    ];
    return $tools;
} );

Tool definition:

The legacy datamachine_global_tools and datamachine_chat_tools filters were consolidated into datamachine_tools in v0.68.0 (PR #1130). The old per-mode filters no longer exist.

datamachine_tool_configured

Implementation example:

The legacy datamachine_global_tools and datamachine_chat_tools filters were consolidated into datamachine_tools in v0.68.0 (PR #1130). The old per-mode filters no longer exist.

$configured = apply_filters( 'datamachine_tool_configured', false, $tool_id );

Use pipeline mode only when a static/global tool is useful inside an automated pipeline AI step. Chat affordances and tools that duplicate engine-level validation should stay chat-only; pipeline AI steps already receive step-scoped handler tools plus pipeline/flow memory directives.

• $configured (bool) — Current configuration status.
• $tool_id (string) — Tool identifier.

The legacy datamachine_global_tools and datamachine_chat_tools filters were consolidated into datamachine_tools in v0.68.0 (PR #1130). The old per-mode filters no longer exist.

Validates that tools requiring external services (API keys, OAuth credentials) are properly configured.

add_filter( 'datamachine_tool_configured', function ( $configured, $tool_id ) {
    if ( $tool_id === 'my_search' ) {
        $settings = get_option( 'my_plugin_settings', array() );
        return ! empty( $settings['api_key'] ) && strlen( $settings['api_key'] ) >= 20;
    }
    return $configured;
}, 10, 2 );

Tool availability (whether the AI sees the tool in this request) is now resolved by ToolManager::is_tool_available(), not by a public filter. The datamachine_tool_enabled filter from earlier versions has been removed in favour of ToolManager‘s direct logic, which combines configuration state, mode membership, and per-step enabled_tools settings.

Handler Registration

Hook usage:

Best Practices

Directive Registration

• Use priority 10–29 for foundational identity / mode guidance.
• Use priority 30–49 for contextual information (memory files, inventory).
• Use priority 50+ for late-stage configuration (workflow visualization, pipeline goals).
• Always declare modes explicitly. Default to ['all'] only when the directive truly applies everywhere.

Tool Registration

• Provide a complete parameters schema — the AI relies on it for argument structure.
• Set requires_config => true only when the tool genuinely needs configuration. Tools that always work (e.g. web_fetch) should leave it false so they don’t get filtered out.
• Declare modes so the tool only appears where it’s useful (e.g. workflow-management tools should be chat-only, not exposed to pipeline AI steps).

Configuration Validation

• Validate the actual usability of credentials, not just their presence (e.g. minimum length, expected prefix).
• Keep validation cheap — datamachine_tool_configured is called repeatedly during tool listing.
• Do not perform live API calls inside the filter; cache results elsewhere if you need to verify connectivity.

Related Documentation

• AI Directives System — Built-in directive list, priorities, modes
• Tool Manager — Tool availability resolution
• Tool Execution — Tool dispatch and result handling
• Core Filters — Handler registration filters and OAuth service discovery