A worker profile says which agents exist on it in spec.agents, built-ins included and in every mode; the plane applies it before any team's grant, a child profile can only narrow it, and the pod drops every definition it excludes, subagents too¶
Decision 968 · accepted · 2026-10-29
The person running a plane wanted a profile called, say, base company info to never offer
build, whatever any team's grant says, and the same for subagents it never needs. Until
now a profile offered its bundle's primaries plus every built-in primary the bundle did not
shadow (Bundles.offering/2), and the only narrowing was a team's grant: entitlement rows
resolved by Entitlement.resolve/2, carried to the pod as the entitlement set, and applied
there to primaries alone (Definitions.load(entitled:)), on purpose, so a bundle's own
delegation kept working for a team that had simply not listed a name it never names. That
left nothing a profile could say for itself, and nothing that reached a subagent.
This extends Decision 913 (a profile's rules are an enforced scope on its pods, read at every activation; a child keeps its parent's and may only add) and Decision 826 (on a pod the bundle's and the built-ins' names beat the disk's): the rule here is one more thing the profile says about its pods, and it is about the agents that decision put in charge.
- The field.
spec.agentson theWorkerProfile, besidepermissions:allowanddeny, each a list of agent names, built-ins and the bundle's alike, declared in the CRD aspermissionsis.allowpresent means only those names exist on the profile, in every mode;denytakes names away; deny over allow, as a grant's rows are read; absent is what every profile had before.admin.profile.puttakes the same document and the row's changeset refuses a name in both lists, a name that is not one, or a field that is neither list, with a sentence; a manifest read in gitops mode goes through the same check. An unknown name is kept, since a bundle may gain it, andadmin.profile.agentslists such names asunmatched. - One module reads it everywhere.
Troupe.Protocol.AgentRuleis the reading:parse/1,allows?/2,keep/2,compose/2,json/1. The plane and the pod both use it, so the offering a person is shown and the definitions a session loads cannot disagree. - Before any grant.
Bundles.offering/3cuts the bundle's primaries and the built-in primaries by the profile's rule first, then the team's entitlement rows narrow what is left. Sosession.create'sagent_forrefuses an excluded primary with its existing sentence and the list it could have had,profiles.listnever shows it, and the entitlement set carried to the pod is already the primaries the rule leaves. A grant can only narrow what the profile offers; it cannot reach past it. - The pod needs the rule itself. The set names primaries. For subagents the activation
carries
agent_rulebeside the set ({"allow": [...]?, "deny": [...]},allowleft out where there is none, since the CRD types it as a list), read again at every activation like the per-tool rules, and left out where the profile says nothing. It rides on the session's bundle map, as the set does, so the one reader of the bundle applies it.Definitions.load(agent_rule:)applies it last, after the whole search order is merged and afterentitled, to every mode: a subagent the rule excludes is not in the map, so the delegate tool's list,fetch/2andprimaries/1never see it and no agent of another name reaches it by delegating. The moduledoc says why this one is applied to subagents where the set is not: the set is a team's narrowing of what the profile offers; the rule is the profile saying the agent does not exist on these pods, for anybody.session_createdrecordsagent_rulebesideentitlements, an addition within schema version 1. A laptop session has no rule. - extends. A child has its parent's rule as well as its own and can only narrow
(
Extends':agent_rulefield rule,AgentRule.compose/2): itsallowis cut to the parent's where the parent has one (an empty cut stands, and a grandchild cannot widen it), itsdenyadds to the parent's, and a denied name leaves theallow, so the composed rule reads as a profile could have written it and passes the row's own check. The row holds the profile in effect, sostatus.effective, the harness and the export carry the composed rule without further work.
Not chosen. A per-team rule only, which exists already and cannot say what a profile is for whoever uses it. A deny-only field, which would have made "only these three" a list of everything else the bundle and Troupe ship, kept up to date by hand as agents are added. Narrowing primaries alone, as the grant does, which would have left a subagent nobody should have on these pods reachable by any primary that delegates.
Governs: apps/troupe_protocol/lib/troupe/protocol/agent_rule.ex, apps/troupe_plane/lib/troupe/plane/bundles.ex, apps/troupe_core/lib/troupe/agent/definitions.ex, apps/troupe_plane/lib/troupe/plane/fleet/profile.ex, apps/troupe_plane/lib/troupe/plane/fleet/extends.ex, apps/troupe_worker/lib/troupe/worker/plane/commands.ex