Extensions and Capability-Gating#

Alongside the message, every operation carries typed extensions: the contextual state policy reasons about. Identity is an extension. So are security labels, the delegation chain, request headers, agent session context, and more. Each extension is bridged into the flat attribute bag APL reads, under a well-known namespace. Capability-gating controls which plugins may read or write each one.

This is a supporting concern, not the headline. You rarely configure it directly. It matters because it is what makes least privilege real for the plugins that execute policy effects, and because the namespaces below are the exact keys an APL predicate or plugin can read.

The extensions#

Each extension flattens into bag attributes under its namespace, gated by a read capability. A prefix ending in . matches any key beneath it (role. matches role.hr); a bare name is an exact key.

ExtensionCarriesBag namespaceRead capability
Security (subject)subject id and type, roles, permissions, teams, claims, authentication statussubject.id, subject.type, authenticated, subject.roles, subject.permissions, subject.teams, role.*, perm.*, team.*, claim.*read_subject, read_roles, read_permissions, read_teams, read_claims
Security (client)OAuth application identity: client id, trust level, roles, permissions, scopes, audiences, teams, claimsclient.*read_client
Security (workload)attested workload identity (SPIFFE / mTLS) for the inbound caller and for this instancecaller_workload.*, this_workload.*read_workload
Security (labels)taint / classification labels for information-flow controlsecurity.labels, security.classificationread_labels, append_labels
Delegationdelegation depth, delegated flag, origin and actor subjects, chain agedelegation.*, delegatedread_delegation, append_delegation
Agentsession, conversation, turn, and lineage contextagent.*read_agent
Metaentity metadata: type, name, tags, scope, propertiesmeta.*read_meta
Requestenvironment, request id, timestamp, trace and span idsrequest.*read_request
HTTPrequest line (method, path, host, scheme) and request/response headers (lowercased)http.method, http.path, http.host, http.scheme, http.request_headers.*, http.response_headers.*read_headers, write_headers
LLMmodel id, provider, capabilitiesllm.*read_llm
LLM requestthe host-parsed inference request bodynot flattened; OPA, CEL and Cedar read it as llm.requestread_llm_request
MCPtool, resource, or prompt metadatamcp.* (mcp.tool.*, mcp.resource.*, mcp.prompt.*)read_mcp
Completionstop reason, token counts, model, latencycompletion.*read_completion
Provenancesource, message id, parent idprovenance.*read_provenance
Frameworkagentic framework name and version, node and graph ids, metadataframework.*read_framework
Customfree-form host-defined namespacecustom.*read_custom
Raw credentialsinbound tokens and minted delegated tokensflow through plugin payloads, not the bagread_inbound_credentials, read_delegated_tokens
Candidate constraintfolded backend routing constraint from restrict effectsnot a bag namespace; read by the host routerwrite_candidate_constraint

The request arguments and response body are also flattened. An object writes args.<dotted> / result.<dotted>; a top-level scalar or scalar array writes the bare key args / result. The route name is available as route.key. APL field pipelines (args: / result:) operate on those. Operator-maintained static attributes are flattened under data.*. These come from config files, not the request, and need no capability (see Static Attributes).

Most extensions are inputs: resolved before policy runs and flattened into the bag for predicates to read. The candidate constraint is the exception: it is an output. APL restrict effects fold into it (see Backend Restriction), it rides the returned extensions the same way minted delegation tokens do, and the host router reads it typed to prune its candidate set.

Capabilities#

A plugin declares the capabilities it needs. CPEX filters the extensions before handing them to the plugin, so a plugin sees only what it declared. The default is no access; capabilities are additive grants.

plugins:
  - name: audit-log
    kind: acme/audit
    hooks: [cmf.tool_pre_invoke]
    capabilities:
      - read_subject
      - read_client
      - read_delegation

Read capabilities and the bag keys they unlock#

CapabilityUnlocks
read_subjectsubject.id, subject.type, authenticated
read_rolessubject.roles and role.* aliases for undotted members (plus the read_subject baseline)
read_permissionssubject.permissions and perm.* aliases for undotted members (plus baseline)
read_teamssubject.teams and team.* aliases for undotted members (plus baseline)
read_claimsclaim.* (plus baseline)
read_clientclient.*
read_workloadcaller_workload.*, this_workload.*
read_delegationdelegation.*, delegated
read_agentagent.*
read_metameta.*
read_requestrequest.*
read_headershttp.method, http.path, http.host, http.scheme, http.request_headers.*, http.response_headers.*
read_llmllm.*
read_llm_requestno bag keys; gates the parsed request body on the LLM request extension
read_mcpmcp.*
read_completioncompletion.*
read_provenanceprovenance.*
read_frameworkframework.*
read_customcustom.*
read_labelsthe labels on the security extension; a plugin reads them from the extension, while an APL predicate reads security.labels from the bag
read_inbound_credentialsno bag keys; gates raw inbound tokens in the plugin payload
read_delegated_tokensno bag keys; gates minted tokens in the plugin payload

read_roles, read_permissions, read_teams, and read_claims each imply the read_subject baseline (subject.id, subject.type, authenticated). The last three capabilities widen no plugin’s bag view: labels are read from the typed extension, and credential material flows through plugin payloads rather than the bag.

Membership names containing . stay atomic in the canonical sets and get no flattened alias. Test a dotted role with subject.roles contains "admin.readonly"; there is no role.admin.readonly key. The same holds for permissions, teams, and client roles and permissions.

Write capabilities#

Four capabilities grant write tokens rather than read access:

CapabilityGrants
append_labelsadd a taint or classification label (monotonic; cannot remove)
append_delegationextend the delegation chain (monotonic)
write_headersrewrite request and response headers (implies read_headers)
write_candidate_constraintnarrow the backends the router may select

Gating an action: perform_http#

Every capability above gates a slot of contextual state. perform_http gates an action: reaching outside the process at all. It is the one capability where withholding it stops the call rather than degrading it. A plugin denied read_claims sees fewer attributes and carries on; a plugin denied its IdP call and carrying on regardless would decide without the answer it needed, which fails open. The engine therefore refuses to start and names the plugin and the capability to add.

Every plugin that fetches JWKS, exchanges a token, dispatches a CIBA prompt, or queries an HTTP key directory must declare it. The host must also have installed an HTTP transport (see Builtins).

Mutability tiers#

Extensions differ in how they may change during a request, and the runtime enforces the tier:

  • Immutable: fixed once resolved. The verified subject identity, client, workload, agent, meta, request, LLM, LLM request, MCP, completion, provenance, and framework extensions. The LLM request is never serialized, so it stays out of extension dumps and session stores.
  • Monotonic: may only grow. Security labels (added via append_labels, never removed) and the delegation chain (extended via append_delegation).
  • Mutable: may be rewritten. HTTP headers (via write_headers) and the custom namespace.

So a plugin cannot clear a taint label or rewrite a verified identity even if it holds the corresponding read capability. This is what keeps the state APL depends on trustworthy: the model is untrusted, and so is any plugin beyond the context and mutations it was explicitly granted.

How it connects to policy#

Capability-gating runs at the boundary between the engine and each plugin: the engine decides which extension slots a plugin sees, and the CMF extractors then flatten those slots into the bag. The same filtered, tier-enforced view feeds the attribute bag APL evaluates, so a policy and the plugins it invokes operate on a consistent, least-privilege picture of the request. See Identity for how the subject is populated and Session Tainting for the monotonic label tier in action.