Add a `core/terms-query` ability (taxonomies, categories, tags)

[whyisjake]

Split out from #40, as requested there on 2026-07-16.

What problem does this address?

The 7.2 roadmap names taxonomies among the read-only resources to cover. Agents that draft or classify content today have no ability-level way to learn which categories and tags exist, so they either guess names or fall back to REST. #40 proposed four narrow abilities (find-categories, get-category, find-tags, get-tag); the read/manage direction since adopted argues for one.

Proposal

• Name: core/terms-query
• Category: content
• Input: taxonomy (required for listing; any public taxonomy or a taxonomy with show_in_rest), id (single term), search, parent, hide_empty, include/exclude, slug, post (terms attached to a post), per_page, page, orderby, order. Returns total and total_pages.
• Output per item: id, taxonomy, name, slug, description, parent, count, link, and registered show_in_rest meta.
• Permission: mirror WP_REST_Terms_Controller: public taxonomies readable by anyone allowed to read the site; non-public taxonomies require the taxonomy's assign_terms/manage_terms capability as the REST controller does.
• Annotations: readonly: true, idempotent: true, destructive: false.

A companion core/read-taxonomies (the list of registered taxonomies with labels, hierarchy, and which post types they apply to) is small and probably belongs in the same PR, since an agent needs it to know what to pass as taxonomy. Suggest deciding in review whether that is one ability with a mode or two.

Out of scope: creating, assigning, or deleting terms (core/manage-terms, separate issue).

Acceptance

• Tests for public vs non-public taxonomy access, hierarchical listing with parent, terms-for-a-post, pagination totals, show_in_rest meta only.
• Abilities Explorer and MCP Adapter exposure verified.
• WordPress Core Abilities #40 checklist updated.

Path to core

Prototype here; Trac ticket after the shape settles, following #64606 and #64657.

[muneeb-ashraf]

I'd like to take this one, and I'll start now. Plan, following the core/users-query / core/content-query pattern and the naming from #1002:

• Name: core/terms-query (no deprecated alias, since core/read-terms never shipped).
• Modes: a single term by id, or by taxonomy + slug, or a paginated collection for one taxonomy filtered by search, parent, hide_empty, include, post, with orderby/order, fields, page/per_page, returning total and total_pages.
• Permissions: mirror WP_REST_Terms_Controller: only taxonomies with show_in_rest, the post filter requires being able to read that post, and an authenticated user is required like the sibling query abilities.
• Registration: gated behind the Custom Abilities experiment like Users_Query and Content_Query, with integration tests for the cases in the acceptance list.

@jorgefilipecosta does core/terms-query match the naming you want? And would you prefer the taxonomy list as a separate core/taxonomies-query follow-up rather than in this PR? Happy to adjust either way.

[gziolo]

I’ve updated the title and description to reflect yesterday’s Core AI chat and the direction @jorgefilipecosta shared in the draft proposal. We’re aligning the names of read-only abilities that query collections around core/$collection-query, so this ability becomes core/terms-query.

And would you prefer the taxonomy list as a separate core/taxonomies-query follow-up rather than in this PR?

This isn't strictly needed to start, since you can define the list of available taxonomies in the input and output schema.

[muneeb-ashraf]

Thanks @gziolo, that matches what I built. #1084 registers core/terms-query and pins the available taxonomies as an enum in the input schema, so I left core/taxonomies-query out. It is ready for review whenever you or @jorgefilipecosta have time.

[gziolo]

I see that @jorgefilipecosta is also working on the same task in #1099, so let's converge on a single approach. I used Claude to get a quick overview on where both overlap and differ:

Most of the work is the same: three input modes (by id, by taxonomy + slug, or a collection), the same output shape, and query logic copied from WP_REST_Terms_Controller.

The main difference is which taxonomies the ability exposes:

• Add core/terms-query ability #1084 exposes every taxonomy with show_in_rest. For taxonomies that are not public, it also requires the assign_terms capability.
• Add core/terms-query ability #1099 exposes only taxonomies that opt in with show_in_abilities. On a default site, that means category and post_tag. This is the same model core/content-query uses for post types.

Smaller differences:

• Add core/terms-query ability #1084 returns term meta. Add core/terms-query ability #1099 does not.
• Add core/terms-query ability #1099 supports exclude. Add core/terms-query ability #1084 does not.
• Add core/terms-query ability #1099 returns more specific errors for the post filter, for example an invalid post ID.
• Add core/terms-query ability #1099 has more tests, including an e2e spec and tests for the show_in_abilities marking.

Based on the feedback on core/content-query (WordPress/wordpress-develop#12195 (comment)) on show_in_abiltiies:

Is there a reason not to default to the value of $show_in_rest for this?

I recommend you combine the two approaches and adjust the exposure by making sure show_in_abilties when is set takes precedence, otherwise it falls back to show_in_rest.

The part covering meta and exclude is an open question. If it isn't covered in core/content-query then we can tackle meta later as another set of PRs.

[gziolo]

Correction to my previous comment: falling back to show_in_rest is not safe, so show_in_abilities must be an explicit opt-in.

I verified it with the settings abilities from #764. With the fallback, the number of exposed settings grew from 18 to 66, including the connector API keys (connectors_ai_*_api_key). Core masks these keys only when preparing the /wp/v2/settings REST response. Abilities skip that step, so core/settings-get returned raw API keys.

The same risk applies to other object types. show_in_rest means the data is safe to expose through REST, together with all its filters and callbacks. Abilities don't run them, so plugin authors who opted into REST didn't opt into this.

For #1084 and #1099, let's keep the show_in_abilities model from #1099, the same one core/content-query uses. Term meta, if we add it later, should require its own opt-in, too.

This also answers the question raised in WordPress/wordpress-develop#12195 (comment).