Hook Registration & Execution

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_quality/hooks/manager.py
• src/flext_quality/hooks/base.py
• src/flext_quality/hooks/__init__.py
• src/flext_quality/utilities.py
• tests/unit/test_hooks.py
• tests/unit/test_api.py
• src/flext_quality/mcp/tools.py

Hook Registration & Execution defines the lifecycle and orchestration of interceptors within the FLEXT Quality platform. This system allows developers to register custom logic that executes during specific quality events, such as tool usage or process termination. It provides a structured mechanism to validate, modify, or block actions based on input data and configured matchers.

The system relies on a central manager to coordinate hook execution across different entry points, including the Command Line Interface (CLI), Model Context Protocol (MCP) tools, and automated analysis workflows. By utilizing standardized JSON inputs and outputs, the hook system ensures compatibility across various toolchains in the FLEXT ecosystem.

Core Architecture

The hook system consists of three primary components: the base hook definition, the lifecycle manager, and utility handlers.

Hook Components

Component	Class/Module	Responsibility
Hook Base	FlextQualityBaseHook	Defines the interface for execution and pattern-based filtering.
Hook Manager	FlextQualityHookManager	Manages hook registration, grouping by event, and sequential execution.
Hook Utilities	FlextQualityUtilities.Quality	Handles JSON parsing, output formatting, and stdin processing.

Sources: src/flext_quality/hooks/base.py, src/flext_quality/hooks/manager.py, src/flext_quality/utilities.py

Class Relationship

The following diagram illustrates the relationship between the hook base class and the management layer.

Hook Execution Logic

The execution of hooks follows a sequential chain managed by the FlextQualityHookManager. When an event occurs, the manager retrieves all hooks registered for that specific HookEvent.

Execution Flow

1. The manager receives an event string and input data.
2. It validates the event against c.Quality.HookEvent.
3. For each hook registered to the event, the manager calls should_run().
4. If should_run() returns true (based on matcher glob patterns), the manager executes the hook logic.
5. If a hook returns a failure result or sets the continue flag to false, the execution chain halts immediately.

Pattern Matching

Hooks use glob patterns defined in the matcher attribute to filter inputs. The should_run method specifically checks the tool_name field within the input_data. If no matcher is provided, the hook runs for every instance of the event.

Sources: src/flext_quality/hooks/base.py:32-43, tests/unit/test_hooks.py:81-100

Integration Points

The hook system is exposed through multiple interfaces to support different orchestration environments.

MCP Tool Integration

The FlextQualityMcpTools class provides a manual execution path via the execute_hook tool. This allows external agents or servers to trigger hook logic by providing an event name and JSON payload.

Sources: src/flext_quality/mcp/tools.py:76-88

Standard Input Processing

For CLI and external process integration, the system can process hooks via sys.stdin.

1. read_stdin() captures the raw input.
2. parse_hook_input() converts the raw string into a JsonMapping.
3. The resulting data is passed to the FlextQualityHookManager.

Sources: src/flext_quality/utilities.py:161-182, tests/unit/test_api.py:175-207

JSON Communication Format

Hook communication relies on a specific JSON structure for both input and output to ensure interoperability.

Hook Output Structure:

{
  "continue": true,
  "systemMessage": "Optional message for the orchestrator",
  "blockedReason": "Explanation if continue is false"
}

Sources: src/flext_quality/utilities.py:117-136, tests/unit/test_api.py:126-155

Summary

Hook Registration & Execution provides a critical control layer for the FLEXT Quality platform. By combining a flexible FlextQualityBaseHook with a centralized FlextQualityHookManager, the system enables conditional execution and orchestration of quality checks. It supports diverse execution environments through MCP tools and standard I/O processing while maintaining strict enforcement of the execution chain through the continue flag mechanism.

Sources: src/flext_quality/hooks/manager.py, src/flext_quality/mcp/tools.py