Agent Authority

Status: implemented on main (2026-07-03). Delivers assessment requirement P3 (agent identity & permissions — only Salesforce/Microsoft were GREEN). Built on the Trust Membrane (Tier 5.2) foundation: the agent is a first-class governed principal. Design: LEAPFROG_ROADMAP.md Epic 3.3, TIER_5.2_TRUST_MEMBRANE.md §1.5.

Renamed 2026-07-04 — this document was formerly "Agent Identity Architecture" and the module was core/agent_identity.py. It was renamed to Agent Authority (core/agent_authority.py) because in Uderia an agent's identity is its Profile; this subsystem governs the agent's authority. See §0. The stored config key moved identityConfig → authorityConfig (the legacy key is still read). The internal class AgentPrincipal keeps its name — it is the correct IAM term.

0. What "Agent Identity" means in Uderia — read this first

"Agent identity" in the market is an umbrella term. In Uderia it is not a single feature — it is a composite realised across four subsystems on two orthogonal axes. Keeping them distinct is the whole point of this rename.

Visual companion: The Uderia Agent — An Anatomy of Trust — the whole-agent diagram this taxonomy comes from (the five faculties inside the Trust Membrane, on the Grounding & Guardrails foundations). Its center — Agent Identity = who it is = its Profile — is exactly the "identity" row above.

Two rules follow, and they are load-bearing:

1. Identity ≠ authority. The Profile says who the agent is; Agent Authority says what it is permitted to do. A trusted, well-defined agent (identity + assurance) can still be given a deliberately narrow authority. This is the platform's phrasing of charter #8, trust ≠ access.
2. Authority is delegated and can only shrink. An agent has no authority of its own — when it acts autonomously it borrows a strict subset of its owner's permissions. The model can only remove; it can never grant or elevate.

If you came here looking for "the agent's identity," you want the Profile and, for how it's surfaced as an estate-wide map, the Platform Ontology. This document is specifically the access/authority face.

1. The idea

When an agent acts autonomously — a genie expert delegated by a coordinator, a scheduled task firing on a timer, a flow node, an inbound MCP ask_profile call — it is not a human issuing that request in the moment. Until now such actions ran under the owner's raw authority (the parent's auth_token, the task's user_uuid). P3 makes each autonomous action run as an Agent Principal derived from the owner whose authority is a strict subset of the owner's — and attributes every autonomous action to the agent in the audit trail.

Honest scope. This is the attainable form of P3: a scoped principal + audit attribution + fail-closed enforcement over capabilities (tools, writes, connectors, budget). The fuller vision — an agent confined to a graph sub-segment via ontology-mediated data access ("cannot query outside its slice") — depends on OBDA, which does not yet exist (Tier 5 Step 5). The shipped form scopes what the agent can do, not yet what data it can see structurally.

2. The model — pure, deterministic, subset-only

core/agent_authority.py is pure: the model + the enforcement decision. It never grants — a scope only ever removes the owner's authority (subset invariant by construction, so an agent with no config behaves exactly as today — byte-identical baseline, charter #15).

3. Enforcement — a per-turn security context, fail-closed at every chokepoint

The design problem: one gate misses most engines, and threading a principal through every call site is fragile. The solution is a per-turn security context via contextvars + layered enforcement at the execution chokepoints.

• contextvars.ContextVar (async-task-local, non-racy). The principal is set once at the autonomous-turn boundary and read at every tool chokepoint. contextvars propagate into awaited coroutines and child tasks (asyncio copies the context at task creation), so concurrent sessions stay isolated and no signature plumbing is needed. An interactive user turn leaves it unset → baseline (no gating). (A CI test proves the propagation across await and the concurrent-turn isolation.)

• Set/reset at the turn boundary — agent/execution_service.py:run_agent_execution. When _effective_origin ∈ AUTONOMOUS_ORIGINS (genie_parent · genie_child · flow · scheduler · mcp) it derives the principal from the active profile and sets the ambient context; on convergence it resets and stamps the turn payload with the actor (agent vs user). A scheduled task's source="scheduler" is mapped to the scheduler origin so the principal applies. Genie slaves run as separate HTTP requests (their own task/context) → each gets its own principal, no cross-task leak.

• Four chokepoints read the ambient principal and deny before executing (all-engine, because every tool call from any engine funnels through one of these):

The single shared decision module agent/tool_enforcement.py backs both MCP paths so the "fail-closed at every tool chokepoint" guarantee holds on every engine, including the ReAct engine that bypasses invoke_mcp_tool.

• Fail-closed (charter #8): enforce_tool() returns deny on any enforcement error; a denial returns a terminal, non-retryable result (denied_tool_result) stamped agent_denied so it is auditable and the LLM incorporates it as a definitive outcome (no self-correction loop). No principal (interactive) → allowed (baseline).

4. Persistence & UX

• Storage: the profile's authorityConfig block (in user_preferences profile JSON, same as guardrailConfig/groundingConfig — no schema change). The legacy identityConfig key is still read on load, so profiles saved before the rename keep their scope; the next save rewrites them under authorityConfig.
• Profile editor: an Agent Authority card (configurationHandler.js + index.html) — process-focused: it frames the model ("when this agent runs autonomously it acts as a scoped identity derived from you — its identity is the Profile itself; leave untouched to inherit your full authority") then exposes allow-autonomous · read-only · denied-tools · allowed-connectors · per-run budget. Theme-aware, monochrome icon, collapsed by default.

5. Guarantees & proof

• Byte-identical baseline — no authorityConfig/identityConfig (or all-default) → unrestricted scope, is_restricted False, nothing gated.
• Subset-only — the scope model has no grant/elevate field; it can only remove.
• Backward-compatible — legacy identityConfig is still honored; authorityConfig wins when both are present (asserted in CI).
• Proof — test/test_agent_authority.py (46 assertions: decision · subset invariant · config back-compat · contextvar set/get/reset · async propagation-across-awaits + concurrent-turn isolation · fail-closed enforce · denial shape) + a live integration proof through the real invoke_mcp_tool chokepoint (owner/no-principal passes; the autonomous agent is denied base_writeQuery before touching MCP; a permitted read tool passes) + the real stored-profile → scope loop (config_manager load of @OPTIM → derive_principal → denial).

5a. The trust-budget circuit breaker writes here (Jul 2026)

The Behavioral Trust Score's opt-in circuit breaker (trust_behavior.breaker_mode = "freeze_autonomy" — see AGENT_OPS_EVAL_ARCHITECTURE.md §6c) acts through this model, not around it: when an agent's trailing conduct enters at_risk, the breaker sets the profile's authorityConfig.autonomous = False and stamps frozen_by_breaker: true + frozen_reason — suspending only the agent's unattended use via the exact same scope the Agent Authority card edits (interactive use untouched; visible and reversible by clearing the flag / re-enabling autonomous in the card). The stamps are plain authorityConfig keys, so export/import and the editor treat them like any other scope field. Implementation: eval/online.py:_run_trust_breaker (the freeze_autonomy branch calls config_manager.update_profile).

6. What's deferred (charter #19)

• Structural data-scoping (OBDA). The agent confined to a graph sub-segment — the fuller P3 vision — is Tier 5 Step 5. The Agent Principal is its on-ramp: the same principal that scopes capabilities today will carry the data-scope when OBDA exists, extending — never forking — this model.
• Per-run budget is post-hoc (is_run_within_budget, enforced at the execution_service.run_agent_execution end-of-turn seam after the turn's cost is resolved): an overrun stamps authority_budget_exceeded on the payload + emits an agent_budget_exceeded audit event so the caller (scheduler, coordinator) can react — it is recorded, not a mid-run kill switch. (max_cost_per_run: 0 is honored as a real deny-all cap, not "no cap".)
• MCP origin is in AUTONOMOUS_ORIGINS but an inbound MCP ask_profile is not yet stamped with a distinct origin at the execution layer (it currently arrives as a user REST call); genie/flow/scheduler are the live autonomous triggers today.
• Frontier "agent identity" facets the platform does not yet claim (see §0): the agent authenticating to external systems as itself (its own workload credential), its own vaulted short-lived secrets distinct from the owner's, and formal OAuth token-exchange / on-behalf-of delegation downstream. Authority (this doc), assurance (Trust Membrane), and audit (provenance) are in place; those three are the open edge of the identity umbrella.

7. Files