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

Directive System

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.

datamachine_directives

Centralized filter for directive registration.

Hook usage:

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

Return shape: array of directive configurations.

Directive configuration:

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

Implementation example:

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

Built-in directives are listed in AI Directives System with current priority and mode assignments.

datamachine_agent_mode_{slug}

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

Hook usage (one filter per mode slug):

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

Parameters:

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

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

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

Implementation example:

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

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

datamachine_tools

Single Data Machine registry for AI tools. ToolManager reads this registry, ToolSourceRegistry composes source pools, and ToolPolicyResolver::resolve() assembles the final request-visible tool set for active modes.

Hook usage:

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

Return shape: associative array keyed by tool ID.

Tool definition:

[
    '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
    'ability'          => 'my-plugin/search',   // optional Ability link for permissions/categories
    'access_level'     => 'admin',              // fallback when no ability is linked
]

Implementation example:

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;
} );

Use pipeline mode only when a static registry tool is useful inside an automated pipeline AI step. Add requires_opt_in => true for powerful tools that should stay hidden by default but can be explicitly granted through enabled_tools. Chat affordances and tools that duplicate engine-level validation should stay chat-only; pipeline AI steps already receive adjacent handler tools plus pipeline/flow memory directives.

Earlier per-mode tool filters were consolidated into datamachine_tools in v0.68.0 (PR #1130). Register current tools through the unified registry and declare modes on the tool definition.

datamachine_tool_configured

Earlier per-mode tool filters were consolidated into datamachine_tools in v0.68.0 (PR #1130). Register current tools through the unified registry and declare modes on the tool definition.

Earlier per-mode tool filters were consolidated into datamachine_tools in v0.68.0 (PR #1130). Register current tools through the unified registry and declare modes on the tool definition.

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

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

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

Hook usage:

Parameters:

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 visibility (whether the AI sees the tool in this request) is resolved by ToolPolicyResolver::resolve(). ToolManager::is_tool_available() is a source-level check for global enablement and configuration. The earlier public enablement filter is not part of the current runtime path.

Handler Registration

Return: bool — Whether the tool is configured.

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 — Data Machine registry, source-level availability, and handler tool expansion
• Tool Execution — Tool dispatch, action policy, and approval staging
• Core Filters — Handler registration filters and OAuth service discovery