Add `core/settings-update` ability by jorgefilipecosta · Pull Request #764 · WordPress/ai

jorgefilipecosta · 2026-06-23T14:52:43Z

What?

Adds core/settings-update next to core/settings-get.

Why?

Agents can read the settings exposed to abilities but not change them. This lets them update those settings under the same rules as the REST API.

How?

The ability lives in includes/Abilities/Settings/Settings.php, behind the Custom Abilities experiment with core/settings-get. Neither ability registers when no setting is exposed.
Input: a map of setting name to its new value, for any setting core/settings-get reads except url and email (siteurl and admin_email), which stay read-only for now: a wrong site URL makes wp-admin unreachable, and wp-admin only changes the admin email after the new address confirms it. As in the settings endpoint, only users who can manage privacy options, network admins on multisite, can change page_for_privacy_policy. For a setting with a registered default (among core settings, language, use_smilies and posts_per_page), null resets the setting to that default. Unknown names, empty input and null for a setting without a default are rejected; the endpoint deletes such a setting, leaving it without a value.
It mirrors WP_REST_Settings_Controller::update_item(). Every value is sanitized against its schema before any is written; the REST API does this through each setting's sanitize_callback arg option, while the Abilities API only validates. Settings are written in registration order, objects reject undeclared properties, and null is refused with settings_invalid_stored_value while the stored value fails validation. Unlike the endpoint, which checks stored values while writing and keeps the settings it already wrote, every check runs before any write, so an error leaves every setting unchanged. A value that sanitizing makes invalid is refused with settings_invalid_param, where the endpoint stores it: %ab@x.co in a setting with the email format would be stored as @x.co. null resets a boolean stored as false, which WordPress saves as ''; the endpoint refuses that reset. The endpoint's null only deletes the stored value, while the ability then stores the registered default: core registers its settings, and so their defaults, only in REST and abilities requests, so after the endpoint's { "posts_per_page": null } other requests read false and show one post per page. For the same reason, a value that matches the registered default is stored when no value is, where update_option() stores nothing. A setting with no stored value reads as its registered default, so null can reset it, where the endpoint refuses that null with a 500. The endpoint also skips a privacy policy page change from users who cannot manage privacy options, while the ability refuses the update with settings_cannot_manage_privacy_options. Error codes use settings_ in place of rest_, and the REST-only filters do not run.
Output: only the updated settings, as core/settings-get reads them after the update; the endpoint answers with the whole settings object, which core/settings-get still returns. core/settings-get now sanitizes each stored value against its schema and leaves out a value the schema rejects, before or after sanitizing, instead of failing for every setting; the endpoint answers null for such a value. Without that, a setting without a default that the endpoint reset to null, such as default_ping_status, would fail core/settings-get for every setting. A boolean stored as false, which WordPress saves as '', reads as false.
Names: as in core (Abilities API: Add a core/settings-get ability wordpress-develop#12141), a setting flagged with show_in_abilities => true takes its name and schema from show_in_rest, and every core setting is flagged with true. Both abilities, and the deprecated core/read-settings alias, now use the settings endpoint's names: title, description, url, email, timezone, language and page_for_privacy_policy replace blogname, blogdescription, siteurl, admin_email, timezone_string, WPLANG and wp_page_for_privacy_policy. url gets the endpoint's uri format, which the abilities client accepts since WordPress 7.1.
It is destructive but not idempotent, so it stays on POST: the DELETE method cannot carry null.
The tests port the settings endpoint's update tests under their core names. A throwaway harness ran 23 updates through both the endpoint and the ability on WordPress 7.1.2. The results match, apart from the differences above.

Testing Instructions

Enable the Custom Abilities experiment.
Run core/settings-update with { "title": "New name" }, then with { "posts_per_page": null }. The first call returns { "title": "New name" }, the second { "posts_per_page": 10 }. { "url": "https://example.com" } and { "default_ping_status": null } are rejected.
npm run test:php -- --filter 'SettingsTest|Gated_AbilitiesTest|Custom_AbilitiesTest'
npm run test:e2e -- tests/e2e/specs/abilities/core-settings-update.spec.js

Changelog Entry

Added - New core/settings-update ability that mirrors the REST API settings endpoint.
Changed - core/settings-get and its deprecated core/read-settings alias now name settings as the REST API settings endpoint does, for example title instead of blogname and url instead of siteurl.
Changed - The Settings_Get gated ability class is now Settings, so code that removes it with the wpai_gated_abilities filter needs the new class name.

AI disclosure: the latest fixes come from an AI-assisted code review of the core port, and were drafted with AI assistance (Claude Code) and reviewed by me.

github-actions · 2026-06-23T14:52:53Z

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.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: jorgefilipecosta <jorgefilipecosta@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: dkotter <dkotter@git.wordpress.org>
Co-authored-by: jeffpaul <jeffpaul@git.wordpress.org>

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

github-actions · 2026-06-23T14:57:24Z

✅ WordPress Plugin Check Report

✅ Status: Passed

📊 Report

All checks passed! No errors or warnings found.

🤖 Generated by WordPress Plugin Check Action • Learn more about Plugin Check

codecov · 2026-06-23T14:58:41Z

Codecov Report

❌ Patch coverage is 99.47090% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 82.28%. Comparing base (19d5670) to head (245764a).
⚠️ Report is 13 commits behind head on develop.

Files with missing lines	Patch %	Lines
includes/Abilities/Settings/Settings.php	99.41%	1 Missing ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##             develop     #764      +/-   ##
=============================================
+ Coverage      81.67%   82.28%   +0.60%     
- Complexity      3103     3407     +304     
=============================================
  Files            129      136       +7     
  Lines          12334    13288     +954     
=============================================
+ Hits           10074    10934     +860     
- Misses          2260     2354      +94

Flag	Coverage Δ
unit	`82.28% <99.47%> (+0.60%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

jeffpaul · 2026-07-16T16:59:10Z

I'd like to see #863 land alongside this specific PR (and any others that aren't explicitly read abilities), to help ensure folks enabling these sorts of abilities are doing so knowingly.

Port the core change in WordPress/wordpress-develop#12141 (30742fc248). The input schema validates `fields` with rest_is_array(), which also accepts a comma-separated string, but execute_get_settings() replaced anything other than an array with an empty one, so a PHP caller that passed 'title,posts_per_page' got every setting back. REST requests were not affected, because the run endpoint converts the input to the schema types first. Normalize the list with rest_sanitize_array().

Port the core docs change in WordPress/wordpress-develop#12141 (4620fbcaed). An array replaces the show_in_rest name and schema entirely, so a setting that only sets a name for abilities also drops its REST schema, such as an email format. Say so where Show_In_Abilities describes the values it can set.

Port the core test in WordPress/wordpress-develop#12141 (f5cf4af483). show_in_abilities => true reuses the show_in_rest name and schema, so guard the opt-in rule next to it: a setting shown in the REST API without show_in_abilities is not exposed.

… exposed Port the core docs change in WordPress/wordpress-develop#12141 (89ca6e70f4). The abilities registry can initialize while init is still running, for example when a plugin uses it at an earlier init priority, so the docs were wrong to call registering a setting on init reliable. Say that settings registered after the abilities register are not exposed, and drop the comments that only repeat that the exposed settings are computed once.

Port the core change in WordPress/wordpress-develop#12141 (a4e7ea0948). It does not: it reads values with a plain get_option() call, without the rest_pre_get_setting filter or the schema default that /wp/v2/settings passes, and it leaves out a value the endpoint answers with null. Describe what the ability does instead.

Port the core change in WordPress/wordpress-develop#12141 (f454c10bbf). PHP turns a numeric array key, such as a setting named 123, into an integer. The fields enum then listed the integer, so input validation rejected the name passed as a string, and the strict in_array() check did not match it either. Cast the names to strings, and test with a numeric setting name. core/settings-update builds its answer from the keys of the settings it wrote, which are integers for such names, so pass them to core/settings-get as strings too. Without that, the string check would leave a numeric setting out of the answer.

Port the core change in WordPress/wordpress-develop#12141 (a999491872). Stored values were only validated before sanitizing, but rest_sanitize_value_from_schema() can turn a valid value into one the schema rejects. For example, sanitize_text_field() turns the email %ab@x.co into @x.co. Output validation then failed the whole call instead of leaving out that one setting. Validate the sanitized value too.

@SInCE

The comment above the schema checks in execute_get_settings() had a sentence about core/settings-update resets, the only difference from core's method besides the @SInCE lines, and it carried no Plugin: marker. Drop it.

null deletes the stored value. Among the core settings only language, use_smilies and posts_per_page register a default, so for the others a null left the setting without a value: the site title, the date format or the front page setting read as false, and both abilities then left the setting out. The description promised that the setting falls back to its default. Add null to the type, and to any enum, only for a setting with a registered default, so the input schema shows which settings can be reset and the Abilities API rejects a null for the others. The settings endpoint accepts null for every setting.

rest_sanitize_value_from_schema() can turn a valid value into one the schema rejects: sanitize_text_field() turns the email %ab@x.co into @x.co. The ability stored that value, and since core/settings-get now leaves out such values, the answer was {} with nothing to say why. Validate the sanitized value too, and refuse it with settings_invalid_param before any setting is written. The settings endpoint stores it.

WordPress stores false as '', which the boolean schema rejects. A null for a boolean turned off in an earlier request was then refused with settings_invalid_stored_value, although core/settings-get reads the setting as false, so a client never sees an invalid value to protect. Read the stored value the way core/settings-get does before checking it. The settings endpoint refuses that null, since it answers null for the setting.

A show_in_abilities (or show_in_rest) name that is not a string, such as an array, was used as an array key, which is a fatal error while the abilities register, so one bad registration broke every ability. develop checked the name with is_string(). Use the option name instead, as for an empty name. Core's WP_Abilities_Settings, and the settings endpoint, fail the same way, so this is marked as a plugin difference.

WP_UnitTestCase backs up $wp_actions once and restores it after every test, so the two tests that set the rest_api_init count no longer save and restore it themselves.

rest_validate_value_from_schema() ignores an empty enum, so a setting whose schema has `enum => array()`, such as a list computed when the setting registers that came out empty, accepts any value through core/settings-get and the settings endpoint. For a setting with a default, update_value_schema() appended null to it, which left `enum => array( null )`, so the ability refused every value but null. Add null only to an enum that is not empty.

…alue The comment said the check keeps a client that sends a response back from deleting values that fail validation. core/settings-get never answers null, it leaves such values out, so that only holds for answers from the settings endpoint, whose setting names the abilities now share. Say so, and note that a repeated null can be refused once the stored value is gone, since get_option() is passed false as the default.

The input schema alone kept url and email read-only and refused null for a setting without a default. A wp_ability_validate_input filter can skip that validation, and then {"url": ...} wrote siteurl before the output check failed, a null deleted default_ping_status, and an input with only unknown names answered with every setting, since an empty `fields` filter means all of them. Skip read-only settings in the write loop, check each sanitized value against the input schema rather than the setting's schema, and answer with no setting when nothing was written.

A null deleted the stored value, as the settings endpoint does, so the setting fell back to its registered default. That default only applies in requests that register the setting, and core registers its own settings only in REST and abilities requests. After {"posts_per_page": null}, the ability answered 10 while other requests read false and showed one post per page, and sending 10 again stored nothing, since update_option() skips a value that matches the registered default when no value is stored. Delete the stored value, then store the registered default, so every request reads it. The delete comes first because sanitize_option() turns a language that is not installed, such as the en_US default, into the current value. Also store a value that update_option() skips that way.

The stored-value check read the value with false as the default, as the settings endpoint does, so a setting with no stored value failed validation and null was refused with a 500: language on a site without a WPLANG row, or posts_per_page after the endpoint's null deleted it. Since null now stores the default, that refusal blocked the very reset that repairs such a setting. Read a missing value as the registered default, as core/settings-get and the endpoint answer it. A stored value that fails validation is still refused.

The fallback after update_option() added the value whenever no value was stored afterwards, including a value update_option() refused on purpose: a pre_update_option_{$option} filter that turned the update back was bypassed, and a language that is not installed left a new en_US row where the settings endpoint stores nothing. Add the value only when it matches the registered default, the one case where update_option() stores nothing because no value is stored.

…ema. `execute()` validates the whole output against the output schema, so one stored value that does not match its setting's schema (for example an out-of-enum `default_ping_status`) made the entire call fail. Validate each cast value against its schema and leave out only the ones it rejects, as WordPress/ai#764 does for the plugin's copy of the ability.

With nothing exposed, the ability could not return anything and its schemas would carry empty enums and properties. Compute the exposed settings in register() and register nothing when there are none, as WordPress/ai#764 does for the plugin's copy of the ability.

The AI plugin named the write ability `core/settings-update` (see WordPress/ai#764), so update the comments that still called it `core/manage-settings`.

An empty PHP array is encoded as `[]`, so an ability whose output schema describes an object, such as `core/settings-get` when its filters match no setting, answered with a JSON array. When the output schema describes an object, send an empty object instead, so the response matches the schema. PHP callers still receive the plain array. Suggested in WordPress/ai#764, where `core/settings-update` worked around it with an `(object)` cast.

"Settings Get" follows the ability name but does not read as a label. The other core abilities start with the verb, as in "Get Site Information". The AI plugin uses the same label (see WordPress/ai#764).

- Name the class members like the users and content classes: register_settings_get(), register_settings_update(), execute_settings_get(), execute_settings_update(), get_settings_get_input_schema(), get_settings_get_output_schema(), check_permission(), and a CATEGORY constant. - Label the abilities `Get Settings` and `Update Settings`, verb first like the other core abilities, and say in the get description that it requires an authenticated user who can manage options. - Reject duplicate names in the `fields` filter with `uniqueItems`. - Explain in the class docblock why the settings abilities live in a dedicated class instead of closures in wp_register_core_abilities(), as the users and content classes do.

gziolo · 2026-10-09T07:52:39Z

+				'settings_invalid_param',
+				/* translators: %s: List of invalid parameters. */
+				sprintf( __( 'Invalid parameter(s): %s', 'ai' ), implode( ', ', $invalid_params ) ),
+				array( 'status' => 400 )


Could we include the invalid setting names in the error data? We already collect them in $invalid_params; exposing them would let callers identify what to fix without parsing a translated message.

Only init() and register() stay public. The permission and execute callbacks of `core/settings-get` and `core/settings-update` are now private methods, registered through closures defined in the class, so callers run the abilities through the Abilities API, such as `wp_get_ability( 'core/settings-get' )->execute()`, which validates the input and checks permissions first. The test that calls the update callback directly now captures it from the registration arguments, through the `wp_register_ability_args` filter, so register_ability() no longer returns the instance. Ported from WordPress/wordpress-develop#12141.

- Map each invalid setting to its messages under `params`, and to its error under `details`, in the `settings_invalid_param` error data, as the REST API's `rest_invalid_param` errors do, so callers can tell which setting failed without parsing the translated message. - Pass the setting name to the schema validation, so its messages name the setting.

On WordPress 7.1, `public` also enables REST exposure, and the default MCP adapter only exposes public abilities, so `core/settings-update` stayed hidden there while `core/settings-get` was exposed. Keep `show_in_rest` for WordPress 7.0, which does not read `public`, as the content and user write abilities do. Also type READ_ONLY_OPTIONS as list<string>.

jeffpaul added this to the 1.2.0 milestone Jun 23, 2026

jeffpaul added this to WordPress AI Roadmap Jun 23, 2026

github-project-automation Bot moved this to Triage in WordPress AI Roadmap Jun 23, 2026

jeffpaul moved this from Triage to Needs review in WordPress AI Roadmap Jun 23, 2026

jeffpaul requested review from dkotter and gziolo June 23, 2026 14:59

gziolo reviewed Jun 24, 2026

View reviewed changes

Comment thread includes/Abilities/Settings/Settings.php Outdated

gziolo reviewed Jun 24, 2026

View reviewed changes

Comment thread includes/Abilities/Settings/Settings.php Outdated

gziolo reviewed Jun 24, 2026

View reviewed changes

Comment thread includes/Abilities/Settings/Settings.php Outdated

gziolo reviewed Jun 24, 2026

View reviewed changes

Comment thread includes/Abilities/Settings/Settings.php Outdated

dkotter assigned jorgefilipecosta Jun 24, 2026

jeffpaul modified the milestones: 1.2.0, 1.3.0 Jul 13, 2026

jeffpaul moved this from Needs review to In progress in WordPress AI Roadmap Jul 13, 2026

jeffpaul mentioned this pull request Jul 13, 2026

New Experiment: Abilities toggle #863

Closed

1 task done

gziolo mentioned this pull request Jul 17, 2026

WordPress Core Abilities #40

Open

6 of 7 tasks

jeffpaul mentioned this pull request Aug 10, 2026

Release version 1.3.0 #924

Closed

48 tasks done

dkotter modified the milestones: 1.3.0, 1.4.0 Aug 12, 2026

jeffpaul modified the milestones: 1.4.0, 1.5.0 Sep 17, 2026

jorgefilipecosta force-pushed the add/core-manage-settings-ability branch from 68d5383 to 1174887 Compare October 1, 2026 17:00

jorgefilipecosta requested a review from a team as a code owner October 1, 2026 17:00

jorgefilipecosta changed the title ~~Add a core/manage-settings ability~~ Add a core/settings-update ability Oct 1, 2026

jorgefilipecosta changed the base branch from develop to update/rename-settings-get-ability October 1, 2026 17:01

jorgefilipecosta added 19 commits October 7, 2026 16:45

Keep the core/settings-get comment identical to core

67e3398

The comment above the schema checks in execute_get_settings() had a sentence about core/settings-update resets, the only difference from core's method besides the @SInCE lines, and it carried no Plugin: marker. Drop it.

Drop the rest_api_init restore from the settings registration tests

e22f37a

WP_UnitTestCase backs up $wp_actions once and restores it after every test, so the two tests that set the rest_api_init count no longer save and restore it themselves.

gziolo changed the title ~~Add a core/settings-update ability~~ Add core/settings-update ability Oct 8, 2026

gziolo reviewed Oct 9, 2026

View reviewed changes

jorgefilipecosta added 3 commits October 9, 2026 12:50

Navigation Menu

Repository navigation

Add `core/settings-update` ability - #764

Add `core/settings-update` ability#764
jorgefilipecosta wants to merge 57 commits into
developfrom
add/core-manage-settings-ability

jorgefilipecosta commented Jun 23, 2026 •

edited by github-actions Bot

Loading

Uh oh!

github-actions Bot commented Jun 23, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 23, 2026

Uh oh!

codecov Bot commented Jun 23, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jeffpaul commented Jul 16, 2026

Uh oh!

gziolo Oct 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

jorgefilipecosta commented Jun 23, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Changelog Entry

Uh oh!

github-actions Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 23, 2026

✅ WordPress Plugin Check Report

📊 Report

Uh oh!

codecov Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jeffpaul commented Jul 16, 2026

Uh oh!

gziolo Oct 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jorgefilipecosta commented Jun 23, 2026 •

edited by github-actions Bot

Loading

github-actions Bot commented Jun 23, 2026 •

edited

Loading

codecov Bot commented Jun 23, 2026 •

edited

Loading