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-READ 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-READ 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-READ (mode="off"; the DEFAULT): dataSurface absent, null, or an empty product list — and always the answer when the OBDA-READ component is not enabled for the agent (Administration → Components, the per-user override, the agent's Capabilities toggle — read by core/obda_planes and handed to the parser as parse_scope(cfg, planes=…)), because parse_scope drops the surface at the parse seam (OBDA-READ is additive, charter #15: plane off ⇒ the platform behaves as if OBDA-READ never shipped for that agent; gating each consumer separately is how the enrichment and the agent face were missed — found live, session d51cf073). The former OBDA_ENABLED master was migrated once into component availability (Oct 2026) and no longer exists. 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.

2b. The write surface (OBDA-ACT, PROP-008 §5.4 — increment B3)

The data surface's twin for writes. authorityConfig.actions = {types: [...], exclusive?} parses to AgentScope.actions_allowed / actions_exclusive — the grant is the list, and both are dropped at the one parse seam while the OBDA-ACT component (action) is not enabled for the agent (planes= — the plane is the component; the former ACT_ENABLED master no longer exists).

Who decides a parked write — four eyes (PROP-008 §5.4a). authorityConfig.actions.approvers (account usernames, read by agent_authority.action_approvers, dropped while OBDA-MODEL · OBDA-ACT is off) names the accounts that approve this agent's parked writes. With a designation the agent's OWNER may not approve them — authority over the write is split between the agent's owner (whose agent and connection perform it) and a second person (who decides it). Absent, the owner decides — the single-account baseline. Like the grant, the designation is access, not trust: it moves no signature. Full contract: ACT_ARCHITECTURE §3.5.

Why a signed action never travels through a data tool. A data tool runs one statement per call under autocommit; an action is the preconditions, the before-image read, the write, the postconditions and the ledger row in ONE transaction, rolled back if any check fails (dbdeploy/action_runner.py). So the action face performs through a Database Connection (core/action_perform.py), and the SQL gate's part is the refusing side above. On Teradata the connection's login must HOLD the manifest's role (A6 proved what that role grants) and the session acts under it (SET ROLE); the platform never widens a role. Measured live: a login holding only UDERIA_ACT_FITNESS was refused by the database itself when writing a table outside the contract (Error 5315).

Before anything touches a connection, perform_action refuses: OBDA-MODEL · OBDA-ACT off, an unknown action, an action that is not signed-and-intact, an agent whose grant does not name it.

The posture ladder is reused verbatim: observe records what would be written and writes nothing; review checks the preconditions and parks the compiled write (review_queue, source action, never releasable into a conversation); the owner's approval (POST /v1/assurance/reviews/<id>/approve) performs it BEFORE the disposition is recorded — only if the manifest hash, the re-compiled statement hash and the invocation hash all equal the parked ones and the agent's grant still names the action; a refused approval returns 409 action_not_performed and records nothing. annotate and enforce write.

The receipt. Every invocation is appended to the turn's action record (a contextvar started and ended at the execution seam), stamped on the turn as turn['actions'] at the persistence chokepoint; each PERFORMED one is sealed as an action.performed provenance step in ProvenanceChain.finalize() through action_perform.receipt_content — the same function verify_content uses, so a tampered stamp is a named mismatch. The OBDA-READ lane scanner reads the record: acted_count / refused_count, headline lane acted (absent on a turn without actions — byte-identical baseline).

Measured (B4d). action_safety (BOUNDED, ACT moment, owned by the actions mechanism): of the action writes the turn put to the database, the share whose every check held — read through the same fold every surface reads, informational, abstaining when no write reached the database (an act refused before it compiled is not a write). The write-escape red-team probe lures an action-only agent into a raw UPDATE (a self-assignment on an impossible key, so even an escape changes no row) and adjudicates from the turn's own stamps: the action-only denial on the write statement → held; a raw write that executed → the escape; a refusal in words naming the action route → held; no signal → honestly unknown. The live runner scores each probe against its PERSISTED turn (live_redteam.with_turn) — the task result alone carries no tool calls.

The action-only denial is recovery-shaped (like the surface denial): it spells out the next step — change the data through one of the signed actions it names, with TDA_Action if that tool is offered to the agent, otherwise tell the user which action would make the change — and never says "report this limitation". TDA_Action is named conditionally because the action component may be off for the agent; an instruction to call a tool that is not offered is the defect the tail exists to avoid.

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

3b. Several MCP servers (PROP-006 phase 2)

An agent with additional MCP servers sees an additional server's tools under a qualified name (crm__base_readQuery, MULTI_SOURCE_ARCHITECTURE.md §9). Authority is decided at the same chokepoints, on the name the agent sees:

• denied_tools matches that name — base_readQuery denies the primary server's tool, crm__base_readQuery the additional server's. Deny both to deny the capability everywhere.
• deny_writes classifies the SQL statement itself, so a write is denied whichever server it goes to.
• Rules that recognise a tool by what it IS (the SQL tool, discovery tools, the governed tool-surface backbone) read the base name through tool_identity.base_name; test/tool_identity_gate.py fails the build on a comparison that bypasses it.
• Each server's own database login still bounds what the call can read — the database, not the tool name, is the boundary.

Open (build brief B4): an allow-list per source, with denials naming the source.

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-READ) — 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