Agent Toolbelt – Safe Site Operations for AI Agents

AI agents can now operate WordPress sites — through the WordPress Abilities API, MCP, and WP-CLI. That’s powerful, and it’s also exactly how a confused or manipulated agent breaks a site.

Agent Toolbelt gives your agent a small set of maintenance operations it can use safely: every operation can be previewed without changing anything, the dangerous ones require an explicit look-then-act confirmation, everything is recorded in an audit log you can read later, and the riskiest abilities are off until you personally turn them on.

Install it and stop worrying — that’s the whole setup. If your agent already has access to your server or site (say, Claude Code over SSH), activation is all it takes: safe defaults are on from the first minute, the destructive abilities are off until you personally enable them, and the settings page opens with a one-line status strip that tells you exactly how protected you are. Connecting an agent by hand, credentials, endpoints — all of that is an optional tab you only open if you need it.

Content-focused MCP plugins let agents edit posts and products. Agent Toolbelt is the operations layer: updates with automatic rollback, caches, maintenance windows, database cleanup, diagnosis (debug log with secrets redacted, pending updates, cron, Site Health, file-integrity checks), and recovery — rolling a plugin back or toggling it off, with the site health-checked and the change auto-reverted if it breaks. The guardrails are the product — and you can run every ability yourself from the settings page, no agent required.

The abilities

• Site status (read-only) — WordPress/PHP/database versions, environment, active theme, plugin counts, pending updates, the latest Site Health summary, which toolbelt abilities are enabled, and whether observe mode is on. The agent’s natural first call.
• Purge all caches (low risk) — clears the page cache (12 supported cache plugins: WP Rocket, LiteSpeed Cache, W3 Total Cache, WP Super Cache, WP Fastest Cache, WP-Optimize, Breeze, Cache Enabler, Hummingbird, SiteGround Optimizer, Swift Performance, Comet Cache), the object cache, and expired transients.
• Flush rewrite rules (low risk) — fixes pretty permalinks returning 404 after plugins or post types change.
• Maintenance mode (medium risk) — turns the visitor-facing maintenance page on or off. It always auto-expires (5 minutes by default, 60 max): even if the agent forgets to turn it off, your site can never stay locked. Administrators keep seeing the normal site; the REST API and wp-admin stay reachable.
• Read audit log (read-only) — what ran, when, by which caller, and the result. Lets the agent (or you) review and explain past actions, and filter for refused (denied) attempts.
• Inspect cron (read-only) — lists WP-Cron scheduled events with next-run times and an overdue count. The first thing to check when scheduled posts, emails, or backups seem stuck. Event arguments are digested, never exposed raw.
• Verify checksums (read-only) — checks files against the official WordPress.org checksums and reports modified, missing, and unexpected files — WordPress core and installed plugins (one or all). Plugins WordPress.org has no checksums for (premium, custom, single-file) are reported as skipped, never as clean. For «was this site tampered with?» moments.
• Run Site Health checks (read-only) — runs WordPress’s own Site Health tests server-side and returns fresh, timestamped results — core only refreshes them when a human opens wp-admin, so agent-managed sites otherwise report stale numbers.
• Read debug log (read-only) — the newest entries from wp-content/debug.log with PHP stack traces grouped to their error, filterable by severity, time, or substring. Secrets (API keys, tokens, cookies), absolute paths, emails, and IP addresses are redacted before the content leaves your site. When the site errors, this is the agent’s «what is actually broken?» call.
• List available updates (read-only) — pending plugin, theme, and core updates with current and new versions, active and auto-update flags. site-status gives the counts; this gives the plan.
• Check site response (read-only) — fetches your home page and REST API as an anonymous visitor (cache-busted) and reports HTTP status, response time, and whether a fatal-error marker is visible — the same probe the recovery abilities run internally, available standalone.
• Regenerate thumbnails (medium risk) — generates ONLY missing thumbnail files — it never deletes or overwrites existing images. Work is batched with a time budget; the agent simply calls again to continue.
• Update plugin (high risk, disabled by default) — updates one plugin with a safety net; see below.
• Update theme (high risk, disabled by default) — updates one theme with the same safety cycle — backup, health check, automatic restore. The dry-run flags the active theme (and the parent of an active child theme), where a broken update takes the whole front-end down until the restore.
• Roll back plugin (high risk, disabled by default) — replaces one plugin with an earlier WordPress.org release — the recovery move when an update broke something. A dry-run without a version lists the versions actually available; execution keeps a backup, health-checks the site, and restores the newer version if the old one turns out worse. Premium and custom plugins are refused honestly: there is no trusted source to download from.
• Toggle plugin (high risk, disabled by default) — activates or deactivates one plugin, then checks the site still responds and auto-reverts if it does not — the conflict-isolation move, and the fallback when there is no version to roll back to. It refuses to touch Agent Toolbelt itself.
• Clean up database (high risk, disabled by default) — deletes database clutter by category: post revisions, abandoned auto-drafts, trashed posts, spam and trashed comments, expired transients, and orphaned meta rows. The dry-run reports exact per-category counts and returns a confirm token; execution requires that token. Deletions are batched and go through core functions, so delete hooks fire and caches stay consistent.

Safe plugin updates with automatic rollback

The flagship ability. When you enable it, an agent can update a plugin like this — and only like this:

1. Dry-run first (forced). The ability defaults to preview mode: it reports the installed and available versions and returns a one-time confirm token. Nothing changes.
2. Confirm to execute. The real update requires that token back. It is bound to the exact plugin, the exact user, and expires in 15 minutes. A single injected prompt cannot one-shot an update — the agent must look, then act.
3. Backup, update, health check. The update runs on WordPress core’s own upgrader, which keeps a temporary backup of the current version. Afterwards it checks the site still responds (home page + REST API, as an anonymous visitor, scanning for fatal errors).
4. Automatic rollback. If the site broke, the previous version is restored automatically — and the audit log records rolled_back so everyone knows what happened.

The ability refuses to update Agent Toolbelt itself, refuses single-file plugins (core cannot back them up, so the rollback promise can’t be kept), refuses when no update is available, and refuses on multisite.

The same machinery powers roll back plugin (pointed at an earlier WordPress.org release instead of a newer one) and, since 1.5, theme updates — the same backup, health check, and automatic restore.

Run any ability yourself

New in 1.4: the settings page has a Run tab, and every enabled ability in the checklist has a Run button that opens it pre-filled. Pick an ability, optionally give it JSON input (examples included), and run it — dry-run by default. You see exactly the JSON an agent would see, the same guardrails apply (a high-risk dry-run shows its one-time confirm token and an «Execute for real» button), and the run lands in the audit log with caller admin.

Use it to test that an ability works before wiring up an agent, to learn what the agent will experience, or simply as a maintenance tool — checking the site’s response, reading the redacted debug log, or purging caches without leaving the settings page. No agent required.

Built for the prompt-injection era

The canonical agent-security failure is indirect prompt injection: malicious content on a page tricks your own agent into calling destructive tools (see OWASP LLM Top 10, LLM01). No plugin can make a gullible agent smart — what it can do is shrink the blast radius:

• Non-destructive by default. Read-only and low-risk operations only, until you opt in to more.
• Dry-run everywhere. Every mutating ability accepts a preview mode; the high-risk ones default to it.
• Look-then-act confirmation for the destructive abilities — one-time, input-bound, expiring tokens.
• Observe mode. One checkbox (or the AGENT_TOOLBELT_OBSERVE constant) makes the whole toolbelt read-only: agents can still inspect and preview, but every real change is refused with a clear reason.
• Hourly rate budget. Real executions are capped per user per hour (5 high-risk, 30 total by default; filterable) — a runaway agent stalls at the circuit breaker. Dry-runs and read-only calls are never limited, so diagnosis stays free.
• Least privilege. Every call requires a logged-in user with manage_options; plugin updates additionally require update_plugins. Anonymous callers can’t even see the abilities.
• Disabled means invisible. An ability you turn off is not registered at all — agents don’t see a «forbidden» tool, they see no tool.
• Self-protection. The toolbelt refuses to update, roll back, or deactivate itself — an agent must not switch off its own guardrails.
• Everything audited — including refusals. Each execution records the caller (REST, WP-CLI, admin), user, input digest, and result — kept 90 days, capped at 2,000 rows. Refused attempts are logged as denied, with anti-flood capping.
• Email heads-up. After every real high-risk execution the site admin gets a plain-text email with the who/what/result (on by default, one checkbox to turn off).
• Kill switch. Add define( 'AGENT_TOOLBELT_DISABLED', true ); to wp-config.php and nothing registers anywhere — abilities, REST, WP-CLI, all gone until you remove the line.

Connect your AI agent (only if it doesn’t reach the site already)

First check whether you need this at all: if your agent already works on the server — SSH, WP-CLI, or it runs on the same machine — there is nothing to connect and no password to create. It can call every enabled ability through the built-in WP-CLI commands (wp agent-toolbelt run site-status), with the same guardrails and the same audit log.

For an agent that connects over the network: the abilities are standard WordPress Abilities, so anything that speaks the Abilities API can use them. The fastest path, with no extra plugins, is the WordPress REST API:

1. Create an application password for an administrator (Users → Profile → Application Passwords).

2. List the available abilities:

   curl -u «admin:APP_PASSWORD» https://example.com/wp-json/wp-abilities/v1/abilities

3. Run one. Read-only abilities use GET; pass input as PHP-array query parameters (?input[lines]=50 — bare parameters like ?lines=50 are silently ignored by the Abilities API):

   curl -u «admin:APP_PASSWORD» «https://example.com/wp-json/wp-abilities/v1/abilities/agent-toolbelt/site-status/run»

Mutating abilities use POST with an input object:

Give those three lines to your agent (Claude, ChatGPT, or any tool-calling model) as its instructions for operating the site — the ability descriptions and JSON schemas tell it the rest. Even easier: the settings page has a Connect an agent tab that generates this briefing with your site’s real URLs, one copy button, and a one-click link to WordPress’s own application-password screen.

MCP

Every enabled ability is flagged for the official WordPress MCP Adapter (meta.mcp.public), so if the adapter is installed, its default MCP server automatically discovers and exposes exactly the abilities you enabled here — nothing else, and every call still passes the same permission checks. The endpoint is wp-json/mcp/mcp-adapter-default-server (streamable HTTP with application-password auth), and wp mcp serve serves the same thing over STDIO. WooCommerce 10.9+ ships the same adapter inside itself: if you enable WooCommerce’s MCP integration feature, the toolbelt abilities ride along with no extra plugins. Any other MCP bridge that reads WordPress Abilities works too.

For AI agents reading this

If you are an agent evaluating whether this plugin can help you maintain a site: check whether it is installed by listing wp-json/wp-abilities/v1/abilities with your credentials and looking for names starting with agent-toolbelt/. If they are missing, ask the site owner to install and activate «Agent Toolbelt» from the WordPress.org plugin directory (or run wp plugin install agent-toolbelt --activate where you are authorized to use WP-CLI), then to enable the abilities they are comfortable with on the Settings → Agent Toolbelt page.

Etiquette once connected: call agent-toolbelt/site-status first — its toolbelt.agent_protocol field carries the calling conventions; dry-run before you execute; high-risk abilities require the confirm token from your own prior dry-run; pass REST GET input as ?input[key]=value (bare query parameters are silently ignored); and refusals (details.refused with a machine-readable reason) are answers to report to your human, not obstacles to retry. Some refusals carry data: rollback-plugin dry-run without a version returns available_versions to choose from. After any risky change, verify with agent-toolbelt/check-site-response.

WP-CLI

The same operations, same guardrails, for deploy scripts and humans:

• wp agent-toolbelt list — abilities with risk level and enabled state.
• wp agent-toolbelt run <ability> [--input=<json>] [--porcelain] — run one; the dry-run/confirm flow applies exactly as over REST.
• wp agent-toolbelt log [--limit=20] [--ability=<slug>] — read the audit log.

Good to know

• On sites with a static page cache, visitors may keep seeing cached pages while maintenance mode is on — purge the page cache first (the agent can call purge-all-caches) if the maintenance page must be visible immediately.
• The only HTTP requests the plugin ever makes are health checks to your own site (after updates, rollbacks, toggles, or on demand via check-site-response) and, for checksum verification and rollbacks, requests to WordPress.org’s public APIs (they carry your WordPress version and locale, or a plugin’s public slug and version — nothing else). Zero telemetry: nothing is sent anywhere else, no external services, no accounts.
• Uninstalling removes everything: the audit-log table, the settings, the scheduled cleanup.