Automattic / Automattic/agents-api

Derive pending-action resolver provenance from the authenticated principal

Open
#489 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
PHP
Stars
33
Forks
8
Avg merge
1h 39m
Merged PRs (30d)
30

Description

## Problem

`agents/resolve-pending-action` currently requires a caller-supplied `resolver` string and forwards it unchanged to `WP_Agent_Pending_Action_Resolver::resolve_pending_action()`. That value is intended to become durable resolution audit data, but the canonical ability does not bind it to the authenticated execution principal.

A permitted REST or MCP caller can therefore submit a resolver such as `user:42` even when the request was authenticated by an agent token, application password, runtime, or another user. Host resolvers can independently re-resolve and compare the principal, but every consumer must remember to do so, and the canonical ability shape makes the untrusted string look authoritative.

This surfaced while prototyping a cross-agent code-review relay. Agent feedback may remain private, but promoting a finding to repository-wide durable learning must require a real human decision. Treating caller-supplied identity or verdict fields as audit provenance lets an agent self-attest that promotion.

Capability checks answer whether the caller may invoke the ability. They do not prove that a caller-supplied audit identity describes who actually invoked it.

## Proposed direction

Derive resolution provenance from `WP_Agent_Execution_Principal` at the canonical ability boundary and pass it to the resolver in a typed or canonical shape. At minimum, that shape should preserve:

- canonical actor identity/owner key;
- `auth_source` (`user`, `application_password`, `agent_token`, `runtime`, etc.);
- acting user and effective agent where applicable;
- whether the execution is autonomous;
- request context and timestamp supplied by the substrate, not the client.

The existing `resolver` input can be deprecated, retained only as an untrusted display label, or validated against the derived principal during a compatibility period. Resolution metadata that represents provenance should not be accepted from `payload` or `context` as authoritative.

A small value object such as `WP_Agent_Resolution_Actor` may make the trust boundary clearer than another array, but the important part is that the substrate derives it. Host-specific resolvers would still own authorization, handler dispatch, and persistence.

## Acceptance criteria

- An agent-token invocation cannot produce a resolution audit record claiming browser user-session provenance.
- A WordPress browser session, an application password, an agent token, and a runtime remain distinguishable in resolution audit data.
- Host-defined auth sources remain supported.
- Canonical pending-action abilities pass authenticated provenance to the resolver without trusting caller input.
- Existing resolver implementations have a documented migration path.
- Tests cover spoofed `resolver` input and browser-vs-autonomous resolution.

## Related

- #163 introduced the canonical pending-action abilities.
- #206 hardened execution-principal auth source and binding.
- #412 enforces capability ceilings at execution; this proposal is complementary audit-integrity hardening.

## AI assistance

- AI assistance: yes
- Tool(s): Codex
- Used for: tracing a downstream review/learning prototype through the current pending-action and execution-principal contracts, checking related issues, and drafting this proposal.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start at the agents/resolve-pending-action canonical ability and trace how it calls WP_Agent_Pending_Action_Resolver::resolve_pending_action(). Read the WP_Agent_Execution_Principal contract and related issues #163, #206, and #412 before choosing the provenance shape. Done means canonical abilities derive authenticated provenance, reject spoofed resolver identity, preserve supported auth sources, and document migration for existing resolvers.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
api, authentication, security
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.