Define enterprise principal and client-context contract for permission-aware agents

[chubes4]

Goal

Define a generic Agents API contract for principal, ownership, and client context that downstream agent runtimes can use for permission-aware tools, citations, and audit trails.

This should support private-site knowledge products without encoding Intelligence or A8C-specific semantics.

Required work

• Clarify session owner, authenticated user, agent owner, workspace, audience, and runtime principal fields.
• Define how client context may explicitly map to tool arguments without broad ambient key matching.
• Provide metadata shape for citations/tool calls that records safe principal/source context.
• Support frontend chat/session surfaces that need to show permission-aware results and diagnostics.
• Document redaction and sensitive-context handling.

Acceptance criteria

• Data Machine and Intelligence can propagate permission context through tool execution and search/read provenance.
• Frontend clients can reason about permission-denied, partial, and source-restricted results.
• The contract remains generic enough for non-Intelligence agents.

Related

• Automattic/agents-api#273 for structured pending-action confirmations.
• Automattic/intelligence#815 for permission-aware search/read and wiki provenance.