Abilities API: Add a core/content-query ability

[jorgefilipecosta]

Part of WordPress/ai#40.

This PR adds the read-only core/content-query ability to core. It ports the ability from the AI plugin (WordPress/ai#739, WordPress/ai#1002, and WordPress/ai#1025), with the shape from jorgefilipecosta#93.

This PR implements the following changes:

• Adds the core/content-query ability in a new content category.
• Adds a show_in_abilities post type argument. Only post types that set it to true can be queried; post and page do.
• The input is { where, fields, pagination }, with no top-level oneOf or anyOf, which some AI providers reject. where.type is required, and the optional ids, slugs, status, author_slug, and parent filters combine with AND.
• The output is always { items, pagination: { total, total_pages } }, newest posts first, 10 per page by default, or 100 with ids or slugs.
• The ability requires a logged-in user, and permissions follow the REST API posts endpoint: posts the user cannot read are left out, and raw fields are only returned for posts the user can edit. As in REST, pagination.total can count posts left out of items.

Querying the posts of an author, two per page:

await wp.apiFetch( {
	path: wp.url.addQueryArgs( '/wp-abilities/v1/abilities/core/content-query/run', {
		input: {
			where: { type: 'post', author_slug: 'jane' },
			pagination: { per_page: 2 },
		},
	} ),
} );

{
	"items": [
		{
			"id": 57,
			"type": "post",
			"status": "publish",
			"date": { "local": "2026-10-10T09:00:00+00:00", "gmt": "2026-10-10T09:00:00+00:00" },
			"slug": "release-notes",
			"title": { "rendered": "Release notes" }
		},
		{
			"id": 56,
			"type": "post",
			"status": "publish",
			"date": { "local": "2026-10-05T09:00:00+00:00", "gmt": "2026-10-05T09:00:00+00:00" },
			"slug": "our-roadmap",
			"title": { "rendered": "Our roadmap" }
		}
	],
	"pagination": { "total": 3, "total_pages": 2 }
}

Querying pages by slug, with some fields. With ids or slugs, every status the user may query is included, so an administrator also gets the draft page:

await wp.apiFetch( {
	path: wp.url.addQueryArgs( '/wp-abilities/v1/abilities/core/content-query/run', {
		input: {
			where: { type: 'page', slugs: [ 'about', 'contact' ] },
			fields: [ 'status', 'title', 'link' ],
		},
	} ),
} );

{
	"items": [
		{
			"id": 59,
			"status": "draft",
			"link": "http://localhost:8918/?page_id=59",
			"title": { "raw": "Contact", "rendered": "Contact" }
		},
		{
			"id": 58,
			"status": "publish",
			"link": "http://localhost:8918/about/",
			"title": { "raw": "About", "rendered": "About" }
		}
	],
	"pagination": { "total": 2, "total_pages": 1 }
}

The same query as a subscriber only returns the published page, without the raw title:

{
	"items": [
		{
			"id": 58,
			"status": "publish",
			"link": "http://localhost:8918/about/",
			"title": { "rendered": "About" }
		}
	],
	"pagination": { "total": 1, "total_pages": 1 }
}

Trac ticket: https://core.trac.wordpress.org/ticket/66268

Testing

Verify unit tests are passing:

npm run test:php -- --group 66268

Open the post editor and run the examples above in the browser console, using an author and page slugs from your site.

Use of AI Tools

AI assistance: Yes. Claude Code was used to sync this PR with the plugin, apply the review feedback, test it, and draft this description; I reviewed the changes.

---

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

[github-actions]

Hi there! 👋

Thank you for your contribution to WordPress! 💖

It looks like this is your first pull request to wordpress-develop. Here are a few things to be aware of that may help you out!

No one monitors this repository for new pull requests. Pull requests must be attached to a Trac ticket to be considered for inclusion in WordPress Core. To attach a pull request to a Trac ticket, please include the ticket's full URL in your pull request description.

Pull requests are never merged on GitHub. The WordPress codebase continues to be managed through the SVN repository that this GitHub repository mirrors. Please feel free to open pull requests to work on any contribution you are making.

More information about how GitHub pull requests can be used to contribute to WordPress can be found in the Core Handbook.

Please include automated tests. Including tests in your pull request is one way to help your patch be considered faster. To learn about WordPress' test suites, visit the Automated Testing page in the handbook.

If you have not had a chance, please review the Contribute with Code page in the WordPress Core Handbook.

The Developer Hub also documents the various coding standards that are followed:

• PHP Coding Standards
• CSS Coding Standards
• HTML Coding Standards
• JavaScript Coding Standards
• Accessibility Coding Standards
• Inline Documentation Standards

Thank you,
The WordPress Project

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props jorgefilipecosta, peterwilsoncc, gziolo, ugyensupport.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[gziolo]

Thanks @jorgefilipecosta! I went through this against the companion plugin PR WordPress/ai#739. The Core class is a truthful representation of what is proposed there. After accounting for the expected adaptations (no namespace, no ai text domain, and dropping the plugin-only init(), category self-registration, and override blocks), there is no divergent logic. The new show_in_abilities post type arg is clean and mirrors the settings approach, the wiring and category registration look right, and CI is green.

On sequencing: the AI plugin PR should go first. Since #739 is still open, we are matching a proposal, not merged code, so this PR should wait on that merge to avoid the two drifting.

One small thing to add: the Trac ticket reference is missing. There should already be one for this ability, like the sibling PRs have (users links #64657 and settings links #64605). Could you add it to the description and the test @ticket tags?

[peterwilsoncc]

I've added a few notes inline. LMK if this is no longer the canonical URL as there are a few linked to the ticket.

[gziolo]

In addition to addressing the feedback from @peterwilsoncc, we need to sync the latest fixes applied in the AI plugin. Most importantly:

• Rename the content and users abilities and remove ai/get-post-details ai#1002

[gziolo]

The previous review feedback is addressed, and local verification passed for the focused tests and the broader Abilities API suite on both single-site and multisite.

Two follow-ups remain before approval:

• Please remove open_world and its accompanying comment/assertion, since WordPress Core does not support this annotation.

• The rendering helpers do not fully restore loop globals when there is no surrounding post. To reproduce:

  1. Start with an empty global WP_Query and no $GLOBALS['post'].
  2. Execute core/content-query for a published post with fields: ['content_rendered'].
  3. Inspect $GLOBALS['pages']: it still contains the rendered post’s content.

  setup_postdata() populates these globals, but wp_reset_postdata() cannot restore them because the main query has no post. The excerpt helper uses the same cleanup pattern. Please preserve and restore the affected globals, including their previously unset state, and add regression coverage.

For awareness, this PR incorporates the author_slug contract from the still-open WordPress/ai#1025. Keep the implementations synchronized as that PR settles.

[gziolo]

I did a full pass over the class, in addition to my earlier comment. Permission handling looks solid. Every lookup is checked, raw fields need edit access, and filters that cannot be applied fail closed. I left a few inline notes:

• Before approval: limit show_in_abilities to a boolean for now, and remove the core/users-query references (or land that ability first).
• Question: the network-wide author lookup on multisite.
• Docs and minor: the future ability name, an explicit limit in the slug lookup, and the @param alignment.

[jorgefilipecosta]

I tested core/content-query with real models using the snippet below. Add your API keys to the constants at the top, then visit /?ai-content-test as an administrator or editor, or /?ai-content-test=openai to test a single provider.

Snippet

<?php
/*
 * API keys for Settings > Connectors. Core reads these constants ahead of a key
 * saved on that screen; leave one empty to use the saved key instead.
 */
define( 'ANTHROPIC_API_KEY', '' );
define( 'OPENAI_API_KEY', '' );
define( 'GOOGLE_API_KEY', '' );

/**
 * Asks a provider a question that it answers by calling `core/content-query`.
 *
 * @param string $question The question.
 * @param string $provider The AI Client provider ID, such as 'anthropic', 'openai' or 'google'.
 * @param array  $calls    Receives the arguments of each ability call.
 * @param string $model    Receives the ID of the model that answered.
 * @return string|WP_Error The answer, or the error.
 */
function my_plugin_ai_content_answer( string $question, string $provider, array &$calls = array(), string &$model = '' ) {
	$resolver = new WP_AI_Client_Ability_Function_Resolver( 'core/content-query' );
	$messages = array(
		new \WordPress\AiClient\Messages\DTO\UserMessage(
			array( new \WordPress\AiClient\Messages\DTO\MessagePart( $question ) )
		),
	);

	for ( $i = 0; $i < 5; $i++ ) {
		$result = wp_ai_client_prompt( $messages )
			->using_provider( $provider )
			->using_system_instruction( 'You are a WordPress assistant. Use abilities when needed.' )
			->using_abilities( 'core/content-query' )
			->generate_text_result();

		if ( is_wp_error( $result ) ) {
			return $result;
		}
		$model = $result->getModelMetadata()->getId();

		// OpenAI returns each function call as its own candidate, so keep them all, not just toMessage().
		$model_messages = array();
		foreach ( $result->getCandidates() as $candidate ) {
			$model_messages[] = $candidate->getMessage();
		}
		array_push( $messages, ...$model_messages );

		$call_messages = array_filter( $model_messages, array( $resolver, 'has_ability_calls' ) );
		if ( ! $call_messages ) {
			return $result->toText();
		}

		foreach ( $call_messages as $message ) {
			foreach ( $message->getParts() as $part ) {
				if ( $part->getFunctionCall() ) {
					$calls[] = $part->getFunctionCall()->getArgs();
				}
			}
			$messages[] = $resolver->execute_abilities( $message );
		}
	}

	return new WP_Error( 'ai_tool_loop_limit', 'Too many ability rounds.' );
}

// Demo: visit /?ai-content-test as an administrator or editor, or /?ai-content-test=google for one provider.
add_action(
	'template_redirect',
	function () {
		if ( ! isset( $_GET['ai-content-test'] ) || ! current_user_can( 'edit_others_posts' ) ) {
			return;
		}

		$providers = array( 'anthropic', 'openai', 'google' );
		if ( in_array( $_GET['ai-content-test'], $providers, true ) ) {
			$providers = array( $_GET['ai-content-test'] );
		}

		$prompts = array(
			'How many published posts does this site have, and which are the three most recent? Give the title, author and date of each one.',
			'Which posts are drafts or pending review? Give the title, status and author of each one.',
			'Which pages have a parent page? Give the title of each one and of its parent.',
			'What does the post with the slug hello-world say?',
		);

		set_time_limit( 600 );
		header( 'Content-Type: text/plain; charset=utf-8' );

		foreach ( $providers as $provider ) {
			if ( ! \WordPress\AiClient\AiClient::defaultRegistry()->isProviderConfigured( $provider ) ) {
				echo "## {$provider}: skipped, no API key or provider plugin\n\n";
				continue;
			}

			foreach ( $prompts as $prompt ) {
				$calls  = array();
				$model  = '';
				$answer = my_plugin_ai_content_answer( $prompt, $provider, $calls, $model );

				echo "## {$provider}", $model ? " ({$model})" : '', ": {$prompt}\n";
				foreach ( $calls as $args ) {
					echo 'core/content-query ', wp_json_encode( $args ), "\n";
				}
				echo is_wp_error( $answer ) ? 'Error: ' . $answer->get_error_message() : $answer, "\n\n";
			}
		}
		exit;
	}
);

To test Gemini, the Google provider needs WordPress/ai-provider-for-google#45 applied. Version 1.2.0 sends the schema in a format that rejects uniqueItems, so every request fails with a 400 before the model can call the ability. With a free tier key, the default gemini-4-argon model has no quota, so for my Gemini runs I added ->using_model_preference( 'gemini-3.8-flash' ).

All the answers were correct. The site had 17 published posts, three drafts, two posts pending review and two child pages. The provider plugins came from WordPress.org: Anthropic 1.0.5, OpenAI 1.2.0 and Google 1.2.0 with the PR above.

Prompt	Claude claude-sonnet-5-5	GPT gpt-6.1-sol	Gemini gemini-3.8-flash
How many published posts does this site have, and which are the three most recent?	✅	✅	✅
Which posts are drafts or pending review?	✅	✅	✅
Which pages have a parent page?	✅	✅	✅
What does the post with the slug hello-world say?	✅	✅	✅

Full output

## anthropic (claude-sonnet-5-5): How many published posts does this site have, and which are the three most recent? Give the title, author and date of each one.
core/content-query {"where":{"type":"post","status":["publish"]},"pagination":{"per_page":3,"page":1},"fields":["id","title.rendered","author.name","date"]}
The site has **17 published posts**. These are the three most recent:

| # | Title | Author | Date |
|---|-------|--------|------|
| 1 | Hello world! | admin | 2026-10-15 17:34 |
| 2 | CQ p_admin_pub | admin | 2026-09-01 10:00 |
| 3 | CQ p_author_pub | Ana Author | 2026-08-01 10:00 |

The dates are in site-local time, which is the same as GMT here.

## anthropic (claude-sonnet-5-5): Which posts are drafts or pending review? Give the title, status and author of each one.
core/content-query {"where":{"type":"post","status":["draft","pending"]},"fields":["id","title","status","author"],"pagination":{"per_page":100}}
I found 5 posts that are drafts or pending review:

| Title | Status | Author |
|---|---|---|
| CQ p_author_draft | Draft | Ana Author |
| CQ p_author_pending | Pending | Ana Author |
| CQ p_author2_draft | Draft | Bea Author |
| CQ p_contrib_draft | Draft | cq_contributor |
| CQ p_contrib_pending | Pending | cq_contributor |

I only searched the standard "post" type. Pages and custom post types weren't checked. I can search those too if you'd like.

## anthropic (claude-sonnet-5-5): Which pages have a parent page? Give the title of each one and of its parent.
core/content-query {"where":{"type":"page","status":["publish","future","draft","pending","private"]},"fields":["id","title.rendered","parent","status"],"pagination":{"per_page":100}}
Two pages have a parent page:

| Page | Parent page |
|---|---|
| CQ pg_child_a | CQ pg_parent_a |
| CQ pg_child_b | CQ pg_parent_b |

I checked pages with these statuses: published, scheduled, draft, pending and private. The other four pages are top-level: Privacy Policy (a draft), Sample Page, CQ pg_parent_a and CQ pg_parent_b.

## anthropic (claude-sonnet-5-5): What does the post with the slug hello-world say?
core/content-query {"where":{"type":"post","slugs":["hello-world"]},"fields":["id","title","content","status","date","author.name"]}
The post with the slug `hello-world` is titled **"Hello world!"**. It says:

> Welcome to WordPress. This is your first post. Edit or delete it, then start writing!

This is the default WordPress starter post. Its details:
- **ID:** 1
- **Status:** Published
- **Author:** admin
- **Date:** 2026-10-15

## openai (gpt-6.1-sol): How many published posts does this site have, and which are the three most recent? Give the title, author and date of each one.
core/content-query {"where":{"type":"post","status":["publish"]},"fields":["title.rendered","author.name","date"],"pagination":{"per_page":3,"page":1}}
The site has **17 published posts**. The three most recent are:

| Title | Author | Date |
|---|---|---|
| Hello world! | admin | October 15, 2026 |
| CQ p_admin_pub | admin | September 1, 2026 |
| CQ p_author_pub | Ana Author | August 1, 2026 |

## openai (gpt-6.1-sol): Which posts are drafts or pending review? Give the title, status and author of each one.
core/content-query {"where":{"type":"post","status":["draft","pending"]},"fields":["title","status","author"],"pagination":{"per_page":100}}
| Title | Status | Author |
|---|---|---|
| CQ p_author_draft | Draft | Ana Author |
| CQ p_author_pending | Pending review | Ana Author |
| CQ p_author2_draft | Draft | Bea Author |
| CQ p_contrib_draft | Draft | cq_contributor |
| CQ p_contrib_pending | Pending review | cq_contributor |

**Total:** 3 drafts and 2 pending review.

## openai (gpt-6.1-sol): Which pages have a parent page? Give the title of each one and of its parent.
core/content-query {"where":{"type":"page"},"fields":["title.rendered","parent"],"pagination":{"per_page":100,"page":1}}
| Page | Parent page |
|---|---|
| CQ pg_child_a | CQ pg_parent_a |
| CQ pg_child_b | CQ pg_parent_b |

## openai (gpt-6.1-sol): What does the post with the slug hello-world say?
core/content-query {"where":{"type":"post","slugs":["hello-world"]},"fields":["title.rendered","content.rendered"]}
The post **“Hello world!”** says:

> Welcome to WordPress. This is your first post. Edit or delete it, then start writing!

## google (gemini-3.8-flash): How many published posts does this site have, and which are the three most recent? Give the title, author and date of each one.
core/content-query {"pagination":{"page":1,"per_page":3},"where":{"status":["publish"],"type":"post"},"fields":["id","title","author","date"]}
This site currently has **17** published posts.

The three most recent published posts are:

1. **Hello world!**
   - **Author:** admin
   - **Date:** October 15, 2026, 17:34:14 UTC

2. **CQ p_admin_pub**
   - **Author:** admin
   - **Date:** September 1, 2026, 10:00:00 UTC

3. **CQ p_author_pub**
   - **Author:** Ana Author
   - **Date:** August 1, 2026, 10:00:00 UTC

## google (gemini-3.8-flash): Which posts are drafts or pending review? Give the title, status and author of each one.
core/content-query {"where":{"status":["draft","pending"],"type":"post"},"fields":["id","title.rendered","status","author.name"]}
Here are the posts that are drafts or pending review:

1. **Title:** CQ p_author_draft  
   **Status:** Draft  
   **Author:** Ana Author  

2. **Title:** CQ p_author_pending  
   **Status:** Pending Review  
   **Author:** Ana Author  

3. **Title:** CQ p_author2_draft  
   **Status:** Draft  
   **Author:** Bea Author  

4. **Title:** CQ p_contrib_draft  
   **Status:** Draft  
   **Author:** cq_contributor  

5. **Title:** CQ p_contrib_pending  
   **Status:** Pending Review  
   **Author:** cq_contributor

## google (gemini-3.8-flash): Which pages have a parent page? Give the title of each one and of its parent.
core/content-query {"where":{"type":"page","status":["publish","draft","pending","private","future"]},"fields":["id","title.rendered","parent","status"],"pagination":{"per_page":100}}
core/content-query {"fields":["id","title.rendered","parent","status"],"pagination":{"per_page":100},"where":{"type":"page","status":["cq_showcase","cq_review"]}}
The following pages have a parent page:

1. **Page:** CQ pg_child_a  
   **Parent:** CQ pg_parent_a

2. **Page:** CQ pg_child_b  
   **Parent:** CQ pg_parent_b

## google (gemini-3.8-flash): What does the post with the slug hello-world say?
core/content-query {"fields":["title","content","slug"],"where":{"type":"post","slugs":["hello-world"]}}
The post titled **"Hello world!"** contains the following content:

> "Welcome to WordPress. This is your first post. Edit or delete it, then start writing!"

Tested and drafted with AI assistance (Claude Code).

[gziolo]

This looks ready to commit from my side. Thank you for working through all the iterations.

The input is now always { where, fields, pagination }, and the output is always { items, pagination }. This gives callers a clear and predictable shape. Field selection works well. Every item keeps its id. Raw fields the user cannot see are left out, but the readable post is still returned. Password-protected content stays protected.

The explicit show_in_abilities opt-in, the private callbacks, and the tests for permissions, input normalization, pagination, and restoring the post context address my earlier concerns.

A few small documentation improvements would help callers. These fit well in the schema descriptions:

• List the default fields (id, type, status, date, slug, title.rendered), and clarify that omitting fields or passing fields: [] uses them.
• Explain that requested raw sub-fields are left out when the user cannot edit the post, and that fields the post type does not support are left out too. So a readable item may contain only id. Distinguish this from password-protected posts, where content.rendered and excerpt.rendered are returned as an empty string, and protected tells callers why.
• Document that pagination.page defaults to 1. A page past the end returns an error. The only exception is when the query matches no posts at all: then the response has empty items and zero totals. Note that empty items does not always mean zero totals, because posts the user cannot read are still counted.

None of these need API changes, so they can be done together with the developer documentation. As a separate follow-up, it would be good to add a _doing_it_wrong() notice when a post type with show_in_abilities is registered after the ability.

[jorgefilipecosta]

Thank you for the review @gziolo, the documentation suggestions were applied to the schema descriptions.

[github-actions]

A commit was made that fixes the Trac ticket referenced in the description of this pull request.

SVN changeset: 64388
GitHub commit: 213ecca

This PR will be closed, but please confirm the accuracy of this and reopen if there is more work to be done.