Agents API: promote agent authorization, access grants, tokens, and capability ceilings

[chubes4]

Problem

Greg's post argues that agent memory and behavior should delegate to existing platform permissions, not invent a parallel ACL. Data Machine already has the pieces:

• PermissionHelper maps agent actions to WordPress capabilities.
• Agent bearer tokens have optional capability restrictions.
• Agents execute under the owner's WordPress capability ceiling.
• datamachine_agent_access grants admin, operator, and viewer roles per (agent_id, user_id).
• Agent token auth sets the current user to the owner and records acting agent/token context.

These are generic agent substrate concepts and should move into Agents API contracts/default implementations.

Proposed shape

Promote generic contracts/value objects:

WP_Agent_Access_Grant
WP_Agent_Access_Store_Interface
WP_Agent_Token
WP_Agent_Token_Store_Interface
WP_Agent_Token_Authenticator
WP_Agent_Authorization_Policy_Interface
WP_Agent_Capability_Ceiling

Agents API should define the policy shape. Data Machine can keep its concrete DB tables initially as an adapter.

Acceptance criteria

• Agents API can represent who is acting, which agent is effective, which workspace applies, what token/client is involved, and what capability ceiling applies.
• Agent access grants are generic, role-based, and host-extensible.
• Token metadata supports label, expiry, last-used timestamp, and capability restrictions without storing raw tokens.
• Authorization checks compose token restrictions with the acting user's WordPress capabilities.
• Data Machine product code delegates to the Agents API authorization model instead of owning the generic model.

AI assistance

• AI assistance: Yes
• Tool(s): OpenCode (GPT-5.5)
• Used for: Source audit and issue drafting.

[chubes4]

Status after Agents API/Data Machine adoption

This tracking issue is superseded and complete.

What landed upstream:

• Add agent authorization contracts Automattic/agents-api#73 added the generic authorization substrate: WP_Agent_Access_Grant, token/store contracts, token authenticator, authorization policy, capability ceilings, and execution-principal context.

What landed in Data Machine:

• Adopt agent authorization contracts #1764 adopted those contracts in Data Machine's access grant/token/auth middleware/permission helper paths.
• Adopt Agents API authorization contracts for grants, tokens, and capability ceilings #1757 tracked the Data Machine adoption slice and is closed.
• The adoption meta Meta: adopt landed Agents API substrate contracts #1755 is also complete for the fix(cli): add missing --step parameter declaration for queue commands #65-Add inbound Agent Ping receiver for self-iterating loops #73 substrate wave.

Remaining authorization-adjacent work is not this issue's original scope:

• Migrate A2A caller context to Agents API primitive #1773 tracks migration of A2A caller context to Add caller context primitive Automattic/agents-api#81.

Closing this as completed/superseded by Automattic/agents-api#73 plus Data Machine #1764/#1757.

AI assistance

• AI assistance: Yes
• Tool(s): OpenCode (GPT-5.5)
• Used for: Auditing merged Agents API/Data Machine PRs and drafting this status update. Chris remains responsible for review and final issue management.