Skip to content

Feat[Experiment]: Add Agent Users linked with parent user accounts - #1068

Open
nerrad wants to merge 6 commits into
WordPress:developfrom
nerrad:add/agent-users-parent-accounts
Open

nerrad wants to merge 6 commits into
WordPress:developfrom
nerrad:add/agent-users-parent-accounts

Conversation

@nerrad

@nerrad nerrad commented Sep 28, 2026 •

Copy link
Copy Markdown

What?

Closes #923.

Adds the Agent Users experiment: dedicated WordPress accounts linked to a human parent, with access bounded by that parent's current permissions.

Supersedes #211 by @Jameswlepage and #961 by @gziolo. This PR builds on #961's code; its first two commits carry @gziolo as co-author. It implements the parent/child account suggestion.

@josephfusco requested a default agent avatar. @mathetos's testing and permission feedback on #923 informed the decision to keep agents out of site-managing roles. @gziolo summarized the acceptance criteria and E2E scenarios implemented by the end-to-end tests.

Why?

External agents need their own identities so their work is attributable and their credentials can be revoked independently of a human account. Linking each agent to a parent also prevents it from acting with more authority than the person it represents.

How?

How to review: The branch was force-pushed into six batches. Each can be reviewed and merged as its own PR, and each passes PHPCS, PHPStan, and PHPUnit on single site and multisite on its own. Batches 1–3 must ship in the same release: until batch 3, deactivating the plugin leaves agent Application Passwords working without the parent limit.

  1. 0e700110 — Agent accounts and their security contract: Agent_Account, Agent_Provisioner, Agent_Authentication, Agent_Capabilities.
  2. 4fb099e8 — The experiment and its admin screens.
  3. 52633e96 — Revoking agent credentials when the plugin stops bounding them (Agent_Credentials).
  4. 9b586d2a — Keeping agents with their parents as accounts come and go (Agent_Lifecycle).
  5. c072d5ea — Only running the per-request safeguards once an agent may exist.
  6. 770c4804 — End-to-end tests, including a multisite CI job.

Inline review comments mark the spots most worth scrutiny.

Current behavior

  • Identity and parent link: An agent is a regular WP_User marked by wpai_agent user meta. wpai_agent_parent links it to a human parent; wpai_agent_created_by records the provisioner. The agent owns its work under its own account. Users → Add Agent requires an explicit eligible parent and appends _agent to the username.
  • Authentication: Agents cannot use password login or password resets. Provisioning gives them an unknown random password. They use core Application Passwords for API access; other authentication that resolves to the agent remains subject to the account restrictions.
  • Capabilities: The agent's role and its parent's current permissions both apply to each capability check, including object-specific checks. Roles with manage_options are unavailable to agents; agents cannot change other users or use unfiltered_html. Agent and parent treat each other's posts as their own under core's own-post rules. wpai_add_agents controls who may have agents, while user managers create them. Parents can edit their own agents' profiles and Application Passwords without edit_users; changing roles or deleting agents still uses core permissions.
  • Suspension: An agent with no eligible parent, a site-managing role, or a parent who is neither a member of the current site nor a super admin is suspended there. It keeps its account, content, and credentials, but has no capabilities and its Application Passwords are rejected with wpai_agent_suspended.
  • Deletion and site removal: Deleting a parent deletes its agents and applies the parent's content choice to their content. The delete screen names the agents and offers core's content choice when only an agent owns content. On multisite, removing a parent from a site removes its agents from that site.
  • Multisite: Agent identity and Application Passwords are network-wide; roles, parent eligibility, and suspension are site-specific. An agent may join only sites its parent belongs to, except that a super admin parent can authorize it on any site. Agents cannot become super admins. Add Agent requires network activation, and network deletion also handles agent content on sites the parent does not belong to.
  • Admin screens: The Users list labels agents with their parent or as suspended, filters by account type, and swaps the password reset action for credential management. Agent profiles hide human-only settings and explain suspensions; human profiles list their agents. Agents fall back to the plugin's flask avatar.
  • Enablement and retirement: Provisioning and the admin UI load only while the experiment is enabled. Turning it off leaves existing account safeguards in force; revoke credentials or delete an agent to retire it. Deactivating the plugin (network deactivation on multisite) revokes agents' Application Passwords. Reactivation emails each affected parent and shows a reissue notice until each agent has a new password. Activation also revokes credentials created while the safeguards were absent.
  • Safeguard gate and developer surface: The wpai_agents_exist network option avoids registering per-request agent safeguards on installs without agents, while authentication and password-reset checks still detect an agent marked outside provisioning. Read-only REST user fields wpai_is_agent and wpai_agent_parent appear in embed, view, and edit; wpai_is_agent_user() and wpai_get_agent_parent() expose the identity and link to PHP callers.

See includes/Experiments/Agent_Users/README.md for the full design and behavior.

Deliberate choices

  • Store the marker and parent link in user meta, rather than adding a wp_users column.
  • Narrow or suspend agents when roles or parent eligibility change; keep their accounts and content.
  • Keep agent creation with user managers for now; parents have no self-service creation flow.
  • Defer custom hooks for suspension and agent restrictions until the identity model settles.

Questions for maintainers

  1. Should parents manage their agents' profiles and Application Passwords on multisite without manage_network_users? This departs from core's model and has a @todo in code.
  2. Should the REST parent link (wpai_agent_parent) stay public in view and embed, or should the parent's display name also be exposed so public bylines always work?
  3. Should agents always be denied capabilities below manage_options, such as installing plugins, or stay bounded by the parent?
  4. Filters for suspension and agent restrictions are deferred until the identity model is confirmed. Do maintainers agree?

The experiment has not shipped, so there is no migration. Accounts marked as agents without a parent are suspended.

Use of AI Tools

Testing Instructions

  • PHP: npm run test:php -- --filter Agent_UsersTest and npm run test:php:multisite -- --filter Agent_UsersTest.
  • E2E: npm run test:e2e -- tests/e2e/specs/experiments/agent-users.spec.js tests/e2e/specs/experiments/agent-users-deactivation.spec.js. For multisite, start npm run wp-env:test-multisite start, then run npm run test:e2e:multisite.
  • Application Passwords require HTTPS or WP_ENVIRONMENT_TYPE=local.
  1. Enable the Agent Users experiment. Open Users → Add Agent. Confirm the parent is required and no role with manage_options is listed.
  2. Create an Editor agent for an Editor parent. Open the agent profile and create an Application Password.
  3. Authenticate as the agent over REST with that password and edit a draft owned by the parent.
  4. Demote the parent to Contributor. Confirm the agent's permissions narrow immediately.
  5. Explicitly deny wpai_add_agents to the parent with a role editor. Confirm the agent is marked suspended and its Application Password is rejected with wpai_agent_suspended.
  6. With a parent who owns no content and an agent that owns a draft, open the parent's deletion screen. Confirm it names the agent and offers the content choice. Reassign the content and confirm the agent is deleted with the parent.
  7. With an agent that has an Application Password, open Plugins. Confirm the warning that deactivation revokes agent credentials, then deactivate the plugin and confirm its Application Password is revoked.
  8. Reactivate the plugin. Confirm the parent sees the reissue notice until a new Application Password is created.
  9. On multisite, confirm Add Agent is available only with network activation. Confirm agents can be added only to sites their parent belongs to, except when the parent is a super admin.

Screenshots or screencast

Users list: agents labeled with their parent, and a suspended agent.

Users list with agents labeled 'agent of' their parent, one marked suspended

Users → Add Agent: core's Add User form with a required parent.

Add Agent screen with username, email, names, role, and a required Parent user field

Agent profile: the account note names the parent; human-only settings are hidden and Application Passwords stay.

Edit Agent screen with the agent account note and an Application Password

A suspended agent's profile explains why.

Edit Agent screen explaining the agent is suspended because its parent can no longer have agents

A parent's profile lists their agents.

User profile with an Agents section listing the user's agent

Deleting a parent names the agents deleted too, and counts agent content toward core's choice.

Delete Users screen offering the content choice and naming the parent's agent

The Plugins screen warns that deactivating revokes agent credentials.

Plugins screen with a warning under the AI plugin about revoking agent Application Passwords on deactivation

Changelog Entry

Added - Agent Users experiment with dedicated accounts linked to a parent user, bounded by the parent's permissions, and authenticated with Application Passwords.

Open WordPress Playground Preview

@codecov

codecov Bot commented Sep 28, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 73.97541% with 381 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.34%. Comparing base (7dbcf07) to head (770c480).

Files with missing lines Patch % Lines
...cludes/Experiments/Agent_Users/Agent_Lifecycle.php 29.00% 164 Missing ⚠️
...cludes/Experiments/Agent_Users/New_User_Screen.php 64.28% 65 Missing ⚠️
...ncludes/Experiments/Agent_Users/Profile_Screen.php 59.35% 63 Missing ⚠️
...udes/Experiments/Agent_Users/Agent_Credentials.php 88.79% 27 Missing ⚠️
...udes/Experiments/Agent_Users/Agent_Provisioner.php 87.28% 22 Missing ⚠️
includes/Experiments/Agent_Users/Agent_Users.php 63.46% 19 Missing ⚠️
includes/Experiments/Agent_Users/Agent_Account.php 93.02% 6 Missing ⚠️
includes/Experiments/Agent_Users/Users_Screen.php 91.42% 6 Missing ⚠️
...s/Experiments/Agent_Users/Agent_Authentication.php 94.44% 4 Missing ⚠️
...des/Experiments/Agent_Users/Agent_Capabilities.php 96.39% 4 Missing ⚠️
... and 1 more
Additional details and impacted files
@@              Coverage Diff              @@
##             develop    #1068      +/-   ##
=============================================
- Coverage      84.31%   83.34%   -0.98%     
- Complexity      3744     4291     +547     
=============================================
  Files            149      161      +12     
  Lines          14170    15632    +1462     
=============================================
+ Hits           11948    13029    +1081     
- Misses          2222     2603     +381     
Flag Coverage Δ
unit 83.34% <73.97%> (-0.98%) ⬇️

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.

@nerrad
nerrad force-pushed the add/agent-users-parent-accounts branch from 29b53b4 to 49070ed Compare September 28, 2026 13:20
@nerrad
nerrad marked this pull request as ready for review September 28, 2026 15:22
@nerrad
nerrad requested a review from a team September 28, 2026 15:22
@github-actions

github-actions Bot commented Sep 28, 2026 •

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @chubes4, @nikolas4175-godaddy.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

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

Unlinked contributors: chubes4, nikolas4175-godaddy.

Co-authored-by: nerrad <nerrad@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: mindctrl <mindctrl@git.wordpress.org>
Co-authored-by: jeffpaul <jeffpaul@git.wordpress.org>
Co-authored-by: dkotter <dkotter@git.wordpress.org>
Co-authored-by: webmyc <urbankidro@git.wordpress.org>
Co-authored-by: JasonTheAdams <jason_the_adams@git.wordpress.org>
Co-authored-by: mathetos <webdevmattcrom@git.wordpress.org>
Co-authored-by: TimothyBJacobs <timothyblynjacobs@git.wordpress.org>

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


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub or WordPress.org user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

@nerrad
nerrad marked this pull request as draft September 29, 2026 11:39
@jeffpaul jeffpaul linked an issue Sep 29, 2026 that may be closed by this pull request
1 task done
@jeffpaul jeffpaul added this to the 1.5.0 milestone Sep 29, 2026
@jeffpaul

Copy link
Copy Markdown
Member

@nerrad note that I'm holding off on pinging folks for review as this shows as in draft, so please open this up for review when you're ready, thanks!

@nerrad

nerrad commented Sep 29, 2026 •

Copy link
Copy Markdown
Author

Yup I moved out of draft prematurely by mistake and then moved it back because i wanted it to be a reference for discussion on #961 first. If we're good with trying this approach this PR would likely supersede 961.

@gziolo gziolo changed the title Feat[Experiment]: Agent Users with parent accounts (alternative to #961) Feat[Experiment]: Add Agent Users linked with parent user accounts Oct 5, 2026
@gziolo gziolo self-assigned this Oct 5, 2026
@gziolo

gziolo commented Oct 5, 2026

Copy link
Copy Markdown
Member

@nerrad, based on the conversations, I closed #961 in favor of this enhanced approach. Let's continue the development here. I plan to review and test the changes applied this week.

Additionally, I want to ensure that the #961 (comment) from @josephfusco doesn't get lost in the process:

Could agents get a default avatar? Without a Gravatar, an agent gets the site default, so Presence API's admin bar shows a mystery person beside its Agent badge. A pre_get_avatar_data filter here could give them the plugin's flask icon instead, so every get_avatar() call would match. Gravatar only falls back to a public PNG, JPG or GIF, so it needs a raster copy, or the filter sets url directly.

@gziolo

gziolo commented Oct 7, 2026

Copy link
Copy Markdown
Member

I would like to summarize the feedback from #923 and agree on what we need before merging this as an experiment.

The implementation already covers much of what we need. I would focus on these four points:

  1. Agree on the permission rules. We should resolve the open questions about parents managing agent profiles and Application Passwords on multisite, parents and agents accessing each other's posts as their own, and the permissions available to Administrator agents. These behaviors are already implemented. We need to agree on them and make sure the documentation and tests match.

  2. Decide whether the parent relationship should be public. The REST field currently exposes the parent ID in public contexts. We should confirm whether this is intended or whether access should be limited to users who can manage the agent.

  3. Test the creation and connection flow. The redirect to Application Passwords and the notice about showing the password only once are already there. Let's check whether someone new to the feature can create an agent, understand its permissions, and connect it without missing the password step. Following @mathetos's feedback, the selected role, the limits set by the parent account, and the broad access of Administrator agents should be clear. Automatic password generation does not need to be a requirement if the existing flow works well.

  4. Check suspension and deletion from the user's perspective. These paths already have test coverage. Manual testing should check the messages and content reassignment options when a parent loses permission to have agents, leaves a site, or is deleted. The documented multisite case where agent content is deleted on sites the parent does not belong to needs particular attention. Users should understand what will be deleted before confirming.

I would leave controls for individual abilities, a broader permission model based on risk, agent creation by parents, and additional customization hooks for later work.

I will use these points to guide my review and testing. We can then identify which changes are required before merging and which can follow after we gather feedback from the experiment.

@gziolo gziolo left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Three findings from testing the permission and deletion behavior.

@gziolo

gziolo commented Oct 8, 2026

Copy link
Copy Markdown
Member

I was thinking about E2E testing scenarios that could also serve as acceptance criteria for this experiment. These would complement the PHP tests by checking browser flows and making real REST requests with the agent’s credentials.

Five scenarios seem useful:

  1. Administrator creates and connects an agent. An administrator selects a parent and role, creates the agent, and follows the redirect to generate an Application Password. The generated password authenticates a request as the agent. After reloading, the credential remains listed, but its secret value is no longer visible.

  2. Parent manages an existing agent’s credentials. After an administrator creates the agent, its parent signs in as a non-admin user. They find the agent through their own profile, create a working credential, and revoke it. The revoked credential stops working. An unrelated user cannot manage the agent.

  3. Agent access follows changes to the parent’s permissions. An existing agent loses access to an operation when its parent loses that permission. If the parent can no longer have agents, the UI explains the suspension and the agent’s credentials stop authenticating.

  4. Deleting a parent preserves content when reassignment is chosen. A parent has no posts, but their agent does. The deletion screen explains what happens to the agent and offers reassignment. Choosing it preserves the posts under the selected user.

  5. Multisite changes affect the correct sites. Removing a parent from one site removes the agent’s access there while preserving access on other sites where both remain members. We should also cover deleting a parent when the agent owns content on a site the parent does not belong to, once we agree on that behavior.

These tests would check that the flows work together. A manual walkthrough would still help us check whether the explanations are clear to someone using the feature for the first time.

Comment thread includes/Main.php Resolved
nerrad and others added 6 commits October 25, 2026 14:22
Gives external software a dedicated WordPress user, marked as an agent
and linked to a human parent it acts on behalf of (WordPress#923). An agent:

- authenticates only with Application Passwords: password login, resets,
  and password changes are blocked, and its password stays unknown;
- can never do more than its parent currently can, since every
  capability check is repeated for the parent after all other mapping;
- cannot hold a role that manages the site, change other users, or
  write unfiltered HTML;
- shares post ownership with its parent;
- is suspended, keeping its account and content, wherever its parent is
  missing, cannot have agents (`wpai_add_agents`), or is not a member.

Agent_Account answers who is an agent, who its parent is, and whether it
is suspended. Agent_Provisioner creates agents after checking the
provisioner, the parent, and that the role grants nothing either lacks.
Agent_Authentication and Agent_Capabilities enforce the rules, and Main
registers them whenever the plugin is active, independent of feature
toggles, since agent accounts outlive them. On multisite, provisioning
requires network activation, because the agent marker is network-wide.

Builds on the Agent Users experiment from WordPress#961.

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
Registers the Agent Users experiment, which loads provisioning and
presentation only while it and the AI features are enabled. Agent
management stays on core's user screens, because an agent is a user:

- Users → Add Agent reuses the Add User form, with a required parent
  field and without password or notification controls, then opens the
  agent's profile to create its first Application Password;
- the agent profile hides human-only settings and explains why an agent
  is suspended, and human profiles list their agents;
- the Users list labels agent roles with their parent, filters by
  account type, and swaps the password reset action for credentials;
- REST user responses expose read-only `wpai_is_agent` and
  `wpai_agent_parent` fields, for "agent on behalf of" bylines;
- agents fall back to the plugin's flask avatar.

On multisite without network activation, the Add Agent screen is
unavailable and the user screens explain why.

Builds on the Agent Users experiment from WordPress#961.

Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
…them

The agent safeguards are plugin code, so while the plugin is inactive
nothing limits an agent to its parent or rejects its Application
Passwords. Deactivating the plugin on purpose therefore revokes them,
network-wide on network deactivation, and the Plugins screen confirms
first while agents exist. Core updates plugins without running
deactivation hooks, so updating leaves credentials alone.

Activation revokes any agent credential that exists at that point, since
the plugin never bounded it, and tells each parent once, by email and in
an admin notice, which agents need a new Application Password. An agent
presenting a revoked credential gets `wpai_agent_credentials_revoked`
naming that parent, and a suspended one `wpai_agent_suspended`, instead
of core's generic `rest_not_logged_in`. Only a credential that was real
gets either, so the errors do not reveal which accounts are agents.
An agent acts for its parent, so it follows the parent's account:

- deleting the parent deletes their agents, and agent content is
  reassigned to the same user as the parent's, or otherwise treated
  exactly as core treats the parent's; the delete screens count agent
  content, name the agents that go too, and never offer them as heirs;
- on multisite, removing the parent from a site removes their agents
  from it, deleting the parent from the network deletes their agents,
  and the network delete screen adds core's delete-or-reassign choice
  for agent content on sites the parent does not belong to;
- an agent can only join sites its parent belongs to, or any site under
  a super admin parent, and can never become a super admin.

Agent_Lifecycle holds these rules, and Main registers them with the
other agent safeguards.
The authentication and capability rules filter every capability check,
so installs that never create an agent should not pay for them. The
`wpai_agents_exist` network option records whether an agent may exist:
activation computes it, a missing value is computed on the next request,
and marking any account as an agent sets it and registers the rules for
the rest of that request.

While it says no agent exists, whoever authenticates, by password,
Application Password, or session, or asks for a password reset is
checked, so an agent marked behind the plugin's back, such as with
WP-CLI's `--skip-plugins`, or on another network of a multi-network
install, still gets the rules before it can act. Since registration can
now happen late, from any of those hooks, Main checks what is already
registered so the rules never register twice. Who may have agents and
the account lifecycle rules always run, since they are needed before
the first agent exists and only run on rare events.
Covers the Agent Users flows in a browser: creating an agent and its
first Application Password, a parent managing their agent's
credentials, agent access following the parent's permissions, deleting
a parent with content reassignment, and deactivation revoking
credentials with reactivation explaining how to reissue them. On a
multisite network, it covers the Add Agent form, removing a parent from
one site, and the network delete screen's choices for agent content on
sites the parent does not belong to.

Adds a multisite wp-env configuration and Playwright config, the
`test:e2e:multisite` and `wp-env:test-multisite` scripts, and a CI job
running the multisite specs, which the "Run E2E tests" check now waits
for. The E2E helper plugin gains endpoints for the multisite setup.
@nerrad
nerrad force-pushed the add/agent-users-parent-accounts branch from 319ce2d to 770c480 Compare October 25, 2026 18:55

$own_counterparts = array(
$post_type->cap->edit_others_posts => $was_published ? $post_type->cap->edit_published_posts : $post_type->cap->edit_posts,
$post_type->cap->edit_private_posts => $post_type->cap->edit_posts,

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-posting @gziolo's thread from before the force-push:

An Author agent cannot edit its own private post because the parent check still requires edit_private_posts. Could we fix the mapping and add a test for private posts?"

Fixed. For posts an agent and its parent share, share_post_ownership() swaps the private-post capabilities for their own-post counterparts (this line and the two below), so the parent is checked under its own-post rules too. test_shared_ownership_covers_private_posts covers it, and test_linking_leaves_access_to_others_posts_unchanged checks that linking grants nothing over anyone else's posts.


// Like core for the author, a trashed post that was published still counts as published.
$was_published = 'trash' === $post->post_status &&
in_array( get_post_meta( $post->ID, '_wp_trash_meta_status', true ), array( 'publish', 'future' ), true );

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-posting @gziolo's thread from before the force-push:

A Contributor parent can permanently delete an agent's trashed post that was previously published, although they cannot do this with their own post. Could we preserve the check for the previous post status and add a test?

Fixed. A trashed post whose _wp_trash_meta_status was publish or future keeps requiring the published-post capabilities, as core maps the author's own post. test_shared_ownership_keeps_own_post_limits covers it.

* @param array<int, array{agent: \WP_User, parent_id: int}> $agents Agents being deleted, keyed by ID.
* @param array<int, int> $excluded Users being deleted, who cannot receive content.
*/
private function render_agent_content_on_other_sites( array $agents, array $excluded ): void {

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-posting @gziolo's thread from before the force-push:

Deleting a parent also trashes agent posts on sites the parent does not belong to. Those sites are missing from the confirmation and reassignment options. We should address this before merging, so users do not lose content unexpectedly. What would be the best way to handle this?

What changed:

  • Agents can now only join sites their parent belongs to, or any site under a super admin parent (keep_agents_on_parent_sites()), so this case is now rare.
  • Where it still happens (a super admin parent who isn't a member, or content attributed to the agent directly), the network delete screen adds core's delete-or-reassign choice for the agent on each of those sites (this method). Archived and spam sites are included.
  • Agent content on the parent's own sites follows the parent's choice exactly as core applies it to the parent. The plugin no longer deletes agent content itself. One consequence: "Delete all content" during a network delete leaves the agent's posts behind, just as core leaves the parent's. That's core behavior for every user, and probably worth a Trac ticket.
  • On WP 7.0, whose network delete screen still lists the deleted users' agents as heirs, choosing one, or reassigning with nobody left to receive the content, is rejected before anything is deleted (reject_agents_as_network_heirs()).

Covered by test_multisite_delete_screen_offers_agent_content_on_other_sites, test_multisite_agent_content_without_receiver_is_deleted_with_agent, test_multisite_parent_delete_choice_treats_agent_content_like_the_parents, test_multisite_network_deletion_rejects_agents_of_deleted_users_as_heirs, and test_multisite_archived_sites_still_belong_to_parent_and_agent, plus the multisite E2E spec.

*
* @param bool $network_wide Whether the plugin is being deactivated across the network.
*/
public static function revoke_on_deactivation( bool $network_wide ): void {

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-posting @gziolo's thread from before the force-push (it was on Main.php):

These safeguards only run while the plugin is active. After deactivation, agents keep their full role without the parent limit, suspended agents can authenticate again, and Editor agents get unfiltered_html back. [...] Could we warn about it before deactivation when agents exist, and document it in the README?

I decided to go further than the warning:

  • Deactivating the plugin on purpose revokes every agent's Application Passwords (network-wide on network deactivation). The Plugins screen warns, and the Deactivate link asks for confirmation while agents exist. Core updates plugins without running deactivation hooks, so updates leave credentials alone.
  • Activation revokes any agent credential that exists at that point, since the plugin never bounded it (unless an update left the plugin inactive), and tells each parent once, by email and with an admin notice, which agents need a new Application Password.
  • An agent presenting a revoked credential gets wpai_agent_credentials_revoked, naming the parent who can issue a new one.
  • Agents never have a usable password: provisioning sets a random one, and profile, REST, wp_update_user(), and wp_set_password() updates keep it. A reset by email still works while the plugin is inactive; the README says so.
  • On multisite with only per-site activation, nobody can create new agent credentials, because one would authenticate on sites where nothing bounds it.

The README's "Enablement and retirement" section documents all of this.

}

if ( is_multisite() && ! self::belongs_to_site( $parent->ID, get_current_blog_id() ) && ! is_super_admin( $parent->ID ) ) {
return 'parent_not_member';

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-posting @gziolo's thread from before the force-push:

On multisite, this checks the parent on the current site. If the parent is not a member there and is not a super admin, the agent counts as suspended on that site. Its Application Password is then rejected, and the Users screen says the parent 'can no longer have agents', which is not the real reason. [...] Which behavior do we want? The multisite test only covers a super admin parent, so a test with a regular parent would help too.

I decided to keep suspension and made it the backstop. Agents can only join sites their parent belongs to (Agent_Lifecycle::keep_agents_on_parent_sites()), and where an agent ends up on another site anyway, for example through WP-CLI, it's suspended there with its own reason, parent_not_member. The REST error and the profile now name that reason, the Users list marks the agent as suspended instead of blaming the parent's eligibility, and the network profile lists the sites where the agent is suspended. The README describes per-site suspension. With a regular parent: test_multisite_agent_is_suspended_where_parent_is_not_a_member and test_multisite_agent_joins_only_sites_of_its_parent.

*
* @param bool $network_wide Whether the plugin is being activated across the network.
*/
public static function on_activation( bool $network_wide ): void {

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Highlighting for reviewers that deliberate activation revokes every agent credential that exists at that point, since the plugin never bounded it, unless a marker set while updating (note_update() / forget_update()) says an update left the plugin inactive. A missing marker revokes credentials that were fine and sends a reissue email: disruptive, but safe. A stale marker is the risky direction: it would skip revoking credentials created while the plugin was inactive. How the marker is set and cleared deserves scrutiny.

* @param int|string $user_id Deleted user ID.
* @param int|null $reassign User ID receiving the deleted user's content, or null.
*/
public function delete_agents_of_deleted_user( $user_id, $reassign ): void {

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Highlighting for reviewers that deleting a parent deletes their agent accounts, and the agents' content follows the parent's reassignment choice. This is the one place the plugin deletes accounts by itself, so a wrong parent link here means a deleted account. The links are protected from capability-checked meta writes (auth_user_meta_*), and agents can never be parents.

*
* @since x.x.x
*/
public function reject_agents_as_network_heirs(): void {

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Highlighting for reviewers that on network users.php with action=dodelete, this runs on load-users.php, before core's per-site loop, and stops the request if a deleted user's own agent was picked as heir, or if a "reassign" has nobody to receive the content. It depends on that hook order and on the request shape of WP 7.0's and 7.1's network delete screens, which differ. No test pins the hook order; the integration tests call the method directly. This should get scrutiny.

Comment thread includes/Main.php
add_action( 'added_user_meta', array( $this, 'register_safeguards_for_marked_agent' ), 10, 3 );
add_action( 'updated_user_meta', array( $this, 'register_safeguards_for_marked_agent' ), 10, 3 );

if ( ! Agent_Account::agents_may_exist() ) {

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Highlighting for reviewers that the per-request safeguards register only once wpai_agents_exist says an agent may exist. The risk is the flag reading 0 while an agent exists. It's set whenever any account is marked as an agent, computed when missing, and recomputed on activation. Until it flips, whoever authenticates (by password, Application Password, or session) or requests a password reset is checked first, at priority 0, so an agent marked behind the plugin's back gets the safeguards before it can act. Who may be a parent and the lifecycle rules always run.

The assumption is that agents_may_exist result is accurate. But I also think this needs scrutiny.

@nerrad

nerrad commented Oct 25, 2026

Copy link
Copy Markdown
Author

I meant to add this to the review body above but missed it

I force-pushed this branch to hopefully help make it a bit easier to review. The history was about 80 commits (the #961 import plus review fixes); it's now six, each a batch that could be reviewed, and if we want, merged as its own PR (but we'd have to think about sequencing as noted below, so a release doesn't expose things it shouldn't):

  1. 0e70011 Agent accounts and their security contract: identity, provisioning, no interactive login, the parent ceiling, and the other capability rules
  2. 4fb099e The experiment and its admin screens: Add Agent, profiles, the Users list, the REST fields, and the avatar
  3. 52633e9 Revoking agent credentials when the plugin stops bounding them: deactivation, reactivation, and the reissue notice
  4. 9b586d2 Keeping agents with their parents as accounts are deleted, removed, or added to sites
  5. c072d5e Only running the per-request safeguards once an agent may exist
  6. 770c480 End-to-end tests, including a multisite job

Each commit passes PHPCS, PHPStan, and PHPUnit on single site and multisite by itself. 1 to 3 should land in the same release: until 3, deactivating the plugin leaves agent Application Passwords working without the parent limit.

Agent_Account was also split by responsibility into Agent_Account (identity), Agent_Provisioner, Agent_Authentication, Agent_Capabilities, and Agent_Lifecycle, with no behavior change.

The force-push detached the earlier inline threads. I re-posted each one where its code lives now, with what changed or what I propose, and added comments on the changes I'd most like a second pair of eyes on (I'll resolve the earlier threads so they don't clutter up the event stream in the PR).

Open questions for maintainers:

  • whether the parent link in the REST response (wpai_agent_parent) should stay public;
  • the multisite exception that lets parents manage their own agents without manage_network_users;
  • deferring filters for suspension and agent restrictions until the identity model is settled.

@nerrad
nerrad marked this pull request as ready for review October 25, 2026 19:53
@nerrad
nerrad requested a review from jeffpaul as a code owner October 25, 2026 19:53
@nerrad

nerrad commented Oct 25, 2026 •

Copy link
Copy Markdown
Author

note: I'm also working on updating the PR description so it more accurately represents the current state of the PR

Done.

@jeffpaul
jeffpaul requested a review from gziolo October 26, 2026 21:17
@jeffpaul jeffpaul modified the milestones: Future Release, 1.5.0 Oct 26, 2026
@jeffpaul jeffpaul mentioned this pull request Oct 28, 2026
31 of 46 tasks
@dkotter dkotter modified the milestones: 1.5.0, 1.6.0 Oct 28, 2026
null !== $response ||
'GET' === $request->get_method() ||
! $request->has_param( 'password' ) ||
1 !== preg_match( '#^/wp/v2/users/(\d+|me)$#', $request->get_route(), $matches )

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Core matches routes in a case insensitive way, so this could be bypassed if someone requests something like .../Users/.

$post_type->cap->edit_private_posts => $post_type->cap->edit_posts,
$post_type->cap->delete_others_posts => $was_published ? $post_type->cap->delete_published_posts : $post_type->cap->delete_posts,
$post_type->cap->delete_private_posts => $post_type->cap->delete_posts,
$post_type->cap->read_private_posts => $post_type->cap->read,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think using cap values as keys will cause problems here. For example, nav menu editing is restricted to edit_theme_options and almost all the cap values are that. PHP will use the value of the last one, which might be read. In the wild, there could be any combination of cap values that cause this array to function in unexpected ways.

webmyc added a commit to webmyc/mcp-adapter that referenced this pull request Nov 7, 2026
Builds the rest of the confirm half promised on WordPress#402.

- Retries: a confirmation still runs its call once, and the response is
  kept until the confirmation would have expired. A retry of the same
  call (same token or state, user, tool and input) gets that response
  back. A retry that arrives mid-run waits briefly, then says the call
  is still running; it never runs twice. Protocol errors and results
  over 512 KB are not replayed. Only the response is stored.
- Follow-ups: a confirmation may cover up to three follow-up calls,
  declared by the Ability (meta.mcp.confirmation_follow_ups) or a
  filter. Each is bound to one Ability and input for the same user and
  site, and is named in the question under "The same yes also covers".
  Anything else is asked as usual.
- Approval link: clients with URL elicitation get a wp-admin page
  (admin-post.php) that the approver opens as themselves: the agent
  user's parent (wpai_get_agent_parent(), WordPress/ai#1068) or the
  calling person. Nonce-protected, only the approver can see or answer
  it, expires with the confirmation. Approving records channel "url"
  and approved_by; the client's retry then runs the call.
- mcp_adapter_tool_call_confirmed now also carries the confirmation id,
  approved_by and follow_up_of, and fires once per confirmation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
webmyc added a commit to webmyc/mcp-adapter that referenced this pull request Nov 7, 2026
The logging half of C4 in WordPress#402, stacked on the confirm branch.

- One entry per confirmed call, as a private post type with no author:
  Ability, tool, input hash (never the input), the summary the person
  saw, channel, approver, the user and, for agent users from
  WordPress/ai#1068, its parent at the time (wpai_is_agent_user(),
  wpai_get_agent_parent()), the follow-up it was covered by, times and
  the result. Names are kept with the IDs, so entries survive deleting
  or reassigning users.
- New action mcp_adapter_tool_call_confirmation_finished reports
  success, error or failed for each confirmed call. Replayed retries do
  not fire it again, so they are not logged twice.
- Tools > Agent changes lists the entries: everything for users who
  can manage options, otherwise their own calls, their agents' calls
  and the calls they approved.
- Keeps the newest 500 entries (filterable); can be turned off.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jeffpaul

Copy link
Copy Markdown
Member

@JasonTheAdams @dkotter even with the coming OAuth effort aligned to WP 7.3, I think its still worth getting this experiment into the AI plugin as a comparable option; any concerns with that?

@dkotter

dkotter commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

@JasonTheAdams @dkotter even with the coming OAuth effort aligned to WP 7.3, I think its still worth getting this experiment into the AI plugin as a comparable option; any concerns with that?

Yeah, I'd like to see this move forward.

@nerrad There's a number of merge conflicts here that need cleaned up. Beyond those, anything else you're tracking before this is ready for review? I see there's a handful of open comments but not sure the status of those

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Introduce agent users to give AI agents an auditable identity

5 participants