docs: describe agent authority, broker trust boundaries, and implementation gaps

[jhrozek]

Summary

Document the intended agent-identity and external-broker design, separating the
reader-facing explanation from implementation evidence and remaining work.

Design narrative

docs/agent-authority.md covers:

• User, logical-agent and workload identities, including the limits of trusting
  a shared Mecatl process to identify its agents.
• The A–D progression from Kubernetes ServiceAccount authentication to
  logical-agent credentials and SPIFFE workload authentication.
• Interactive execution: broker admission for an exact call, followed by
  ToolHive token exchange using the existing user access token and a separate
  logical-agent credential.
• Credential custody, account association, denial behavior and unknown outcomes.

Implementation companion

docs/agent-authority-implementation.md records inspected implementation
snapshots, gaps and follow-up decisions. It distinguishes existing functionality
from proposed integration rather than presenting the design as already shipped.

Scope

Documentation only. No runtime behavior changes.

The design retains the existing broker, browser authorization, token refresh and
provider credential custody. It does not introduce a new consent or mandate system.
Provider-credential linkage is an OAuth/ToolHive concern, separate from SPIFFE
workload authentication.

Review focus

• Are the trust placed in Mecatl and the broker’s independent checks clear?
• Are user, agent and workload identities kept distinct throughout the flow?
• Does the intended design preserve exact-call authorization independently of
  OAuth token claims?
• Does the companion accurately identify what remains unresolved?

Validation

• Staged whitespace checks passed.
• task docs ran but did not pass link validation.
• The companion references a document absent from the branch and two ToolHive
  follow-up briefs not included in this commit; those links need resolution
  before merge.

[JAORMX]

Jakub, my main concern here is keeping the agent/subagent hierarchy from the existing identity model:

https://github.com/stacklok/mecatl/blob/main/docs/agent-identity-model.md#the-three-tier-model

I'm fine with code-reviewer being a stable logical identity that we can use in policy. But we also need to know which instance of that reviewer we're talking about and where it sits in the delegation tree:

Alice
└── main
    └── code-reviewer
        └── security-reviewer
            └── another specialist

Each child inherits restrictions from its parent, all the way down. If the main agent was restricted to reviewing PR 42, spawning a specialist with a broader definition must not give it access to other repositories or permission to merge.

The document does say children only narrow authority. What I'm missing is how we carry and enforce that hierarchy through issuance, broker admission and recovery. The credential identifies the definition, and then we have separate run and call bindings, but where is the binding to the actual parent and the authority delegated to this particular child?

I'm not asking for a private key per subagent or claiming this isolates goroutines from a compromised Mecatl process. I want us to preserve the delegation tree as something we enforce, rather than something we only reconstruct from logs.

Can we make that relationship explicit before settling the credential model? I'd like the broker flow to implement the definition/instance/run model, rather than leave the instance hierarchy behind.

[JAORMX]

One clarification on my earlier comments: I’m thinking of this in two phases. First, identities and cryptographically verifiable attribution across the agent/subagent tree, so we can audit which instance did what and beneath whom. Then, policy enforcement where each child’s authority stays within what its parent may delegate.

I see this PR as helping with that first foundation. I’m not asking us to settle the policy language or containment mechanism here, or make the complete enforcement model a prerequisite for attribution. I want us to preserve the hierarchy now so enforcement can build on the same model later.

[JAORMX]

Jakub, one more thing I'd like us to account for is agent definition provenance. This expands the scope a bit, so I'm not asking us to implement every source adapter or settle a wire format in this PR. But I think we should capture the requirement on both the Mecatl side and the identity broker side.

For attribution, I'd like to answer: which agent definition revision did this particular agent instance actually use, and where did it come from?

With local files, that could mean repository, path, commit and content digest. But Mecatl's AgentDefSource is deliberately storage-independent. An agent definition could also come from a Kubernetes custom resource or a service backed by Postgres. The provenance contract should support those sources without making Git or Kubernetes concepts part of the core interface.

Could we leave room for an agent definition provenance envelope with extensible metadata and versioned profiles? Something like this, just to illustrate the shape:

agent_definition_provenance:
  profile: mecatl.agent-definition-provenance.git/v1
  metadata:
    repository: https://github.com/example/agents
    path: agents/reviewer.md
    commit: "<full commit ID>"
    source_content_digest:
      algorithm: sha256
      value: "<digest of the source content>"
    accepted_definition_digest:
      algorithm: sha256
      value: "<digest of the normalized agent definition>"

A Kubernetes profile could describe the source cluster, custom-resource object UID, observed revision and relevant-content digest. A service-backed profile could use a service/tenant namespace, object identifier and revision. Those are source details; the workload running the agent has its own identity and runtime metadata.

I'm fine with the metadata being a map, provided each profile has a strict contract: required fields, schemas, hashing rules and defined revision semantics. The operator should be able to require particular evidence, and the source shouldn't be able to weaken those requirements by selecting a more permissive profile.

The distinction between source content and the accepted agent definition matters here. Mecatl parses and normalizes agent definitions, so the bytes read aren't necessarily the exact representation used to construct the agent. Having a commit and a digest also doesn't establish that the loaded content belongs to that commit. A locally modified file is an obvious example.

The flow I have in mind is:

Source adapter/service
  → agent definition + source evidence
Mecatl's trusted resolver
  → accepted definition snapshot + validated provenance
Mecatl's instance lifecycle
  → bind that snapshot to the instance and its parent
Identity broker
  → validate required evidence and establish a verifiable binding
Invocation/audit records
  → retain the link to that instance and provenance

This information should come from source resolution and trusted execution state, not from the model. The agent definition and its provenance need to describe the same snapshot. We shouldn't reconstruct provenance afterward by looking at whatever happens to be current in Git, Kubernetes or the service.

On the broker side, we should distinguish what it verifies independently from what it accepts as Mecatl's attestation. “Mecatl reports loading these bytes from commit X” is different from “the broker verified these bytes against commit X.” We don't need the broker to access every backend, but its signature shouldn't obscure that trust distinction.

I also don't think the full provenance record needs to be a claim in every token. We could embed it or use an integrity-protected reference to retained evidence. If the logical-agent credential is reusable across instances, the binding needs to live in instance-specific evidence or an authenticated broker record instead. Otherwise, one credential could end up describing several different agent definition revisions ambiguously.

This fits the observability-first phase: establish which agent definition each instance used and preserve that evidence alongside the delegation hierarchy. It doesn't grant permissions by itself. Later, enforcement could require approved revisions or particular source authorities.

Can we capture this in the proposal and track the Mecatl interface and broker work separately? I'd like us to preserve enough information now that verifiable attribution doesn't stop at the agent definition's name and admission tier.

[JAORMX]

So, I think we're mixing two threat models here. With native execution enabled, mecak8s already keeps workspace filesystem operations and Shell in separate executor Pods, behind the execution provider. A prompt-injected agent running a command doesn't automatically get access to the mecak8s process or its credentials. The proposal acknowledges that existing boundary, but I'd like that distinction to drive the rationale throughout.

I'm in favor of brokerage, and I want the real provider credentials kept away from mecak8s. I also want to keep the agent loop minimal. Owning OAuth enrollment, account association, refresh, credential selection, and mediated provider calls is plenty of responsibility for a broker already!

I don't have a strong opinion about whether that needs its own deployment. A separate deployment is fine for operational ownership, independent lifecycle, or sharing the service across instances. But I wouldn't make process separation the main security argument for the identity design. Keeping credentials outside mecak8s can reduce exposure if that process is compromised, provided its storage and deployment permissions are actually separated. That's a useful property, but it's a different threat from hostile code running in an executor.

And moving the signer doesn't make the identity reports independently trustworthy. If we trust mecak8s to report the user, agent instance, and delegation context, that trust remains. A compromised process holding multiple agent credentials can still substitute one for another. The docs already acknowledge this, and I think we should make it part of the starting assumptions rather than something readers discover after the architecture.

I'd frame this around the responsibilities first: the loop runs agents, the existing execution boundary handles workspace code, and the broker owns provider connections and protected external calls. Identity issuance can be a module in that design without implying another service or per-agent process isolation.

The part I'd like us to discuss separately is broker ownership of run admission and agent lifecycle. Establishing bounded access to external tools makes sense. Becoming another authority over whether agents can start or runs can execute is a much larger decision. Can we clarify which one we mean, and keep the attribution work from depending on the broader execution-control design?

[jhrozek]

Replies to the review summary and the first two issue comments, as of fbf9e8d.

Review summary (delegation hierarchy through issuance, admission and recovery). The hierarchy is now enforced at the broker, not only reconstructed from logs. Each instance is registered under its parent. The broker stores an effective ceiling equal to the child's definition ceiling intersected with the parent's, evaluates it on every call, and reloads it unchanged on renewal and recovery. Details are in Delegated authority and the thread replies above.

Two phases (attribution, then enforcement). Phase 1 maps onto the audit evidence table and the illustrative authorization record. They attribute each call to its instance, incarnation, definition revision, creation parent, run, delegation and user, and mark which facts are verified and which are reported. Server/tool enforcement against the parent's ceiling landed in v1 as well. Still deferred: task-specific bounds, resource/argument policy, and a verified per-operation binding for the reported run and delegation fields.

Agent definition provenance. Captured in a new Definition provenance section:

• a versioned profile with profile-specific metadata (Git, Kubernetes CR, or service-backed), keeping AgentDefSource storage-independent;
• strict per-profile contracts, with operator-required evidence that a source can't downgrade;
• separate source-content and accepted-definition digests, with the locally-modified-file caveat;
• provenance from the trusted resolver, never reconstructed later;
• broker-verified facts kept distinct from mecak8s-asserted ones;
• provenance stored in the per-instance registration record rather than in tokens.

Mecatl and broker work are tracked separately in implementation.md. No wire format is chosen.

The 2026-10-12 comment on threat models and broker scope is still under discussion.

[jhrozek]

This round of review comments is answered, and each thread has a reply linking the commit. I've left the threads open so you can resolve them, or push back if a reply doesn't settle it.

Answers to review comments

• Sequencing (@ChrisJBurns, @JAORMX). The identity work comes first and has no broker authority in it; the authority work follows. "v1" is gone from the drafts (eede8bd).
• Deployment and threats (@JAORMX, 10-12). The broker starts as modules inside mecak8s and later becomes a separate service. A new section says what each deployment closes against a compromised mecak8s, and what stays mecak8s's word in both. Run admission is now an explicit non-goal (adae397, 81eae38).
• Relationships diagram (@ChrisJBurns). Folded in from docs: clarify agent definitions, instances, sessions, and runs #2347. Also: the glossary now separates host sessions from broker sessions (c872f08, d830782).
• Logout (@ChrisJBurns). "Sign out" ends one client's tokens. "Sign out everywhere" stops every agent and schedule. AS-1 re-checks the company-IdP grant, so a disabled account stops acting (5aec36d).
• Audit (@JAORMX). This covers three changes:
  • an AuditEvent profile, which also has AS-1 set act.iss (1a56af2);
  • delegation lineage kept as retained audit events (905f9e9);
  • delivery, protection, and reconciliation, with the sink being the toolhive-core audit logger pointed at a store mecak8s can't write (3557e50).

Other changes, not asked for in review, worth a look

• AS-1 ID-JAG flow (e2e684a). The credential flow was reworked around a sign-in at AS-1, a session-bound broker refresh token, and an ID-JAG per call. Its decision record is now folded into the chapters and deleted (f7c5f58).
• Definition loader (d9fb3c0). It's a broker module again. It loads global definitions at startup, and mecak8s names definitions by reference.
• ID-JAG §9.3 (ca5d9c1). It's now quoted correctly: the section is about trust domains. Embedded mode is outside its cross-domain scope and reuses the format for one protocol path.
• Session binding (467060b). At session open, AS-1 now checks that the token's user owns the session, which catches mistakes. Session-bound tokens via RFC 9396 are recorded as later work.
• Containing a compromised mecak8s (27a5065). The later authority work does this with loader-set ceilings, operator-listed root-eligible definitions, and grants per run.
• ToolHive ledger. The ToolHive work list in implementation.md is now the ledger of the ToolHive changes this design needs. None is filed as an issue yet.

[JAORMX]

shipit