Prompt template extension points

includes/Abilities/Comment_Moderation/Comment_Analysis.php

@@ -239,6 +239,17 @@ private function analyze_comment( string $content, string $author ) {
 			$content
 		);
 
+		/**
+		 * Filters the assembled user prompt for comment analysis.
+		 *
+		 * @since x.x.x
+		 *
+		 * @param string $prompt  The assembled prompt string.
+		 * @param string $content The comment content.
+		 * @param string $author  The comment author name.
+		 */
+		$prompt = (string) apply_filters( "wpai_{$this->get_ability_slug()}_prompt", $prompt, $content, $author );
+
 		$prompt_builder = $this->get_prompt_builder( $prompt );
 
 		if ( is_wp_error( $prompt_builder ) ) {
@@ -278,6 +289,20 @@ private function get_prompt_builder( string $prompt ) {
 			->using_model_preference( ...get_preferred_models_for_text_generation() )
 			->as_json_response( $this->response_schema() );
 
+		/**
+		 * Filters the configured prompt builder for comment analysis.
+		 *
+		 * Runs before text-generation support is verified. This ability configures
+		 * structured JSON output, so extend the builder rather than replacing it,
+		 * and always return a WP_AI_Client_Prompt_Builder.
+		 *
+		 * @since x.x.x
+		 *
+		 * @param \WP_AI_Client_Prompt_Builder $prompt_builder The configured prompt builder.
+		 * @param string                       $prompt         The user prompt string.
+		 */
+		$prompt_builder = apply_filters( "wpai_{$this->get_ability_slug()}_prompt_builder", $prompt_builder, $prompt );
+
 		return $this->ensure_text_generation_supported(
 			$prompt_builder,
 			esc_html__( 'Comment analysis failed. Please ensure you have a connected provider that supports text generation.', 'ai' )

includes/Abilities/Content_Classification/Content_Classification.php

@@ -406,6 +406,21 @@ private function get_prompt_builder( string $prompt ) {
 
 		$prompt_builder = $this->set_provider_model_preference( $prompt_builder, Content_Classification_Experiment::class );
 
+		/**
+		 * Filters the configured prompt builder for content classification.
+		 *
+		 * Runs after the model preference is applied and before text-generation
+		 * support is verified. This ability configures structured JSON output, so
+		 * extend the builder rather than replacing it, and always return a
+		 * WP_AI_Client_Prompt_Builder.
+		 *
+		 * @since x.x.x
+		 *
+		 * @param \WP_AI_Client_Prompt_Builder $prompt_builder The configured prompt builder.
+		 * @param string                       $prompt         The user prompt string.
+		 */
+		$prompt_builder = apply_filters( "wpai_{$this->get_ability_slug()}_prompt_builder", $prompt_builder, $prompt );
+
 		return $this->ensure_text_generation_supported(
 			$prompt_builder,
 			esc_html__( 'Term generation failed. Please ensure you have a connected provider that supports text generation.', 'ai' )

includes/Abilities/Content_Resizing/Content_Resizing.php

@@ -207,6 +207,16 @@ protected function meta(): array {
 	 * @return string|\WP_Error The resized content, or a WP_Error if there was an error.
 	 */
 	protected function generate_resized_content( string $prompt, string $action = self::ACTION_DEFAULT ) {
+		/**
+		 * Filters the assembled user prompt for content resizing.
+		 *
+		 * @since x.x.x
+		 *
+		 * @param string $prompt The assembled prompt string.
+		 * @param string $action The resizing action being performed.
+		 */
+		$prompt = (string) apply_filters( "wpai_{$this->get_ability_slug()}_prompt", $prompt, $action );
+
 		$builder = $this->get_prompt_builder( $prompt, $action );
 		if ( is_wp_error( $builder ) ) {
 			return $builder;
@@ -233,6 +243,21 @@ private function get_prompt_builder( string $prompt, string $action = self::ACTI
 
 		$prompt_builder = $this->set_provider_model_preference( $prompt_builder, Content_Resizing_Experiment::class );
 
+		/**
+		 * Filters the configured prompt builder for content resizing.
+		 *
+		 * Runs after the model preference is applied and before text-generation
+		 * support is verified. Extend the builder rather than replacing it, and
+		 * always return a WP_AI_Client_Prompt_Builder.
+		 *
+		 * @since x.x.x
+		 *
+		 * @param \WP_AI_Client_Prompt_Builder $prompt_builder The configured prompt builder.
+		 * @param string                       $prompt         The user prompt string.
+		 * @param string                       $action         The resizing action being performed.
+		 */
+		$prompt_builder = apply_filters( "wpai_{$this->get_ability_slug()}_prompt_builder", $prompt_builder, $prompt, $action );
+
 		return $this->ensure_text_generation_supported(
 			$prompt_builder,
 			esc_html__( 'Content resizing failed. Please ensure you have a connected provider that supports text generation.', 'ai' )

includes/Abilities/Editorial_Notes/Editorial_Notes.php

@@ -301,6 +301,17 @@ protected function generate_review(
 	) {
 		$prompt = $this->create_prompt( $block_type, $block_content, $context, $existing_notes, $review_types );
 
+		/**
+		 * Filters the assembled user prompt for editorial notes (block review).
+		 *
+		 * @since x.x.x
+		 *
+		 * @param string       $prompt       The assembled prompt string.
+		 * @param string       $block_type   The block type identifier.
+		 * @param list<string> $review_types The review types being performed.
+		 */
+		$prompt = (string) apply_filters( "wpai_{$this->get_ability_slug()}_prompt", $prompt, $block_type, $review_types );
+
 		$prompt_builder = $this->get_prompt_builder( $prompt, $block_type );
 
 		if ( is_wp_error( $prompt_builder ) ) {
@@ -376,6 +387,22 @@ private function get_prompt_builder( string $prompt, string $block_type ) {
 
 		$prompt_builder = $this->set_provider_model_preference( $prompt_builder, Editorial_Notes_Experiment::class );
 
+		/**
+		 * Filters the configured prompt builder for editorial notes (block review).
+		 *
+		 * Runs after the model preference is applied and before text-generation
+		 * support is verified. This ability configures structured JSON output, so
+		 * extend the builder rather than replacing it, and always return a
+		 * WP_AI_Client_Prompt_Builder.
+		 *
+		 * @since x.x.x
+		 *
+		 * @param \WP_AI_Client_Prompt_Builder $prompt_builder The configured prompt builder.
+		 * @param string                       $prompt         The user prompt string.
+		 * @param string                       $block_type     The block type identifier.
+		 */
+		$prompt_builder = apply_filters( "wpai_{$this->get_ability_slug()}_prompt_builder", $prompt_builder, $prompt, $block_type );
+
 		return $this->ensure_text_generation_supported(
 			$prompt_builder,
 			esc_html__( 'Editorial notes generation failed. Please ensure you have a connected provider that supports text generation.', 'ai' )

includes/Abilities/Editorial_Updates/Editorial_Updates.php

@@ -215,7 +215,19 @@ protected function generate_refinement(
 		array $notes,
 		string $context
 	) {
-		$prompt         = $this->create_prompt( $block_type, $block_content, $notes, $context );
+		$prompt = $this->create_prompt( $block_type, $block_content, $notes, $context );
+
+		/**
+		 * Filters the assembled user prompt for editorial updates (block refinement).
+		 *
+		 * @since x.x.x
+		 *
+		 * @param string       $prompt     The assembled prompt string.
+		 * @param string       $block_type The block type identifier.
+		 * @param list<string> $notes      The editorial feedback notes being applied.
+		 */
+		$prompt = (string) apply_filters( "wpai_{$this->get_ability_slug()}_prompt", $prompt, $block_type, $notes );
+
 		$prompt_builder = $this->get_prompt_builder( $prompt );
 
 		if ( is_wp_error( $prompt_builder ) ) {
@@ -249,6 +261,20 @@ private function get_prompt_builder( string $prompt ) {
 
 		$prompt_builder = $this->set_provider_model_preference( $prompt_builder, Editorial_Updates_Experiment::class );
 
+		/**
+		 * Filters the configured prompt builder for editorial updates (block refinement).
+		 *
+		 * Runs after the model preference is applied and before text-generation
+		 * support is verified. Extend the builder rather than replacing it, and
+		 * always return a WP_AI_Client_Prompt_Builder.
+		 *
+		 * @since x.x.x
+		 *
+		 * @param \WP_AI_Client_Prompt_Builder $prompt_builder The configured prompt builder.
+		 * @param string                       $prompt         The user prompt string.
+		 */
+		$prompt_builder = apply_filters( "wpai_{$this->get_ability_slug()}_prompt_builder", $prompt_builder, $prompt );
+
 		return $this->ensure_text_generation_supported(
 			$prompt_builder,
 			esc_html__( 'Refinement generation failed. Please ensure you have a connected provider that supports text generation.', 'ai' )

includes/Abilities/Excerpt_Generation/Excerpt_Generation.php

@@ -233,6 +233,16 @@ static function ( $key, $value ) {
 			$content .= "\n\n<additional-context>" . $context . '</additional-context>';
 		}
 
+		/**
+		 * Filters the assembled user prompt for excerpt generation.
+		 *
+		 * @since x.x.x
+		 *
+		 * @param string                       $content The assembled prompt string (content and context tags).
+		 * @param string|array<string, string> $context The additional context.
+		 */
+		$content = (string) apply_filters( "wpai_{$this->get_ability_slug()}_prompt", $content, $context );
+
 		$prompt_builder = $this->get_prompt_builder( $content );
 
 		if ( is_wp_error( $prompt_builder ) ) {
@@ -258,6 +268,20 @@ private function get_prompt_builder( string $prompt ) {
 
 		$prompt_builder = $this->set_provider_model_preference( $prompt_builder, Excerpt_Generation_Experiment::class );
 
+		/**
+		 * Filters the configured prompt builder for excerpt generation.
+		 *
+		 * Runs after the model preference is applied and before text-generation
+		 * support is verified. Extend the builder (temperature, model, etc.) rather
+		 * than replacing it, and always return a WP_AI_Client_Prompt_Builder.
+		 *
+		 * @since x.x.x
+		 *
+		 * @param \WP_AI_Client_Prompt_Builder $prompt_builder The configured prompt builder.
+		 * @param string                       $prompt         The user prompt string.
+		 */
+		$prompt_builder = apply_filters( "wpai_{$this->get_ability_slug()}_prompt_builder", $prompt_builder, $prompt );
+
 		return $this->ensure_text_generation_supported(
 			$prompt_builder,
 			esc_html__( 'Excerpt generation failed. Please ensure you have a connected provider that supports text generation.', 'ai' )

includes/Abilities/Image/Alt_Text_Generation.php

@@ -226,7 +226,20 @@ protected function get_image_reference( array $args ) {
 	 * @return string|\WP_Error The generated alt text or WP_Error on failure.
 	 */
 	protected function generate_alt_text( array $image_reference, string $context = '', string $image_meta = '' ) {
-		$prompt_builder = $this->get_prompt_builder( $this->build_prompt( $context, $image_meta ), $image_reference['reference'] );
+		$prompt = $this->build_prompt( $context, $image_meta );
+
+		/**
+		 * Filters the assembled user prompt for alt text generation.
+		 *
+		 * @since x.x.x
+		 *
+		 * @param string $prompt     The assembled prompt string.
+		 * @param string $context    Optional context about the image.
+		 * @param string $image_meta Optional metadata about how the image block is used.
+		 */
+		$prompt = (string) apply_filters( "wpai_{$this->get_ability_slug()}_prompt", $prompt, $context, $image_meta );
+
+		$prompt_builder = $this->get_prompt_builder( $prompt, $image_reference['reference'] );
 
 		if ( is_wp_error( $prompt_builder ) ) {
 			return $prompt_builder;
@@ -414,6 +427,22 @@ private function get_prompt_builder( string $prompt, string $reference ) {
 
 		$prompt_builder = $this->set_provider_model_preference( $prompt_builder, Alt_Text_Generation_Experiment::class, get_preferred_vision_models() );
 
+		/**
+		 * Filters the configured prompt builder for alt text generation.
+		 *
+		 * Runs after the model preference is applied and before text-generation
+		 * support is verified. The builder already has the reference image attached;
+		 * extend it rather than replacing it, and always return a
+		 * WP_AI_Client_Prompt_Builder.
+		 *
+		 * @since x.x.x
+		 *
+		 * @param \WP_AI_Client_Prompt_Builder $prompt_builder The configured prompt builder.
+		 * @param string                       $prompt         The user prompt string.
+		 * @param string                       $reference      The reference image data URI.
+		 */
+		$prompt_builder = apply_filters( "wpai_{$this->get_ability_slug()}_prompt_builder", $prompt_builder, $prompt, $reference );
+
 		return $this->ensure_text_generation_supported(
 			$prompt_builder,
 			esc_html__( 'Alt text generation failed. Please ensure you have a connected provider that supports both text generation and vision capabilities.', 'ai' )

includes/Abilities/Image/Generate_Image.php

@@ -184,6 +184,19 @@ protected function meta(): array {
 	 * @return array{data: string, provider_metadata: array<string, string>, model_metadata: array<string, string>}|\WP_Error The generated image data, or a WP_Error on failure.
 	 */
 	protected function generate_image( string $prompt, ?string $reference_image = null ) { // phpcs:ignore Generic.NamingConventions.ConstructorName.OldStyle
+		/**
+		 * Filters the user prompt for image generation.
+		 *
+		 * Note: this is the image generation prompt itself, not post content.
+		 * Editorial guidelines (when enabled) are appended after this filter runs.
+		 *
+		 * @since x.x.x
+		 *
+		 * @param string      $prompt          The image generation prompt.
+		 * @param string|null $reference_image Optional base64-encoded reference image for edits.
+		 */
+		$prompt = (string) apply_filters( "wpai_{$this->get_ability_slug()}_prompt", $prompt, $reference_image );
+
 		$prompt_builder = $this->get_prompt_builder( $prompt, $reference_image );
 
 		if ( is_wp_error( $prompt_builder ) ) {
@@ -281,6 +294,21 @@ private function get_prompt_builder( string $prompt, ?string $reference_image =
 			$error_message = esc_html__( 'Image refinement failed. Please ensure you have a connected provider that supports image refinement, not just image generation.', 'ai' );
 		}
 
+		/**
+		 * Filters the configured prompt builder for image generation.
+		 *
+		 * Runs after the model preference and reference image (if any) are applied
+		 * and before image-generation support is verified. Extend the builder rather
+		 * than replacing it, and always return a WP_AI_Client_Prompt_Builder.
+		 *
+		 * @since x.x.x
+		 *
+		 * @param \WP_AI_Client_Prompt_Builder $prompt_builder  The configured prompt builder.
+		 * @param string                       $prompt          The image generation prompt (with guidelines).
+		 * @param string|null                  $reference_image Optional base64-encoded reference image.
+		 */
+		$prompt_builder = apply_filters( "wpai_{$this->get_ability_slug()}_prompt_builder", $prompt_builder, $prompt, $reference_image );
+
 		return $this->ensure_image_generation_supported( $prompt_builder, $error_message );
 	}
 }

includes/Abilities/Image/Generate_Image_Prompt.php

@@ -250,6 +250,17 @@ static function ( $key, $value ) {
 			$content .= "\n\n<style>" . $style . '</style>';
 		}
 
+		/**
+		 * Filters the assembled user prompt for image prompt generation.
+		 *
+		 * @since x.x.x
+		 *
+		 * @param string                       $content The assembled prompt string (content, context, style tags).
+		 * @param string|array<string, string> $context The additional context.
+		 * @param string                       $style   The style instructions.
+		 */
+		$content = (string) apply_filters( "wpai_{$this->get_ability_slug()}_prompt", $content, $context, $style );
+
 		$prompt_builder = $this->get_prompt_builder( $content );
 
 		if ( is_wp_error( $prompt_builder ) ) {
@@ -274,6 +285,20 @@ private function get_prompt_builder( string $prompt ) {
 			->using_temperature( 0.9 )
 			->using_model_preference( ...get_preferred_models_for_text_generation() );
 
+		/**
+		 * Filters the configured prompt builder for image prompt generation.
+		 *
+		 * Runs after the model preference is applied and before text-generation
+		 * support is verified. Extend the builder rather than replacing it, and
+		 * always return a WP_AI_Client_Prompt_Builder.
+		 *
+		 * @since x.x.x
+		 *
+		 * @param \WP_AI_Client_Prompt_Builder $prompt_builder The configured prompt builder.
+		 * @param string                       $prompt         The user prompt string.
+		 */
+		$prompt_builder = apply_filters( "wpai_{$this->get_ability_slug()}_prompt_builder", $prompt_builder, $prompt );
+
 		return $this->ensure_text_generation_supported(
 			$prompt_builder,
 			esc_html__( 'Image prompt generation failed. Please ensure you have a connected provider that supports text generation.', 'ai' )

includes/Abilities/Meta_Description/Meta_Description.php

@@ -312,6 +312,20 @@ private function get_prompt_builder( string $prompt ) {
 
 		$prompt_builder = $this->set_provider_model_preference( $prompt_builder, Meta_Description_Experiment::class );
 
+		/**
+		 * Filters the configured prompt builder for meta description generation.
+		 *
+		 * Runs after the temperature and model preference are applied and before
+		 * text-generation support is verified. Extend the builder rather than
+		 * replacing it, and always return a WP_AI_Client_Prompt_Builder.
+		 *
+		 * @since x.x.x
+		 *
+		 * @param \WP_AI_Client_Prompt_Builder $prompt_builder The configured prompt builder.
+		 * @param string                       $prompt         The user prompt string.
+		 */
+		$prompt_builder = apply_filters( "wpai_{$this->get_ability_slug()}_prompt_builder", $prompt_builder, $prompt );
+
 		return $this->ensure_text_generation_supported(
 			$prompt_builder,
 			esc_html__( 'Meta description generation failed. Please ensure you have a connected provider that supports text generation.', 'ai' )