feat(auth): grant/revoke/list-users agent access abilities over WP_Agent_Access_Store

[chubes4]

Closes #537.

What

Registers three write-side agent-access abilities in src/Auth/register-agent-access-abilities.php, over the existing WP_Agent_Access_Store contract (same file and style as the existing read-side pair):

Ability	Permission gate	Input	Output	Annotations
agents/grant-agent-access	admin role on target agent	{ agent, user_id, role? (default viewer), workspace_id?, metadata? }	{ granted: true, grant: {...} }	idempotent — the store contract upserts ("Create or update a grant")
agents/revoke-agent-access	admin role on target agent	{ agent, user_id, workspace_id? }	{ revoked: bool }	destructive
agents/list-agent-users	operator role on target agent	{ agent, workspace_id? }	{ users: [grant] }	idempotent, readonly

All three are show_in_rest: true, category agents-api, registered behind the same wp_has_ability guards as the read side.

Permission model

Agent-role, not WordPress capabilities — agent-role grants are the substrate's authorization model, so no capability checks are invented. Write abilities require the current principal to hold an admin role grant on the target agent (WP_Agent_Access::can_current_principal_access_agent( , ROLE_ADMIN, )); agents/list-agent-users requires operator. Both decisions run through the existing agents_access_permission filter hook so hosts can tighten or widen them exactly as they can for the read abilities.

Error surface

Execute callbacks return WP_Error (not success:false arrays): agents_access_invalid_agent, agents_access_unknown_agent (via a cheap WP_Agents_Registry::is_registered() lookup), agents_access_invalid_user, agents_access_invalid_role, agents_access_store_missing (when WP_Agent_Access::get_store() resolves to null), and agents_access_last_admin — revocation checks get_users_for_agent() first and refuses to remove the agent's last remaining admin grant (audience admin grants count toward the survivor set). The last-admin rule is documented in the ability description.

Consumer

Data Machine already implements WP_Agent_Access_Store via its AgentAccessStoreAdapter (Extra-Chill/data-machine#3473, interim datamachine/manage-agent-access ability) and will switch to these slugs once merged — retiring that plugin-side wrapper is the motivating use case from the issue.

Tests

• New tests/agents-access-write-ability-smoke.php (33 assertions, registered in composer.json scripts.smoke): grant → list shows it → revoke → list empty; re-grant upserts instead of duplicating; non-admin principal denied on the grant permission gate; operator passes the listing gate; last-admin revoke refused with agents_access_last_admin; revoking a non-admin grant never blocked; workspace scoping; invalid role / invalid user / unknown agent / missing store WP_Errors; ability registration.
• Full composer test (102 smoke files) and composer phpstan (level max) pass locally; Generic.Formatting.MultipleStatementAlignment clean on changed files.

Docs

docs/auth-consent-context-memory.md gains an "Agent access abilities" subsection documenting all five access ability slugs with permission gates, input/output, and annotations.

AI-generated with Claude Code via Homeboy worktree