pom_theme_update_setting: update one setting
Changes one field of one POM Theme setting — if that field is on the allowlist.
Arguments
| Argument | Required | Meaning |
|---|---|---|
setting |
Yes | The setting key |
field |
Yes | The field within it |
value |
Yes | The new value |
dry_run |
No | Report without writing |
Permissions
Allow POM Theme writes open, plus manage_options — not the edit_theme_options that reading requires.
The allowlist is two fields
Out of the box, exactly two fields are writable:
- the post archive sidebar layout, on the
post_archivesetting; - the post single layout, on the
post_singlesetting.
Everything else returns pom_ai_mcp_theme_field_denied. Colours, typography, header, footer, logos, buttons, spacing — all readable, none writable.
This surprises people, and it is deliberate. A connected client cannot restyle the site by asking.
Custom post type layouts are also accepted
Two dynamic patterns work in addition to the allowlist: the archive sidebar layout and the single sidebar layout for any custom post type, on the cpt_archive and cpt_single settings respectively.
They are accepted only when the post type genuinely exists. A field naming a post type that is not registered is refused like any other.
Extending the allowlist is a site decision
The allowlist passes through the pom_ai_mcp_writable_pom_theme_settings filter, so a site can add entries in the form setting.field. A * in place of a field name matches any single field of that setting.
That is code someone writes and deploys deliberately. It is not something an assistant can arrange, and asking for it is not a workaround for a denial. See Extending the tool modules.
What is refused regardless of the allowlist
| Error | Cause |
|---|---|
pom_ai_mcp_js_write_denied |
The field is JavaScript. Always refused, no exceptions |
pom_ai_mcp_complex_setting_denied |
The value is an array or object; use the dedicated tool |
pom_ai_mcp_css_denied |
CSS containing PHP tags or </style> |
pom_ai_mcp_template_php_denied |
HTML containing PHP tags |
The JavaScript refusal has no filter and no gate. There is no configuration that enables it.
The complex-value refusal is why repeaters — CSS snippets, templates — have their own tools rather than being edited through this one.
Values are sanitised
Plain values pass through text sanitisation, so markup in a text field will not survive intact. HTML fields always use the installation's KSES post-content rules, including for actors with unfiltered_html. Scripts and inline handlers remain excluded.
Check the result rather than assuming what you sent is what was stored.
The dry run is genuine
It returns before — the current value — and after, the value that would be stored after validation and sanitisation. That makes it a real preview, unlike some dry runs in the WooCommerce chapter which merely echo arguments.
It also runs the allowlist and validation checks first, so a dry run is how you find out a field is denied without writing anything:
Dry-run setting the post archive sidebar layout and show me the before and after.
For code fields the dry run returns the content itself; a real write stores it to a file and returns the path.
The write triggers the theme's save routine
After storing the value, the theme's own post-save action runs — the same one the admin fires. That is what applies the change rather than merely recording it.
Template settings additionally rebuild the theme's asset discovery manifests.
After writing
- Read the setting back with
pom_theme_get_settings_values. - Load an affected page and confirm the layout changed.
- Purge the cache.
Common problems
| Symptom | Cause |
|---|---|
| The write is refused | POM Theme write gate closed |
pom_ai_mcp_forbidden |
Missing manage_options; reading needs less |
pom_ai_mcp_theme_field_denied |
Not on the allowlist — the usual outcome |
pom_ai_mcp_theme_setting_not_found |
Wrong setting key |
pom_ai_mcp_js_write_denied |
JavaScript; unconditional |
pom_ai_mcp_complex_setting_denied |
Use the CSS or template tools |
| The stored value differs from what you sent | Sanitisation |