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.

Scope (updated Aug 2026). The original delivery was 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 data slice ("cannot query outside its slice") — shipped with OBDA Phase C: the data surface (§2a below) makes the set of signed data products on an agent's surface its entire data authority, enforced through this same principal at the same chokepoints. See OBDA_ARCHITECTURE.md §6.

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).

2a. The data surface (OBDA Phase C — E1–E5, per-agent tri-state)

authorityConfig.dataSurface = {products, exclusive, advisory}, read through ONE resolver — agent/obda.py:profile_obda(profile) → (mode, products) — which is what the enrichment render/seed/event, both agent actions, the governed_execution planner pass, the lane scan and the champion filter all consult (the tri-state, operator model 2026-08-17):

• Option A — Disable OBDA (mode="off"; the DEFAULT): dataSurface absent, null, or an empty product list — and always the answer when the OBDA_ENABLED master is off, because parse_scope drops the surface at the parse seam (OBDA is additive, charter #15: master off ⇒ the platform behaves as if OBDA never shipped; gating each consumer separately is how the enrichment and the agent face were missed — found live, session d51cf073). No products are visible to the planner, query_product/list_products refuse (obda_not_enabled_for_agent), no lane stamp, no confinement.
• Option B — Surface Full (mode="exclusive", {products, exclusive: true}): surface-only (E1). When the agent runs autonomously, raw SQL is denied fail-closed at all three chokepoints below (the sql argument is threaded through is_tool_allowed); only signed-and-intact products are served (E2/E4, enforced in the product face). Counts as restricted for authorityScope; downgrade-guarded in the config contract (a pack republish cannot silently relax it). Deliberately no TDA_ exemption — canvas SQL is the same escape hatch. advisory is B's observe-only development sub-toggle (E4): nothing denied, violations observed and scored.
• Option C — Products + regular paths (mode="mixed", {products, exclusive: false}): the listed products render as consumption contracts BESIDE the full KG paths — the LLM decides per question. Nothing is denied, but the list is still the grant: query_product refuses products not on it (not_on_surface, naming the granted surface). That check is config-driven, so it holds on interactive turns that carry no ambient principal.

Visibility vs enforcement — two seams, deliberately split. Planning visibility (which contracts the planner is shown, which champions are offered) follows the PROFILE configuration on every turn, interactive included; raw-SQL enforcement stays with the ambient PRINCIPAL (autonomous turns, plus the explicit enforce_interactive opt-in). An empty product list is Option A by construction — the profile editor never shows a mode that does not act, and saves an empty list as a cleared surface.

The one exception — the turn-scoped governed-SQL registry. query_product registers its compiled statement (register_governed_sql), so the only raw SQL a surface-only agent can execute is a statement the surface itself produced this turn; an edited statement forfeits the contract. The registry is a mutable set in a contextvar, created at set_current_principal and mutated by reference — a .set() in a child task is invisible to sibling tasks (contextvars propagate parent→child only, and Optimize runs parallel phases).

Recovery-shaped denial. A surface denial spells out the NEXT STEP (call query_product, execute the returned statement verbatim), keyed on the ONE SURFACE_DENIAL_MARKER; the blanket "do not retry; report this limitation" tail is reserved for categorical denials (denied tool, deny_writes) where nothing the agent does can help.

E5 — the empirical monitor. Free-formed SQL executed by a surface-only agent means the confinement leaked: a DANGER surface_breach incident (Assurance Inbox, BOUNDED station) whose summary says "a hole report, not agent misbehaviour". It fires only on the breach — advisory, additive, governed and interactive turns are all silent.

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.

The scope is a declared choice, not a hardcoded constant (Aug 2026). An agent may opt its INTERACTIVE turns into enforcement too: authorityConfig.enforce_interactive: true (agent_authority.enforces_interactive, consulted at the same one gate — AUTONOMOUS_ORIGINS ∨ enforces_interactive(profile)). Why: an operator ticked Surface-only (structural confinement) and then watched the agent hand-write raw SQL in chat, because a principal was never derived interactively — a switch labelled structural confinement that silently does not apply to the mode the operator is using is the wrong default, and what the human "control" actually sees is prose, not SQL. Rules, each mutation-tested: it WIDENS the scope, never replaces it (an autonomous origin still derives a principal whatever the flag says); only an explicit True opts in (a migrated "true" string must never start denying tools); it governs the WHOLE authorityConfig, not the data surface alone (a partially applied principal would be a second, subtler notion of authority); turning it OFF is a pack-import downgrade (flag_paths). Editor: Agent Authority card → Apply to interactive turns too. Default absent ⇒ byte-identical baseline.

• A SQL argument that is not a STRING is refused before any round trip — tool_enforcement.nonstring_sql_block, ONE implementation on BOTH data-tool paths (the MCP adapter and the ReAct wrapper; the first version lived inline in the adapter alone and a cross-class audit found the ReAct path uncovered). The refusal's marker is in DEFINITIVE_TOOL_ERRORS, so no self-correction rounds fire: retrying cannot change what the upstream step produced. TDA_* exempt; never raises.

• 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.

4a. Reporting a scope — presence is not constraint

Any surface that reports what an agent may do must resolve the scope, never inspect the raw config. authorityConfig being a non-empty dict says nothing about whether the agent is constrained: {autonomous: true, denied_tools: [], deny_writes: false, max_cost_per_run: null} is a fully-populated block that restricts nothing, and is byte-for-byte equivalent at runtime to no block at all. A presence check over that key once rendered the least-bounded agent in an estate as green under the headline "a strict subset of yours", while agents with no block — behaving identically — read as honest n/a. It rewarded touching authority in the direction of more autonomy.

Two helpers make the resolved answer the only reachable one:

GET /v1/profiles ships the result as a computed, read-only authorityScope {restricted, autonomous, constraints[]}; the Trust Circle's BOUNDED station and the posture matrix render that field rather than re-deriving it. The station reads pass only when every agent in scope genuinely restricts itself, and warn — with a count of how many would act with the owner's full authority if run unattended — otherwise.

The asymmetries is_restricted already encodes are exactly the ones a naive reader inverts: allowed_connectors: [] is deny-all, not "no restriction", and max_cost_per_run: 0 is a real (deny-all) cap, not an absent one.

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 (58 assertions: decision · subset invariant · reported-scope agrees with enforced scope (a present-but-empty block is not restricted; description non-empty ⇔ restricted; $0 cap and empty connector allow-list read as real constraints) · 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) — delivered, Aug 2026: the Agent Principal now carries the data surface (§2a), exactly as this row predicted — extending, never forking, this model. Kept here as the record of the prediction.
• Per-run budget is enforced in two places, on ONE predicate (is_run_within_budget):
• In-flight (check_budget_before_call, the same predicate): asked BEFORE each model call is paid for, on every engine that spends autonomously. Routed through PlanExecutor (Optimize/Ideate/Focus helpers), the ReAct engine (conversation_agent at each on_chat_model_start, accumulating self._run_cost_usd, halting with a named, graceful stop that keeps the partial answer + budget_stopped), and the genie coordinator (same seam). No ambient principal (interactive turn) → the check is a no-op → baseline. This closes the earlier gap where only the PlanExecutor path checked in flight, so ReAct + genie got post-hoc flagging only — "an audit record wearing a control's name".
• Post-hoc (execution_service.run_agent_execution end-of-turn seam): a final check after the turn's cost is resolved, stamping authority_budget_exceeded + emitting an agent_budget_exceeded audit event so the caller (scheduler, coordinator) can react.
• (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