Appendix G — Agent Governance Extension (agents 0.1)
This appendix specifies the agent governance extension to CADL. It
builds on the norms extension (Appendix F) and
adds the key agent: to actor_def
(A.3), the keys
enforcement: and delegations: to contract_def
(A.4), and the
key on_denied: to norm_def (F.3). With them, the permissions and
prohibitions of a contract determine, for every message that arrives at
an enforcement point, one of three decisions: allow, deny, or
escalate. The decision is made before the message takes effect, and
it is a function of the message and of the state of the norm instances;
no part of it is left to the judgement of an agent.
The core language does not mandate these blocks; a conforming CADL processor that does not implement the extension MUST NOT reject a file because of the new keys. It SHOULD accept them syntactically and emit an informational diagnostic.
The extension is named agents and this appendix describes version
0.1. It requires norms: 0.1: the norms are what is enforced. A
file that uses it MUST declare both under extensions:
(A.2); G.14 says what
a processor does with an undeclared use.
sos:
...
extensions:
- norms: 0.1
- agents: 0.1
G.1 Motivation
LLM-based agents are becoming constituent systems of SoS, and the protocols that connect them are being standardised [MCP, 2026-07-28] [Linux Foundation, A2A 2025]. Enforcement is converging on deterministic checks at the tool-call boundary; for example, Amazon Bedrock AgentCore Policy authorises tool calls with Cedar policies and denies by default [AWS, AgentCore Policy]. What is missing is the step from an organisational contract (who is allowed to do what, on whose authority) to such a check. Version 0.1 is a first step on four research directions of Section 9.8:
- RD-8.1, compiling contracts to boundary policies. Nothing in a CADL file says which actor is an agent, which message is a tool call, and what a generated policy has to decide (G.4, G.5, G.10).
- RD-8.2, provenance of delegated authority. A check that sees only the local state cannot tell whether an action reached the caller through delegations that its originator was not entitled to make. G.7 gives delegated permissions a provenance chain.
- RD-8.3, recovery after a blocked action. A preprint review reports a study in which blocking 94% of unsafe actions still left fewer than 5% of tasks completed safely and correctly [Dantas+, arXiv 2026]. G.6 defines escalation to a named actor and a fallback message.
- Part of RD-8.4, audit. Community governance has been found to be a layer missing above the protocols [Kang & Diponegoro, arXiv 2026], and a governance graph enforced with an append-only audit log constrained LLM agents where a prompt-only "constitution" did not [Bracale Syrnikov+, arXiv 2026]. G.8 fixes the format of an audit record.
Scope of version 0.1. The extension is small on purpose. It has no primitives for membership, voting, or the preservation of dissent (RD-8.4 otherwise remains open, for a later version); it does not verify plans or the interaction of several agents (RD-8.5), since every decision concerns one message; it maps no article of any regulation to CADL; and it does not cover authentication: the sender and the receiver of a message are taken as given. At the boundary it considers only norms whose content is a message, and only the sender, the receiver, and the name of a message, not its arguments.
G.2 Concepts
| Concept | Meaning in agents 0.1 |
|---|---|
| Tool call | A message whose receiver is an actor of kind tool_server and whose name is one of the tools: of that actor. |
| Enforced contract | A contract that has the key enforcement:. Only enforced contracts take part in decisions. |
| Enforcement point | The one logical place where the decision for a message is made, over all enforced contracts of the file. |
| Decision | allow, deny, or escalate, computed for one message by the decision function of G.5 before the message takes effect. |
| Ground | A prohibition that applies to a message in the decision function. For a hold, grounds are counted per contract instance: a ground of a hold is a prohibition in one contract instance in which it applies (G.6). |
| Hold | The record of a message whose decision is escalate; the message is kept back until the hold reaches a final state (G.6). |
| Derived instance | A permission held by a delegate (G.7), with its provenance chain: the actors from the bearer of the original permission to the holder, one link per delegation. |
| Audit record | What an enforcement point records for one decision (G.8). |
Norm, norm instance, contract instance, institutional event, and observation have the meaning of Appendix F.
G.3 Syntax (EBNF additions to A.3, A.4, and F.3)
The grammar uses the notation of Appendix A,
which defines identifier, hyphen_name, actor_ref, int_literal,
and duration_lit; message_event is defined in
E.3 and norm_event in
F.3.
actor_def = ... , [ "agent:" , agent_binding ] ;
agent_binding = "kind:" , agent_kind ,
[ "protocol:" , hyphen_name ] ,
[ "tools:" , { "-" , identifier } ] ;
agent_kind = "llm_agent" | "tool_server" | "human" | "service" ;
contract_def = ... ,
[ "enforcement:" , enforcement_block ] ,
[ "delegations:" , { "-" , delegation_def } ] ;
enforcement_block = [ "default:" , ( "deny" | "allow" ) ] ,
[ "point:" , ( "caller" | "receiver" | "gateway" ) ] ;
norm_def = ... , [ "on_denied:" , denial_recovery ] ;
denial_recovery = [ "escalate_to:" , actor_ref ] ,
[ "timeout:" , duration_lit ] ,
[ "fallback:" , message_event ] , (* string *)
[ "notify:" , actor_ref ] ;
delegation_def = "norm:" , identifier ,
"to:" , { "-" , actor_ref } ,
"grant:" , identifier ,
[ "revoke:" , identifier ] ,
[ "max_depth:" , int_literal ] ,
[ "until:" , norm_event ] ; (* string *)
- An actor without
agent:has no agent kind. The kindtool_serverdefines tool calls (G.4);llm_agent,human, andservicehave no meaning beyond the static rule that names one of them (G-8) and the use generators make of them.protocol:(mcp,a2a, or another name) has no default and no effect on decisions. Anagent:on an actor declared with a range applies to every actor of the set. - A tool name is an
identifier, because it is the message name of amessage_event. Where the protocol-level name is not an identifier, themappings:of acodegen:entry (A.9) relates the two. - A contract is enforced when it has the key
enforcement:; an empty mapping or a null value (enforcement: {}, or the bare key) means "enforced with all defaults". Whendefault:is omitted, the default decision isdenyfor a tool call andallowfor every other message; when given, it applies to both (G.5). point:(defaultgateway) is a deployment hint for generators and has no effect on the decision. Whatever the deployment, there is one logical enforcement point: every governed message is decided once, over all enforced contracts, on one state.on_denied:is allowed only on a prohibition.timeout:has no default.fallback:andnotify:are data: they are copied into the result of the decision (G.10) and have no other effect.max_depth:defaults to1. Withoutrevoke:a delegation cannot be revoked by a message; withoutuntil:it has no end of its own.
Keys added, by block: actor — agent (kind protocol tools);
contract — enforcement (default point), delegations (norm
to grant revoke max_depth until); norm — on_denied
(escalate_to timeout fallback notify). In an enforced contract
the names approval and rejection are reserved for the institutional
events of G.6.
G.4 Messages and tool calls
A message has a sender and a receiver, each one concrete actor, a
name, and arguments. It is a tool call when its receiver has
agent.kind: tool_server and its name is one of that actor's tools:;
a message to a tool server with any other name is a call of an
undeclared tool; every other message is an ordinary message.
The result that a tool server returns is not a separate message in
version 0.1.
At the boundary, a message_event S -> R : e is matched against
a message on three components: the sender, the receiver, and the
message name (the identifier of e, or the name of the call).
Arguments written in e are not considered in version 0.1:
delete_file and delete_file(path) match the same messages. Each
component is true, false, or unknown, and the match is their Kleene
conjunction: false when any component is false, otherwise unknown when
any is unknown, otherwise true. An actor reference matches a concrete
actor as follows:
| Reference | Matches |
|---|---|
A | the actor A, declared without index; never an indexed member A[k] |
A[3], A[*], A[1..3] | A[3]; every member of the set A; A[1] to A[3] |
A[1..N] (symbolic bound) | every member of the set A; the bounds are not compared |
A[i] | false when the concrete actor is not a member of A. Otherwise: exactly A[v] when the contract instance binds i to v, and unknown when it binds no value to i. |
The table is that of F.3, which the norms
engine uses for the events of a trace, with two differences. First,
F.3 compares the arguments written in a message event with those of the
message, and the boundary does not consider arguments. Second, where
the contract instance binds no value to i, F.3 lets A[i] match
every member of the set, and at the boundary the match is unknown and
is resolved fail-closed (G.5). The second difference also holds for the
events of an enforced contract that the norms engine evaluates, and for
the performer of a power (G.5, "Unknown occurrences").
A[k] is a member of the set A when A is declared with a range
and k lies within its integer bounds (a set declared as A[1..3]
does not contain A[7]); when the declared upper bound is symbolic,
every index from the lower bound on is a member.
G.5 Boundary enforcement of norms
Instances, governed messages, and norms that take part
For an enforced contract without host-created instances, the single instance of F.5 exists from the start of the enforcement point, not from the first observation; this addition to F.5 lets the first message be decided. When a host application creates and ends the instances, the running instances are those it has created and not ended.
Whether an enforced contract governs a message m is decided
before any instance is considered, so no binding is applied to
parties:: a party A[i] or A[*] matches every member of A.
- A message whose receiver is a tool server (a tool call or a call of an undeclared tool) is governed by every enforced contract of which that tool server is a party, whatever its sender: a party, a declared actor that is not a party, or an undeclared actor. Steps 2 to 4 below therefore apply to outsiders too. When a tool server is a party of several enforced contracts, each of them governs every call to it, and a call that one of them does not allow is denied (step 4): contracts that share a tool server each have to permit the calls they intend.
- An ordinary message is governed by an enforced contract when its sender and its receiver each match a party.
A norm still applies only to its bearer or to a valid holder (below). The enforcement point decides the messages one at a time, in the order in which they arrive, each on the state left by all earlier observations, and the decision MUST be deterministic. A decision never depends on a later observation. This holds also for the reading of a bare name in a predicate as a quantity or as a symbolic value (F.5): an enforcement point that is given the quantity names uses them from the start, and one that is not takes a name as a quantity from the first observation on that gives it a value, never earlier.
Only a permission or a prohibition whose content: is a
message_event takes part in a decision. One whose content is a
predicate, a tpredicate with temporal operators, or an institutional
event has no effect at the boundary in version 0.1 and is monitored
under Appendix F only. Obligations and powers do not take part: the
message that an obligation requires, or by which a power is exercised,
is decided like any other, and F.5, item 7 is unchanged.
A norm instance takes part while it is in force at the boundary. The flag is an addition to F.5; the states and verdicts of F.5 are unchanged.
- A permission is in force while its instance is
active. - A prohibition is in force while its instance is
active. When the instance becomesviolated, the prohibition stays in force: the violation is reported once (F.5) but does not lift the prohibition. It then stays in force until the first of: the time at which itsdeadline:window would have closed; the occurrence of itsuntil:; adischargeeffect of a power that names it; an amendment under which it is not carried over (F.6); the end of the contract instance.suspendandresumeeffects that name it put it out of force and back, also after a violation.
A norm instance in force applies to m when its content matches
m (G.4) and the sender of m is its bearer. A derived instance of a
permission (G.7) applies when it is valid and the content matches with
the holder as sender. The result is unknown when the match is unknown
or the enforcement point does not have the flag. Unknown is resolved
fail-closed: an unknown prohibition applies, an unknown permission
does not.
Missing data. The enforcement point also does not have the flag
when it cannot determine it because a quantity has no value yet. This
concerns the trigger: of a prohibition that is inactive and the
until: of a permission that is active, in two forms. Directly:
while that trigger: or until: is a predicate that is undefined
(F.5), the flag is unknown. Through an institutional event: while it
is an event that a counts_as: rule creates from a predicate when:,
and the when: or the if: of such a rule is undefined, the flag is
unknown; with several rules for the event, as long as one of them is
undefined. A quantified predicate or aggregate over an open domain
(F.5, "Quantifiers and aggregates") that the known members do not
decide is undefined in this sense: the members not yet named are the
missing data. While its domain is open, a prohibition whose trigger:
is exists x in A: p therefore always applies: as missing data until
a known member makes p true, and from then on as long as it is in
force, which ends by its until: or otherwise as G.5 describes above. A permission whose until: is for all x in A: p applies only
while a known member makes p false.
Where such a predicate governs the boundary, the contract instance
SHOULD give the bound of the set a value (F.5).
An unknown prohibition applies and an unknown permission
does not. Nothing is latched: the state of the norm instance and its
verdict are those of F.5, where an undefined predicate does not occur;
as soon as the predicates have values, the flag is the one of the
state again. Two cases need no rule, because F.5 already blocks: an
undefined trigger: does not activate a permission, and an undefined
until: does not end a prohibition. A processor SHOULD warn when it
decides a message on a flag that is unknown for this reason. The
consequence at the start is intended: a message that arrives before
the quantities of such a predicate have their first values is denied
or escalated.
One case is not covered. A rule with a message when: and an
if: creates its event at the moment of that message or never. When
the message arrives while the if: is undefined, no event is created
(F.5); that blocks where the event would let a message through, but
where the event would bring a prohibition into force or end a
permission, the boundary does not block, and there is no later moment
at which the flag could be corrected without inventing a state that
F.5 does not have. G-19 warns about such a contract, and a processor
SHOULD warn when it observes such a message.
Unknown occurrences. G-18 requires every index variable of an
enforced contract to be the index of a party, and a contract instance
binds the indices of its parties (F.2). A processor that creates the
instances itself MUST refuse an instance of an enforced contract that
does not bind every index variable of its parties:. So no index is
unbound in a conforming run. The following rule is a second line of
defence for a processor that is handed such an instance all the same.
Where the occurrence of an event of an enforced contract, the value of
one of its predicates, or the identity of the performer of an act
depends on an index that the contract instance does not bind, it is
unknown, and unknown is resolved
fail-closed by what the occurrence would do: an unknown occurrence
never has an effect that lets a message through (it does not activate
or resume a permission, end, suspend, or discharge a prohibition,
create an institutional event, exercise a power, or fulfil an
obligation), and it always has the effects that block (it activates a
prohibition and ends a permission or a derived instance). There is one
exception to "always blocks": a power is the act of a determined
party, so a performer who is unknown exercises no power, also when the
effects of the power would block (activate a prohibition, suspend or
discharge a permission). The exception cannot arise in a processor that
refuses instances without bindings. A processor SHOULD warn. Grant and
revoke messages name no index variable (G-11, G-12) and are never
unknown.
The requirement to refuse an instance is on a processor that creates
contract instances. The policy input of G.10 is a description of
instances that a caller supplies, and it may describe an instance that
binds nothing, as it does when the field instances is absent; the
decision function then takes every match that depends on the index as
unknown (G.4) and resolves it fail-closed as above. The two do not
conflict: the decision for such an input is defined, and a conforming
runtime does not produce such an input.
The decision function
For a message m, the following steps give a result (fields in
G.10), in this order.
- Ungoverned. If no enforced contract governs
m:allow, reasonungoverned. This appendix does not restrict such a message. - Undeclared tool. If
mis a call of an undeclared tool:deny, reasonundeclared_tool. - Per contract. Each governing contract C decides, over all its
running instances:
- If C has no running instance:
deny, reasonno_instance, whenmis a tool call; otherwise as in step 3.4. - If prohibitions of C apply to
m, they are the grounds and the reason isprohibition. C decidesescalatewhen every ground has anon_denied.escalate_to, all name the same actor, and that actor is not the sender ofm; otherwisedeny. Anescalate_to: A[i]is resolved with the bindings of each instance in which the ground applies; an unbound index, or different actors in different instances, givesdeny. - Otherwise, if a permission of C, original or derived, applies
to
m:allow, reasonpermission. - Otherwise the
default:of C or, when it is omitted,denyifmis a tool call andallowif not; reasondefault.
- If C has no running instance:
- Combination (deny overrides). If some contract decides
deny, the decision isdeny. Otherwise, if some contract decidesescalate, the decision isescalatewhen all escalating contracts name the same actor anddenywhen they do not (a hold has a single approver). Otherwise it isallow.
The determining contracts are those that decided deny; if none,
those that decided escalate; if none, all governing contracts. The
reason of the result is, for deny and escalate, the first of
no_instance, prohibition, default that a determining contract
has; for allow, permission if a contract has it, else default.
The result lists the grounds or applying permissions of the determining
contracts and, whenever the reason is prohibition (for deny as well
as for escalate), the fallback and notify of those grounds and
the smallest timeout: among them.
It follows that within a contract a prohibition overrides a permission
(N-12 still warns), that a message governed by two enforced contracts
has to be allowed by both, that a prohibition without escalate_to: is
never escalated, and that an actor cannot approve its own message.
The default differs by kind of message for a reason. Tools are
enumerated and a tool call acts outside the contract, so a closed
policy can be reviewed tool by tool; it is also the default of the
enforcement cited in G.1. Ordinary messages include the coordination
messages on which protocols, lifecycles, and triggers rely; a contract
written for norms 0.1 has no permissions for them, and deny would
stop them all. default: deny closes the policy for them too.
Effect of a decision on the trace
allow. The message takes effect and becomes an observation, with the time of the decision as its time stamp, for the instances of the enforced contracts that govern it. An instance of an enforced contract observes a message only when its contract governs the message: a message that no enforced contract governs (step 1) is an observation for no enforced contract, and a message that one enforced contract governs is no observation for another that does not. So a message cannot trigger, end, or fulfil a norm of an enforced contract, or create an institutional event in it, without having been decided by that contract. It follows that a message event of an enforced contract whose sender or receiver is not a party could never occur: a prohibition with such atrigger:would never come into force, and a permission with such anuntil:would never end. G-17 therefore makes such an event an error. Contracts that are not enforced keep F.5 unchanged.deny. The message does not take effect and is not an observation: it triggers no norm, creates no institutional event, fires no lifecycle transition, fulfils no obligation, and violates no prohibition. The enforcement point SHOULD return the result to the sender.escalate. The message is held (G.6); while held it is not an observation.
The deadlines of Appendix F keep running while a message is denied or
held. Before a message is decided, the enforcement point observes the
time of the decision: an observation that carries no message, at which
F.5 settles every deadline and every window that has passed. A decision
therefore never rests on a prohibition whose window closed, or on an
obligation whose deadline passed, before the time of the decision. A
denied trigger: message does not activate its norm. As an
addition to the verdicts of F.5, a violated obligation has the
verdict excused when, between its activation and the violation, a
message of its bearer that matches its content was denied with the
obligation's own contract among the determining contracts, or was held
on a ground of that contract and not released before the violation:
the contract itself prevented the fulfilment. Its on_violation: still
applies, as for every excused norm.
G.6 Escalation after a denial
on_denied: on a prohibition says what follows when that prohibition
is a ground. fallback: names a message the sender could send instead
and notify: an actor to be informed; both are only copied into the
result. A fallback gives no permission: when sent, it is decided like
any other message. escalate_to: and timeout: define holds.
When the decision is escalate, the enforcement point creates a
hold with a hold_id unique within the enforcement point, the
message, the time of the decision, the grounds, the approver, and a
deadline (the time of the decision plus the timeout of the result, or
none). A ground of a hold is a prohibition in one contract
instance in which it applies to the message. The grounds of a hold are
all of them, over all governing contracts, and their contract instances
are the contract instances of the grounds. A prohibition that applies
in two contract instances is two grounds. A hold without deadline in a contract instance that never ends
is held for ever. How the hold id reaches the approver depends on the
protocol.
| State | Entered when | Closing record (G.8) |
|---|---|---|
held | the hold is created; the only state that is not final | — |
approved | the approver approves; the message is released | allow, reason approved (or the denial of the release) |
rejected | the approver rejects | deny, reason rejected |
expired | the deadline has passed | deny, reason expired, with the deadline as time |
cancelled | a contract instance of a ground ends, or a contract of a ground is amended | deny, reason cancelled |
withdrawn | the host of the enforcement point withdraws the held message, because its sender cancelled it | deny, reason withdrawn |
The approver acts through two institutional events, approval and
rejection, each created by a counts_as: rule from a message of the
approver (G-9), for example when: "OPERATOR -> PLANNER : approve",
creates: approval. As an extension of F.5, where institutional events
"exist only as events", these two carry one value, the hold id: the
first argument of the message that created them. This is the only use
of a message argument in version 0.1. The approver's message is itself
governed and decided by G.5.
The order of steps within one observation (F.5) is extended:
- After step 1: an
approval(rejection) whose hold id names aheldhold, whose performer (F.5, item 7) is the approver of that hold, and which was created in a contract instance of a ground of the hold makes itapproved(rejected). When the hold has several contract instances of grounds, one such event is enough; an event that one message creates in several contract instances is one event. Any otherapprovalorrejectionchanges no hold and SHOULD be recorded as unauthorised. Then the grants, revocations, anduntil:events of G.7 are applied. - In step 6: when a contract instance ends, the
heldholds with a ground in it becomecancelled, before its norms are settled. - After step 6: each hold that became
approvedat this observation is released, in the order of creation.
Release. The message is decided again, on the current state and at the time of the approving observation. The approval stands in for the permission and for the grounds, and for nothing else:
- If the message is now a call of an undeclared tool:
deny, reasonundeclared_tool. - A governing contract that has a ground of the hold denies with the
reason
no_instancewhen a contract instance of one of its grounds is no longer running, and with the reasonprohibitionwhen one of its prohibitions applies in a contract instance in which it is not a ground of the hold (normslists these prohibitions). This includes a prohibition of the grounds that now applies in another contract instance, for example one created after the hold. Otherwise the contract allows: it tests neither a permission nor its default. This is so also when a prohibition of the grounds is no longer in force at the time of the approval, for example after itsuntil:: the approval stands in for the permission in that contract, and the message is released. The reasonno_instancearises only when the approving observation itself ends that contract instance (step 6); an instance that ended earlier has cancelled the hold. The reference runtime does not reach it, because there the end of an instance is an observation of its own (G.13). - Every other governing contract decides in full by step 3 of G.5 and
has to allow, by a permission, original or derived and valid now, or
by its default. A contract that would decide
escalatedenies, with the reasonprohibition. - If no contract denies, the message is released. Otherwise the
release is denied; the result is formed as in step 4 of G.5 from the
contracts that deny:
contractslists them, the reason is the first ofno_instance,prohibition,defaultamong them, and forprohibitionthenorms,timeout,fallback, andnotifyare those of G.10.escalate_toisnull.
A denial of the release is final: it creates no hold, and the hold
stays approved. With these rules a release keeps what G.5 and G.7
state for every other message: a message governed by two enforced
contracts is allowed by both, and no actor acts on an authority that
its originator no longer has. A delegation revoked, a contract instance
ended, or a contract amended between the hold and the approval in a
contract without a ground therefore denies the release. If the message
is released, it
takes effect as the immediately following observation, with
the time stamp of the approving observation, before any other message
is decided. As an addition to F.5, item 3, it is not an occurrence of
the content of a prohibition in a contract instance in which that
prohibition is a ground of the hold: an approved exception does not
violate its grounds. An approval releases one message; a
later message with the same sender, receiver, and name is decided
again.
Hold identifiers. An approval or a rejection names a hold by its
identifier and by nothing else. An identifier need not be
unpredictable: what protects a hold is that only its approver can
close it, through a message that the contract governs, and not the
secrecy of the identifier. An approver's message that is itself held
and released later applies to the hold that has the identifier when
that message is released; if that hold is no longer held, it changes
nothing and is recorded as unauthorised.
Expiry. Before each decision and each observation whose time is
later than the deadline of a held hold, that hold becomes expired.
Holds that expire together do so in the order of their deadlines, and
of their creation when the deadlines are equal. An approval at exactly
the deadline is in time.
Withdrawal. A protocol may let the sender cancel a request while it
is held. The host then withdraws the hold, at the time of the
cancellation and before anything else at that time: a held hold
becomes withdrawn, the message never takes effect, and an approval or
a rejection that comes later changes nothing (not_held). A hold that
is no longer held is not changed by a withdrawal.
G.7 Delegation with provenance
An entry of delegations: makes one permission delegable: norm:
names it, to: lists the actors that may hold a derived instance at
any depth, grant: and revoke: name the messages that delegate and
revoke, max_depth: is the largest number of links in a chain, and
until: is an event that ends every derived instance of the entry.
Only a permission whose content is a message_event can be delegated
in version 0.1; a power cannot.
A derived instance is a permission with the same content, read with
its holder as sender, in one contract instance. Its provenance
chain is a0, …, an: a0 is the
bearer of the original permission, an the holder, and each
pair of neighbours a link made by one grant; the chain of the
bearer is a0 alone. A derived instance is active or
discharged (final). Derived instances are an addition to Appendix F,
which has one instance per norm; there is at most one active
derived instance per norm, holder, and contract instance, so every
holder has one chain.
A derived instance is valid when the original permission is in
force (G.5), the derived instance is active, its chain has at most
max_depth links, and every actor of the chain after the first matches
a reference in to:. While the original is suspended, its derived
instances are not valid.
Grant. A message X -> Y : g, where g is the grant: name of an
entry of a contract that governs it, is decided by G.5 like any other
message. When it is observed, these conditions are tested in each
running instance of the contract:
Xis the bearer and the permission is in force, orXholds a valid derived instance;Ymatches a reference into:;Ydoes not occur in the chain ofX;- the chain of
Xhas fewer thanmax_depthlinks; Yholds noactivederived instance of the permission.
If all hold, a derived instance is created for Y, with the chain of
X followed by Y. If 1 to 4 hold and 5 fails, the grant is a no-op.
If one of 1 to 4 fails, the grant has no effect and SHOULD be recorded
as unauthorised. The granter keeps its instance: delegation shares
authority and does not transfer it.
End. A derived instance becomes discharged when (a) a message
X -> Y : r with the revoke: name of the entry is observed and X
occurs before Y in the chain of Y: the instance of Y and every
derived instance in whose chain Y occurs are discharged; (b) the
until: of the entry occurs, as for the until: of a norm: the
derived instances that are active at that observation are discharged,
and the entry stays delegable; (c) the
original permission becomes discharged or the contract instance ends.
A revoke message that does not satisfy (a) has no effect. A discharged
instance is not revived; a new grant creates a new one.
Because validity is computed from the whole chain, an actor cannot obtain through intermediaries an authority that its originator did not have or no longer has: a grant by an actor without a valid instance creates nothing, a chain is never longer than the contract allows, and revoking one link ends everything derived through it.
Amendments. F.6 governs the norm instances of an amended contract.
This appendix adds two rules: when a new version of an enforced
contract takes effect, (1) every held hold with a ground in that
contract becomes cancelled, and (2) the validity of every derived
instance is tested against the new version; an instance whose
permission has no delegations: entry there, or whose original was
discharged by the amendment, is discharged.
A new version takes effect where a trace says amend, and, from
cadl 0.3.35, at the effective times of the versions of a run given to
cadl agents-run and the gateways
(Appendix K, K.11
and K.9); the rules above apply to both.
G.8 Audit record
An enforcement point SHOULD record every decision and SHOULD keep the records append-only. Recording is a recommendation; the format is normative. An audit record is the result of the decision (G.10) with five more fields:
| Field | Content |
|---|---|
time | The time of the decision, on the clock of the trace. |
message | from, to, and name, as in the policy input. |
instances | The running instances of the governing contracts: contract id and an identifier of the instance. In a closing record: the contract instances of the grounds of the hold, whether they are still running or not. |
hold_id | For an escalate decision and for the record that closes the hold; otherwise null. The identifier is unique within the enforcement point and need not be unpredictable (G.6). |
outcome | In the record that closes a hold, its final state; otherwise null. |
An escalate decision gives two records with the same hold_id: one
when the hold is created and a closing record when it reaches a
final state (table of G.6). The closing record keeps the contracts,
norms, and escalate_to of the hold; when its reason is rejected,
expired, cancelled, or withdrawn, it also keeps the fallback and notify of
the hold, so that the sender finds them in the denial. Its timeout is
null. When the release is denied (G.6), the closing record has the
result of that denial instead, and its outcome is approved. The
time of a closing record is the time of the observation that closed
the hold, except for expired, where it is the deadline; such a record
is written when the expiry is found, before the next decision or
observation, so the times of a log never decrease.
A denial or an escalation that rests on a flag that is unknown (G.5)
has the reason prohibition and lists the norm in norms, like any
other. What distinguishes it is in the policy input of the decision,
where the flag is absent from in_force, and in the warning of the
processor. The remedy of the sender differs: for missing data it is to
wait for the data, not to ask the approver.
Grants, revocations, and acts recorded as unauthorised SHOULD be
written to the same log, as event records, and so SHOULD every
other change of the state on which later decisions rest: the end of a
derived instance for any cause, the start and the end of a contract
instance, and an amendment. An event record has no result; it has the
field event in place of decision, and these fields:
| Field | Content |
|---|---|
time, message | As in an audit record: the observation and the message that the event comes from; message is null when there is none. |
event | grant, revoke, delegation_end (a derived instance ended for another cause than a revoke message; one record per derived instance), instance_start, instance_end, amendment, unauthorised_grant, unauthorised_approval, unauthorised_rejection, or unauthorised_act (an act that F.5, item 7 records as unauthorised); and the events of the host below. |
instances | The contract instance or instances in which the event took place; for amendment, the running instances of the amended contracts. |
norm | For a grant, a revocation, or a delegation_end, the delegable permission as <contract id>.<norm id>; otherwise null. |
chain | For a grant, the chain of the derived instance of the receiver; for a revoke that has an effect, the chain of the revoked instance; for a delegation_end, the chain of the instance that ended; otherwise null. |
holders | The holders whose derived instance the event created or discharged, in the order of creation; otherwise empty. |
hold_id | For an unauthorised approval or rejection, the hold id it carried, if any; otherwise null. |
reason | null for a grant or a revocation that has an effect; holder_exists for a grant that is a no-op (condition 5 of G.7); no_effect for a revoke message that does not satisfy (a); for unauthorised_grant the first condition that fails: no_authority (1), not_in_to (2), in_chain (3), max_depth (4); for an unauthorised approval or rejection unknown_hold, not_held, not_approver, or other_instance (not created in a contract instance of a ground), and, when the host authenticates approvals, unauthenticated, wrong_run, wrong_message, or replayed; for unauthorised_act, no_power; for delegation_end the cause: until, original_discharged, instance_end, or amendment; for instance_end, end or terminal_state; for amendment, the name of the new version; for instance_start, null. |
Records are written in the order in which the enforcement point produces them: the record of a decision, then the event records of the observation that the message becomes, then the closing records of the holds that this observation approved or rejected. A change of the in-force flag of a norm has no record of its own: it follows from the recorded messages, from the times, and from the values that the predicates of the contract read.
The host of an enforcement point MAY record its own events in the same
log, as event records with message set to the message concerned or
null, instances empty, and norm, chain, holders empty: an
approval or a rejection that it refuses before it becomes a message
(unauthorised_approval, unauthorised_rejection, with the reasons
above), another message that it refuses (unauthorised_message), the
evidence of an approval that it accepts (approval_evidence when the
approval was authenticated, approval_unauthenticated when it was not;
reason names the digest of the approval, the digest of the arguments
of the held call, and for an authenticated approval the key id of the
approver and the nonce; written before the decision of the approver's
message), a request that it does not pass on (method_refused, with
the method as reason), a response for which no request is in flight
(unsolicited_response), a call that was allowed or released but
could not be sent (forward_failed), and, at an A2A gateway, a request
without an authenticated sender (unauthenticated_request), a request
that names a task or a context of another client (task_refused), a
request that was sent but got no valid response (invalid_response), a
cancellation of a task that is passed on or withdraws a hold
(task_cancel), a request beyond a limit of the gateway on the
requests handled at the same time (overloaded), a request that was
not read within its deadline (read_timeout), and, from cadl 0.3.28, a
TLS handshake that failed or a client certificate that names no client
(handshake_failed), a push notification configuration that the gateway
gives to the agent or deletes (push_config), one that it refuses
(push_refused), a notification that it relays to the client
(push_sent) or cannot relay (push_failed), and a notification that it
does not relay because it is not authenticated or not of the task of its
configuration (push_dropped), and, from cadl 0.3.36, a change of the
current regime that it accepts (regime_change, with the regime as
reason) or refuses (regime_refused). The reason of regime_refused
is one of five: unauthenticated (the host authenticates the changes and
the file has no valid MAC or nonce, or the host has no key for them),
wrong_run (the file names another run), replayed (its nonce was used
before), no_regimes (the file has no regimes:), and unknown_regime
(a name that is not a regime of the file or, with versions, not a regime
of every version that the run used, uses, or may still use, K.11). The
first three are decided before the regime that the file names is read,
so a change that is not authenticated is recorded with one of them only.
These records change no decision,
and they are only as trustworthy as the host that writes them: a log
replayed from a trace that anyone could write proves nothing about
them.
Integrity of the log. An enforcement point MAY protect its log against later changes with a hash chain. When it does, the log has the format below, so that a verifier that does not know the enforcement point can check it. The chain adds lines and fields; it changes no value of a record.
The log is a file of JSON Lines in UTF-8, each line ended by a line feed. Its first line is a header record, then come the audit records and event records in the order in which they were written, and a complete log ends with an end record:
| Line | Fields before the integrity fields |
|---|---|
| Header | audit_format: "cadl-audit/1". hash: "sha256", or "hmac-sha256" for a keyed log. key_id: in a keyed log, the first 16 hexadecimal digits of HMAC-SHA256(key, cadl-audit key id), otherwise null. run_id: a random identifier of 128 bits of this run of the enforcement point, as 32 lowercase hexadecimal digits. approvals: how the host read approvals, authenticated, insecure, or none, or null when it does not say. source_sha256: the SHA-256 of the bytes of the CADL file, in hexadecimal. epoch: the time of t = 0 as an ISO 8601 time stamp in UTC, or null when the times are those of the trace. |
| Record | The fields of the audit record or event record, in the order of the tables above. |
| End record | audit_end: true. records: the number of records between the header and the end record. |
Every line ends with three integrity fields: seq, the number of
the line, 0 for the header; prev, the digest of the previous line,
64 zeros in the header; and digest, the SHA-256 of the canonical JSON
of the line without its field digest, or in a keyed log its
HMAC-SHA256 with the key, as 64 lowercase hexadecimal digits.
The canonical JSON of a value is defined as follows, so that it does not depend on a programming language.
null,true, andfalseas written.- A number whose value is an integer is written as that integer in
decimal, with a minus sign when it is negative and without leading
zeros; its absolute value is at most 253, and a larger one
is not allowed in a log. Any other number is a finite IEEE 754
binary64 value and is written as the shortest decimal that reads back
to that value, without exponent: digits, a point, digits, with no
trailing zero after the point and one zero before it when the value
is below 1 (
0.5,0.0000001,123.456). NaN and infinities are not allowed. - A string is written between quotation marks in UTF-8. The characters
"and\are written as\"and\\; U+0008, U+0009, U+000A, U+000C, and U+000D as\b,\t,\n,\f, and\r; every other character below U+0020 as\uand four lowercase hexadecimal digits. Every other character is written as itself. A string with a lone surrogate is not allowed. - An array is
[, its elements separated by,, and]. - An object is
{, its members separated by,, and}; a member is its key as a string,:, and its value. The members are in the order of the code points of their keys. An object has no duplicate key.
A line is written in the same way, with two differences: the
members keep their order (the fields of the record, then seq, prev,
digest), and the separators are , and : . A verifier reads each
line, rejects a duplicate key, recomputes the digest from the values,
compares seq and prev with the line before, and requires the line
to be in the written form, so that a change of whitespace, of an escape,
or of the form of a number that leaves the values equal is detected as
well. The key of a keyed log is not part of the log, of the trace, or
of a command line.
What the chain shows has limits, and a verifier MUST know them.
- The header is not authenticated apart from the chain. Without a key, anyone can write a chain that verifies; a keyed log rewritten as an unkeyed one verifies when no key is given. A verifier MUST therefore know from outside the log whether the log is keyed, and give the key when it is.
- Without a key, the chain detects a change of any byte, a line
deleted, inserted, or moved, and a log cut at its tail, which lacks
the end record, as long as the rest of the log is left as it was. It
does not detect a log that is rewritten from a changed line on,
digests and end record included. A line taken from another log does
not fit, because the
run_idof the header differs and with it every digest; two different logs of the same run cannot both verify against the same key and anchor. - With a key, only a holder of the key can write a chain that verifies. A holder of the key can still replace the whole log.
- A log without end record was cut, or its writer did not finish (an enforcement point that is still running, or one that failed); a verifier reports it as such.
An enforcement point SHOULD therefore keep the digest of the last line
of a log, and its run_id, outside the log (an anchor), for
example in a separate system; a verifier that compares the anchor with
the log detects a rewrite, a cut, or a replacement that the chain alone
does not show.
G.9 Static semantics
An agents-aware processor MUST, in addition to the checks of Appendix F:
-
G-1. A file that declares
agents: 0.1MUST also declarenorms: 0.1; otherwise the processor reports an error and does not interpret the keys of this extension. -
G-2. An
agent:mapping MUST havekind:, one ofllm_agent,tool_server,human,service;protocol:MUST be ahyphen_name. -
G-3.
tools:is allowed only for atool_server, which MUST list at least one tool. A tool name MUST be an identifier, not a reserved word, and unique within its actor. (Under a YAML 1.1 loader an unquotedyes,no,on,off,true,false, ornullis not a name; see A.12.) -
G-4. When the receiver of a
message_eventis a tool server, the message name MUST be one of itstools:. This applies to thetrigger:,until:, andcontent:of a norm, thewhen:of acounts_as:rule, theon:of a lifecycle transition, and afallback:. A processor SHOULD warn about a message step of a protocol (A.5) that does not satisfy it. -
G-5.
enforcement.defaultMUST bedenyorallow, andenforcement.pointone ofcaller,receiver,gateway. A null or emptyenforcement:is valid. -
G-6. In an enforced contract, the sender of the
message_eventcontent of a permission or a prohibition MUST be textually equal to itsbearer:. -
G-7.
on_denied:is allowed only on a prohibition whose content is amessage_event, in an enforced contract, and MUST have at least one key.timeout:MUST be aduration_litgreater than zero and requiresescalate_to:. A processor SHOULD warn about anescalate_to:withouttimeout:. -
G-8.
escalate_to:andnotify:MUST name single declared actors (as N-3).escalate_to:MUST name a party of the contract, so that its messages are governed, MUST NOT be textually equal to thebearer:of its prohibition, and SHOULD haveagent.kind: human. -
G-9. A contract with an
escalate_to: AMUST have acounts_as:rule that createsapprovalfrom amessage_eventwhose sender isA, and SHOULD have one forrejection. In an enforced contract, every rule that createsapprovalorrejectionMUST have aswhen:amessage_eventwhose sender is theescalate_to:of a prohibition of the contract, and no normidmay equal either name; these are the only uses that are errors. By G-17 the sender and the receiver of thatmessage_eventare parties of the contract, so the contract governs the approver's message and its instances observe it. A reference to the two events in atrigger:,until:, orcontent:is allowed. -
G-10. A
fallback:MUST be amessage_eventwhose sender is textually equal to thebearer:of its prohibition and whose receiver is a declared actor, and MUST differ from the content of the prohibition in receiver or message name. -
G-11.
delegations:is allowed only in an enforced contract.norm:MUST be theidof a permission of the contract whose content is amessage_event; at most one entry may name a norm. Thebearer:of that permission MUST NOT have an index bound by the contract instance (ROBOT[i]), so that the first actor of every chain can be read from the file. -
G-12.
to:MUST list at least one reference, each naming declared actors; a wildcard or a range is allowed, an index bound by the contract instance is not.to:MUST NOT name a tool server and SHOULD NOT include the bearer.max_depth:MUST be an integer of at least 1.until:MUST satisfy the rules of Appendix F for theuntil:of a norm (N-9, N-10, N-16). -
G-13.
grant:andrevoke:MUST be identifiers and not reserved words. Within a contract, allgrant:andrevoke:names MUST differ from each other and fromapprovalandrejection, and none may be a tool of a tool server that is a party. (The YAML 1.1 note of G-3 applies.) -
G-14. A processor SHOULD warn, in an enforced contract, about a permission or prohibition (a) whose content is not a
message_event, because it has no effect at the boundary, or (b) whosemessage_eventcontent has arguments, because they are not considered. -
G-15. A processor SHOULD warn about (a) a tool of a party of an enforced contract with
default: allowthat no permission or prohibition of the contract covers, and (b) a tool server that is a party of no enforced contract, whose tool calls are ungoverned. A norm covers a message when itsmessage_eventcontent has that receiver and message name. -
G-16. A processor SHOULD warn about a message that a contract needs and would itself deny: (a) the content of an obligation, or a
fallback:, that a prohibition withouttrigger:whose bearer is the sender of that message covers, or that is a tool call covered by no permission of its sender while the default for tool calls isdeny; a message that the sender could send only through a derived permission still gets the warning, because delegations are runtime state; (b) underdefault: deny, agrant:orrevoke:name, or thewhen:message of a rule that createsapprovalorrejection, that no permission covers. -
G-17. In an enforced contract, the sender and the receiver of every
message_eventof the contract MUST be covered by the parties and MUST name declared members only: thetrigger:,until:, andcontent:of its norms, thewhen:of itscounts_as:rules, and theuntil:of its delegations. A reference is covered when one reference inparties:matches every actor that it can name (G.5):Aby a partyA;A[3]by a partyA[3],A[i],A[*], or a range that contains 3;A[1..3]by a partyA[i],A[*], or a range that contains it;A[*]andA[i]by a partyA[i]orA[*], or by a party range that contains the whole declared set. Two party references are not combined: the partiesA[1..2]andA[3]do not coverA[1..3]. A literal index or a range MUST lie within the declared set: for a set declared asA[1..3],A[7]andA[2..5]are errors. An instance of an enforced contract observes only the messages that the contract governs (G.5), so an event that is not covered, or that names no declared member, could never occur for some or all of the actors it names. The receiver of a tool call is included: G-4 requires the tool, and this rule that the tool server is a party. So is its sender: a contract cannot make the tool call of an actor that is not a party the content or the event of a norm. Such a call to a tool server that is a party is governed all the same (G.5); it is decided by the default of the contract and by the norms written for parties, and that is intended. Afallback:is not included: it is data for the sender and no event of the contract, G-10 requires its receiver only to be declared, and a fallback sent to an actor that is not a party is not governed by this contract. -
G-18. In an enforced contract, every index variable MUST be bound. An index variable is a name that is used as an index or inside an index expression (
jinROBOT[j], inROBOT[j+1], and inROBOT[SLOT[j].next]). There are three binders: a reference inparties:binds its index variable for the whole contract (ifor a partyROBOT[i]); a quantifier binds its variable within its predicate (exists j in ROBOT: ROBOT[j].battery < 20, A.10); and a comprehension binds its variable within its element (sum(ROBOT[j].load for j in ROBOT), A.10). Every other index variable is an error, wherever an expression of the contract can stand: in thebearer:and thecounterparty:of a norm; inescalate_to:,notify:, and the sender and receiver of afallback:; in the sender, the receiver, and the arguments of everymessage_eventthat G-17 names, including thecontent:of a norm of any kind; and in every predicate of the contract, which are thetrigger:,until:, andcontent:of its norms, thewhen:andif:of itscounts_as:rules, theuntil:of its delegations, and itsassume:andguarantee:items. The contract instance binds the index variables of its parties (F.2) and no others; a variable without a binder has no value that the file accounts for: by F.3 an event or a power with such a variable would hold for every member of the set, and a predicate with it would read a quantity that no actor has. That a quantifier binds its variable makes the predicate valid; whether a processor can evaluate it is a separate matter (G.13). -
G-19. A processor SHOULD warn, in an enforced contract, about an institutional event that a
counts_as:rule creates under anif:and that is thetrigger:of a prohibition or theuntil:of a permission. When thewhen:of the rule is a message that arrives while theif:is undefined, the event is not created and the boundary does not block (G.5, "Missing data").
The MUST rules are errors; the SHOULD rules are warnings and leave the file valid. N-1 to N-12 of Appendix F apply unchanged.
G.10 Code generation
Two code targets generate a boundary policy from the enforced contracts
of a file. They are listed in
Appendix D in the category Boundary
policy: agent-rego emits Rego
[Open Policy Agent] and is independent of
the opa target, which emits one policy per contract from other parts
of the contract; agent-cedar emits Cedar policies
[AWS, AgentCore Policy]. The syntax of
the policies and the layout of the files belong to the targets.
// policy input
{ "message": { "from": "SUMMARIZER", "to": "FILES", "name": "read_file" },
"now": "2026-11-10T09:00:05Z",
"instances": [
{ "contract": "ASSISTED_REPORTING", "instance": "default",
"bindings": {},
"in_force": {},
"derived": [ { "norm": "may_read", "holder": "SUMMARIZER",
"chain": ["OPERATOR", "PLANNER", "SUMMARIZER"] } ] } ] }
// result
{ "decision": "allow", "reason": "permission",
"contracts": ["ASSISTED_REPORTING"],
"norms": ["ASSISTED_REPORTING.may_read"],
"provenance": [["OPERATOR", "PLANNER", "SUMMARIZER"]],
"escalate_to": null, "timeout": null, "fallback": [], "notify": [] }
Input:
message(required):fromandtoare concrete actors written as in the file (PLANNER,ROBOT[2]);nameis the message name. Arguments are not part of the input.now(optional): the time of the decision; it does not influence the decision.instances(optional): every running instance of every enforced contract; a contract without an entry has no running instance. When the field is absent, the policy assumes one running instance of each enforced contract, with no index bound and no derived instance; a match that depends on an index is then unknown (G.4, and G.5 for the relation to the instances a runtime creates). Per instance:bindingsmaps index names to integers;in_forcemaps theidof each norm that is not static (below) totrueorfalse, and a missing entry is unknown;derivedlists the derived instances that the runtime found valid by G.7, with their chains.regime(fromcadl0.3.36; required for a file in which a regime ofregimes:does not have an enforced contract in force, and read only for such a file): the current regime (Appendix A, A.7.1). A contract that the regime does not have in force governs no message (F.5, "Contracts not in force"); an input without a regime of the file does not have the form of a policy input.cadl agents-decide,agent-rego, andagent-cedar(where the request carries it ascontext.regime, and a forbid policyregimedenies a request without a regime of the file) read it. Fromcadl0.3.36cadl agents-runand the gateways follow the current regime too and give it in every policy input they build (G.13); in 0.3.33 to 0.3.35 they refused such a file. The decision function and both policies are compared on random files with regimes in the tests ofcadl0.3.36: 10560 inputs on two files for each policy with the default count, and 52800 inputs on ten files in a longer run (CADL_REGIME_TARGET_TRACES=10), without a difference.- A
derivedentry is re-checked fail-closed. It applies only if its norm is a delegable permission of that contract, the holder is the sender of the message and the last element of the chain, the chain has at mostmax_depthlinks, its first element matches the bearer and every later one a reference into:, and the original permission is in force (static, or flagtrue; a missing flag does not count). Any other entry is ignored.
For an input that does not have this form no decision is defined: a processor reports an error, and a generated policy denies.
Result:
decision:allow,deny, orescalate.reason: one ofungoverned,undeclared_tool,no_instance,prohibition,permission,default; in a closing record (G.6) alsoapproved,rejected,expired,cancelled,withdrawn.contracts: theids of the determining contracts (G.5); empty forungovernedandundeclared_tool.norms: the grounds (reasonprohibition) or the applying permissions (reasonpermission) of the determining contracts, each as<contract id>.<norm id>, each once, in the order of declaration; empty for the other reasons.provenance: the chains of the applying derived instances, in the order of their norms and then of the input, without duplicates; empty when only original permissions applied.escalate_to: the approver forescalateand in a closing record that keeps it (G.8), as a concrete actor; otherwisenull.timeout(milliseconds),fallback(message events as text), andnotify(actor references) are filled whenever the reason isprohibition, fordenyas well as forescalate, from the grounds, without duplicates, in the order of declaration; for every other reason they arenull,[], and[], except that a closing record with the reasonrejected,expired,cancelled, orwithdrawnkeeps thefallbackandnotifyof its hold (G.8).
A norm is static when it is a permission or a prohibition whose
content is a message_event, it has no trigger:, until:, or
deadline:, no power names it in effects:, no norm names it as
reparation:, and no actor reference of the norm has an index bound by
the contract instance: its bearer, counterparty, and content, its
escalate_to and notify, and the sender and receiver of its
fallback. By G.5 a static norm is in force in every running
instance from its start to its end, so the input carries no flag for
it. A policy is generated for one version of the contracts; an
amendment requires a new policy.
A generated policy MUST return, for every input, the same decision as
the decision function of G.5, with static norms taken as in force, the
other flags and the derived instances taken from the input, and
everything the input does not supply taken as unknown. A target whose
policy language has only two outcomes returns deny where G.5 gives
escalate. The other result fields MAY be produced by the policy or by
the runtime, from a table that the generator emits beside the policy
(per prohibition: escalate_to, timeout, fallback, notify). A
generator MUST list in the generated artifact, as needing runtime
state, each permission or prohibition with a message content that is
not static, and separately, as having no effect at the boundary, each
permission or prohibition with another content; norms of other kinds
are not listed. Holds, release, and the bookkeeping of delegations (G.6, G.7)
belong to the runtime, not to the policy.
For the example of G.12 with only message in the input (informative):
message | Result |
|---|---|
PLANNER -> TICKETS : search_tickets | allow, permission, may_search (static permission) |
PLANNER -> FILES : delete_file | escalate to OPERATOR, prohibition, no_delete |
PLANNER -> FILES : format_disk | deny, undeclared_tool |
SUMMARIZER -> FILES : read_file | deny, default; with the derived entry shown above, allow, permission |
Cedar mapping (informative). In Cedar
[Cutler+, OOPSLA 2024] a request is
denied unless a permit policy is satisfied, a satisfied forbid
policy overrides every permit, and a policy whose evaluation raises an
error is skipped. Undeclared tools and prohibitions therefore become
forbid policies, permissions permit policies, and the default for
tool calls is the default denial of the language; escalate is
returned as a denial and resolved by the runtime from the emitted
table. Because an erroring forbid policy would be skipped and so
would not deny, a generated policy must not raise an error on any
input of the schema above: it tests the presence of every optional
attribute before reading it. Messages that G.5 allows without a
permission (ungoverned messages, a contract whose default is allow)
need explicit permit policies, and with more than one enforced
contract, deny-overrides across contracts needs an additional forbid
policy per contract for what that contract does not allow. From the
Cedar answer alone, a denial by such a policy or by the language
default cannot be told apart from "a non-static or derived permission
might allow"; the Cedar target therefore covers static norms only, and
the runtime decides the rest.
Precisely, the Cedar policies decide a message as the decision function
decides an input with only message on the enforced contracts without
their norms that are not static. Their answer, with Deny for deny and
escalate, is the decision for a policy input in these cases:
- an Allow by the policy for ungoverned messages, or a Deny by the
forbidpolicy of an undeclared tool, for every input; - a Deny by the
forbidpolicy of a static prohibition, when its contract has a running instance in the input or the message is a tool call; a contract without a running instance decides another message by its default (G.5, step 3.1), so this Deny is not final there; - any answer, when every enforced contract that governs the message
has a running instance, no norm of these contracts that is not
static can match the message (its content and its bearer, with an
index bound by the contract instance counted as a match), and no
derivedentry of these contracts in the input is of a permission with the name of the message whose holder is the sender.
In every other case the runtime decides with the decision function. A generator for Cedar SHOULD state these cases in the generated artifact.
G.11 Mapping to agent protocols (informative)
The decision function does not depend on a protocol. This section
gives the correspondence with two protocols for agents: the Model
Context Protocol, revision 2026-07-28
[MCP Specification 2026-07-28], and the
Agent2Agent protocol, version 1.0.0
[A2A Specification 1.0.0]. The reference
implementation has a gateway for MCP and, from cadl 0.3.25, one for the
JSON-RPC binding of A2A, from 0.3.28 also for its HTTP+JSON binding and,
as an optional extra, its gRPC binding (G.13). Nothing normative depends
on this section.
| CADL (agents 0.1) | MCP 2026-07-28 | A2A 1.0.0 |
|---|---|---|
kind: tool_server; tool; tool call | An MCP server; a tool of tools/list; a tools/call request | — |
kind: llm_agent | An MCP client, when it calls tools | An A2A agent, as client and as server |
| Ordinary message between agents | — | A SendMessage request from one agent to another |
| Name of the message | params.name of tools/call | Not carried by the protocol; taken from an extension (below) |
point: gateway | A proxy between client and server. Over Streamable HTTP the headers Mcp-Method and Mcp-Name name the method and the tool; a gateway may decide on them without parsing the body only when the server rejects a request whose headers differ from its body (HeaderMismatch). Over stdio the gateway parses the body | An intermediary between the agents |
deny | A tool result with isError: true | A task in the state TASK_STATE_REJECTED |
escalate, hold id, approver | Outside the protocol | Outside the protocol |
MCP. A gateway sits between an MCP client, which is the actor that
sends the tool calls, and an MCP server, which is a tool server of the
file. A tools/call with the name n from the client of actor A to
the server of actor S is the message A -> S : n at the time of its
arrival. MCP has no authenticated field that names the sender: the
clientInfo of _meta is declared by the client itself. Over stdio,
one gateway process serves one client, and which actor that client is
belongs to the configuration of the gateway. The arguments of the call
are not part of the message (G.4).
allow: the request is forwarded, and the response of the server comes back.deny: the gateway answers with a tool result withisError: truewhose text names the reason, the norms, the hold, and thefallbackandnotifyof the result. MCP distinguishes errors of tool execution, which a client gives to the model so that it can correct itself, from protocol errors, which are meant for requests that the model is unlikely to correct. A denial is of the first kind: the sender can act on it, for example by sending the fallback.escalate: the request is held and the client gets no answer yet. MCP lets a client have several requests in flight, so a held call does not block the others. When the hold closes, a released call is forwarded, and any other closing (G.6) is answered as a denial. A client that cancels a held request (notifications/cancelled) withdraws it (G.6).
Methods other than tools/call are not governed by norms: the
decision function has nothing to decide for them. A gateway therefore
passes them only when they are explicitly allowed, and refuses every
other method, of the client or of the server, with a JSON-RPC error;
it SHOULD record the refusal (method_refused, G.8). The methods of
the lifecycle and of discovery, and tools/list, are the ones that a
client needs to call tools at all. Under MCP 2026-07-28 a server sends
no requests and a client sends no responses on stdio; earlier revisions
let a server ask the client for sampling or elicitation, and a gateway
passes such requests only when they are allowed. A response passes only
for a request that is in flight in the other direction; a response for
a held or a denied call, which the server never received, is dropped.
A gateway reads a message once and passes on what it has read, never the bytes it received. A line that a reader of the other side could split differently, for example at a carriage return, would otherwise let a request pass that the gateway never decided; a line that is not one JSON-RPC message without duplicate keys is refused.
A tools/list result can be reduced to the tools that the file
declares for the server: a call of another tool is denied by step 2 of
G.5 anyway. The approver's message (G.6) and the messages between
agents, such as grants (G.7), do not pass through an MCP gateway; they
reach it through a channel of the deployment, which has to
authenticate who speaks: an approval is authenticated with a key of
the approver and bound to the run, to the hold, to the held message,
and to its arguments, and is used once. The decision does not depend on
the arguments (G.4), but the approver has to see them to know what is
approved. Keys separate approvers only when each approver's key is out
of reach of everyone else: approvers, or an agent, that share the
account of the gateway can read every key it holds, so each approver
needs an account of their own, or a channel that authenticates the
approver in another way. A channel of files protects only against
parties that cannot read the key files. A cancellation of a call that
has already been forwarded is passed on, and the call stays in flight,
because the server may still answer it. Under MCP 2026-07-28, a server can answer
tools/call with a result that asks for more input, and the client
then sends the call again as a new request; the gateway decides it
again, as G.6 says of a message sent again.
A2A. A2A connects agents with each other; a request SendMessage
of agent X to agent Y carries a Message with role, parts,
messageId, and optionally contextId, taskId, metadata, and
extensions. A gateway in front of Y, for any of the bindings of
A2A (JSON-RPC, gRPC, HTTP and JSON), maps such a request to the message
X -> Y : e as follows. A SendStreamingMessage is the same message,
decided before any event of the stream is passed on. From cadl 0.3.25
the reference implementation does so for the JSON-RPC binding, from
0.3.26 also for its streams, and from 0.3.28 for the HTTP+JSON and the
gRPC bindings; G.13 gives its readings.
- X is the authenticated client of the request: A2A authenticates the client by the security schemes of the agent card of Y, one of which is mutual TLS, and the gateway maps the identity to an actor of the file. Without an authenticated identity there is no sender, and the message is denied.
- A2A messages have no name of an operation. The name e and its
arguments, such as the hold id of an approval, come from an
extension: the message lists the extension's URI in
extensionsand carries{"name": "approve", "args": ["h-1"]}under that URI inmetadata. A message without the extension has no name and is denied. allow: the request is forwarded.deny: the gateway answers with a task in the stateTASK_STATE_REJECTED, which A2A defines as "the agent has decided to not perform the task", whose status message names the reason and the fallback.escalate: the gateway does not forward the request; a blockingSendMessagewaits until the hold closes, and withreturnImmediatelythe gateway answers with a task of its own inTASK_STATE_SUBMITTEDand settles it later, as forwarded or rejected. The statesTASK_STATE_INPUT_REQUIREDandTASK_STATE_AUTH_REQUIREDdo not fit a hold: they ask the sender for input, whereas a hold waits for the approver.- The approver's approval can itself be an A2A message of the approver
with the name
approveand the hold id as its first argument, as in G.12; it is decided like any other message (G.6). Such a message names only the hold, so it has to be bound to the held message and its arguments as an approval through another channel is (above); the reference gateway does not accept approvals as A2A messages (G.13). - Push notifications carry no message between actors: the agent sends
the events of a task to a URL that the client registered. A gateway
that relays them sends requests to addresses that its clients choose,
from inside the network it protects, which is server-side request
forgery unless the URLs are restricted; A2A asks the caller of a
webhook to validate its URL and suggests allowlists (A2A 13.2). A
gateway passes a notification only for a task of the client that
registered it, as it passes
GetTask.
G.12 Example
A human operator asks an LLM planner to prepare a report. The planner calls the tools of two tool servers and uses a sub-agent to summarise files. The file satisfies every rule of this appendix and N-1 to N-12 of Appendix F.
sos:
name: "AssistedReporting"
extensions:
- norms: 0.1
- agents: 0.1
actors:
- id: OPERATOR
role: "Human operator who owns the task and the files"
agent: { kind: human }
- id: PLANNER
role: "LLM agent that plans the report and calls tools"
agent: { kind: llm_agent, protocol: a2a }
- id: SUMMARIZER
role: "LLM sub-agent that summarises files for the planner"
agent: { kind: llm_agent, protocol: a2a }
- id: FILES
role: "File store"
agent: { kind: tool_server, protocol: mcp, tools: [read_file, delete_file] }
- id: TICKETS
role: "Issue tracker"
agent: { kind: tool_server, protocol: mcp, tools: [search_tickets, create_ticket] }
contracts:
- id: ASSISTED_REPORTING
parties: [OPERATOR, PLANNER, SUMMARIZER, FILES, TICKETS]
enforcement:
point: gateway # default: omitted -> deny tool calls, allow other messages
counts_as:
- { when: "OPERATOR -> PLANNER : approve", creates: approval }
- { when: "OPERATOR -> PLANNER : reject", creates: rejection }
norms:
- id: may_read
kind: permission
bearer: OPERATOR
content: "OPERATOR -> FILES : read_file"
- id: may_search
kind: permission
bearer: PLANNER
content: "PLANNER -> TICKETS : search_tickets"
- id: may_file_ticket
kind: permission
bearer: PLANNER
content: "PLANNER -> TICKETS : create_ticket"
- id: no_delete
kind: prohibition
bearer: PLANNER
content: "PLANNER -> FILES : delete_file"
on_denied:
escalate_to: OPERATOR
timeout: 10min
fallback: "PLANNER -> TICKETS : create_ticket"
notify: OPERATOR
delegations:
- norm: may_read
to: [PLANNER, SUMMARIZER]
grant: grant_read
revoke: revoke_read
max_depth: 2
The contract has no lifecycle: block and no host creates instances,
so its single instance, here called default, exists from the start of
the enforcement point. The four norms have no trigger: they are in
force from the start, and all four are static (G.10). The permission to
read belongs to the operator; the planner and the sub-agent read only
through a delegation, over at most two links.
At 09:00:00 the operator sends OPERATOR -> PLANNER : grant_read, and
at 09:00:02 the planner sends PLANNER -> SUMMARIZER : grant_read.
Both are ordinary messages to which no norm applies, so the default
allows them. The first creates a derived instance of may_read for
PLANNER with the chain OPERATOR → PLANNER, the second one for
SUMMARIZER with the chain OPERATOR → PLANNER → SUMMARIZER. A further
SUMMARIZER -> PLANNER : grant_read would be recorded as unauthorised:
PLANNER occurs in the chain of SUMMARIZER (condition 3), which
already has two links (condition 4).
Call 1 — allowed through a chain. At 09:00:05 the sub-agent sends
SUMMARIZER -> FILES : read_file. The message is governed and the tool
is declared. No prohibition applies: the sender is not the bearer of
no_delete. The derived instance of SUMMARIZER is valid (may_read
is in force, the chain has two links, its actors are in to:), and its
content, read with the holder as sender, matches: allow.
Call 2 — escalated and approved. At 09:03:00 the planner sends
PLANNER -> FILES : delete_file. no_delete is in force and applies;
it is the only ground and its escalate_to: is not the sender, so the
decision is escalate. The hold h-1 is created with the approver
OPERATOR and the deadline 09:13:00. At 09:03:40 the operator sends
OPERATOR -> PLANNER : approve("h-1"), an ordinary message that the
default allows. After step 1 of that observation the event approval,
performed by OPERATOR, carries the hold id h-1, and the hold
becomes approved. After step 6 the message is decided again: the
tool is declared, the instance of the ground is running, no prohibition
applies outside the grounds, and no other enforced contract governs the
call, so the held message becomes the next observation, with the time
stamp 09:03:40. It
is not an occurrence of the content of no_delete, which stays
active. Had the operator sent reject("h-1"), or nothing until
09:13:00, the closing record would be a deny with the reason
rejected, or expired with the time 09:13:00; the planner would find
the fallback in the result, and may_file_ticket allows that call.
Call 3 — denied after a revocation. At 09:10:00 the operator sends
OPERATOR -> PLANNER : revoke_read. OPERATOR occurs before PLANNER
in the chain of PLANNER, so the instance of PLANNER is discharged,
and with it the instance of SUMMARIZER, in whose chain PLANNER
occurs. At 09:10:30 the sub-agent sends SUMMARIZER -> FILES : read_file. No prohibition applies; SUMMARIZER holds no valid
permission, and the original may_read does not apply because the
sender is not its bearer; the message is a tool call and default: is
omitted, so the contract denies. The sub-agent cannot keep an authority
that the planner no longer has.
The audit records of the three calls (the two of call 2 share the hold
h-1). In all four, instances is the instance default of
ASSISTED_REPORTING and contracts is ["ASSISTED_REPORTING"]; the
first record of call 2 is written out below the table.
time | message | decision | reason | norms | provenance | hold_id | outcome |
|---|---|---|---|---|---|---|---|
| 09:00:05 | SUMMARIZER, FILES, read_file | allow | permission | may_read | OPERATOR, PLANNER, SUMMARIZER | null | null |
| 09:03:00 | PLANNER, FILES, delete_file | escalate | prohibition | no_delete | — | h-1 | null |
| 09:03:40 | PLANNER, FILES, delete_file | allow | approved | no_delete | — | h-1 | approved |
| 09:10:30 | SUMMARIZER, FILES, read_file | deny | default | — | — | null | null |
{ "time": "2026-11-10T09:03:00Z",
"message": { "from": "PLANNER", "to": "FILES", "name": "delete_file" },
"instances": [ { "contract": "ASSISTED_REPORTING", "instance": "default" } ],
"decision": "escalate", "reason": "prohibition",
"contracts": ["ASSISTED_REPORTING"],
"norms": ["ASSISTED_REPORTING.no_delete"], "provenance": [],
"escalate_to": "OPERATOR", "timeout": 600000,
"fallback": ["PLANNER -> TICKETS : create_ticket"], "notify": ["OPERATOR"],
"hold_id": "h-1", "outcome": null }
G.13 IR addition and reference implementation status
The simulator IR (E.7, F.9) is extended in three places; as there, it is a direct serialization of dataclasses and flattens nested blocks.
// each actor under institution.actors
{ "id": "FILES",
"agent_kind": "tool_server", // null for an actor without agent:
"agent_protocol": "mcp",
"agent_tools": ["read_file", "delete_file"] }
// each contract under institution.contracts
{ "enforced": true,
"enforcement_default": null,
"enforcement_point": "gateway",
"norms": [
{ "id": "no_delete", // ... and the fields of F.9
"on_denied_escalate_to": "OPERATOR",
"on_denied_timeout_ms": 600000,
"on_denied_fallback": "PLANNER -> TICKETS : create_ticket",
"on_denied_notify": "OPERATOR" } ],
"delegations": [
{ "norm": "may_read", "to": ["PLANNER", "SUMMARIZER"],
"grant": "grant_read", "revoke": "revoke_read",
"max_depth": 2, "until": null } ] }
enforced is true when the contract has the key enforcement:, also
with a null or empty value. enforcement_default is null when
default: is omitted, because the default then depends on the kind of
message; applying it is left to the consumer. enforcement_point is
filled in for an enforced contract (gateway) and null otherwise;
max_depth is always filled in (1). fallback and until are kept
as text. agent_tools and delegations are empty lists when there is
nothing to list, and the four on_denied_* fields are null for a
norm without on_denied:. All fields shown here (agent_*,
enforced, enforcement_*, delegations, on_denied_*) are present
only when the file declares agents: 0.1; a file that declares only
norms: 0.1 has exactly the IR of F.9.
Reference implementation. cadl 0.3.20 implements agents 0.1 as
follows. It parses the four new keys, applies G-1 to G-16 in
cadl check (the SHOULDs as warnings; G-17 to G-19 from cadl 0.3.22), and lowers the blocks to the IR
above; a timeout: given as a bare number is read as seconds, the
lenient form that
A.12
describes for deadlines. cadl agents-decide implements the decision
function of G.5 over the policy input of G.10. It is stateless: the
in-force flags and the valid derived instances come in through the
input. cadl codegen -t agent-rego emits a Rego policy that returns
the full result, and -t agent-cedar emits Cedar policies for the
static norms with a side table.
Runtime. cadl 0.3.22 adds
cadl agents-run FILE --trace TRACE [--audit OUT.jsonl], a reference
runtime for G.5 to G.8. It is deterministic and offline: it replays a
recorded sequence of messages through one enforcement point over all
enforced contracts of the file, and its only clock is the time of the
trace. For each message it takes the in-force flags from the verdict
engine of cadl norms-eval (F.10), the valid derived instances from
the grants and revocations observed so far, and the running contract
instances from the trace; it builds the policy input of G.10 from them
and calls the decision function of cadl agents-decide. It then
applies the decision as G.5 says, keeps the holds and the derived
instances (G.6, G.7), decides an approved message again before it
releases it, and writes the audit records and event records of G.8, as
JSON Lines when --audit is given. Hold ids are h-1,
h-2, and so on, in the order of creation.
Integrity and online use. cadl 0.3.24 writes the audit log in
the format of G.8, "Integrity of the log": --audit gives a chain of
SHA-256 digests, and --audit-key FILE keys it with HMAC-SHA256 with
the key in FILE (at least 16 bytes); only the Python standard library
is used. The run_id of the header is the key run_id of the first
line of the trace when it has one, and random otherwise, so that two
runs of the same trace differ in the header and the digests unless the
trace names its run: a replay is reproducible byte for byte only with
run_id on the first line. The key approvals of the first line is
copied into the header. agents-run accepts withdraw and
host_events from any trace, so in a log replayed from a trace the
host's event records are what the trace says, and prove nothing more. cadl audit-verify AUDIT.jsonl [--key FILE] [--source FILE.cadl] [--run-id HEX] [--anchor DIGEST] [--open] reports
the first line that does not verify, with the expected and the found
value; --source also requires the hash of the CADL file, --run-id
the run, --anchor the digest of the last line kept elsewhere, and
--open accepts a log without end record. The exit status is 0 for a
valid log, 1 for an invalid one, and 2 for a usage error, among them a
keyed log without key. The values of the records, and the order of
their fields, are those of 0.3.23; a number that is not an integer is
written in the canonical form of G.8, without exponent. The same
release makes the runtime usable online: an enforcement point is
opened on a file, each trace line is given to it when it happens, and
closing it is the line {"t": t} at the end; cadl agents-run is a
loop over the same steps.
MCP gateway. cadl mcp-gateway FILE --agent A --server-actor S --audit OUT.jsonl -- COMMAND (0.3.24) is the MCP gateway of G.11 over
the stdio transport of MCP 2026-07-28: JSON-RPC 2.0, one message per
line. It starts the server with COMMAND and speaks to the client on its
own standard input and output. Its readings of G.11 are these.
- Every line, in both directions, is parsed strictly: a carriage
return other than one trailing CRLF, invalid UTF-8, a duplicate key
at any depth, NaN, an infinity or a number that overflows to one
(
1e999), nesting deeper than 100 arrays or objects, or a lone surrogate makes it invalid (JSON-RPC errors -32700 or -32600), and it is not passed on. What is passed on is the compact JSON of the parsed object with every non-ASCII character escaped. - Everything that can fail is done before a call is decided: the line
to send and the SHA-256 of the canonical JSON of its
params(arguments without a canonical form, such as an integer beyond 253, are refused with -32602). If sending fails after an allow or a release all the same, the client gets -32603 and the log the eventforward_failed; held calls that a failure denies are withdrawn in the runtime first, while it can still record. - Allowed without
--allow-method:initialize,notifications/initialized,ping,server/discover,notifications/cancelled,notifications/progress,tools/list, andtools/call, which alone is decided. From the server the notificationsnotifications/progress,notifications/message,notifications/cancelled, andnotifications/tools/list_changed. Every other method, of the client or of the server, is refused with -32601 and recorded asmethod_refused. - A tool call is decided at the time of its arrival, and calls are
decided one at a time in the order of arrival. A denial is a tool
result with
isError: true.tools/listresults keep only the declared tools, unless--no-filter-toolsis given. A response passes only for a request in flight in the other direction; any other is dropped and recorded asunsolicited_response. A cancelled held call is withdrawn: the trace says"withdraw": ["h-1"]. - The gateway fails closed: when the decision step raises or the trace or the log cannot be written, the call is denied and so is every later call, and the log gets no end record. When the server exits, the requests in flight and the held calls are answered with the error -32603.
- Approvals, rejections, and other messages come through a directory
that belongs to the user of the gateway and that nobody else can
write; only regular files with one link of that user are read. With
--approver-keys KEYS.jsonevery file is authenticated with HMAC-SHA256 under the key of the actor that speaks, over the canonical JSON of G.8.cadl mcp-approve DIR HOLD_ID approve|reject --as ACTOR --key FILEshows the held call with its arguments and writes an approval that names the run, the hold, the held message, the time of the hold, and the SHA-256 of the arguments, which the gateway publishes in the directory, and a fresh nonce. The gateway turns it into the approver's message of thecounts_as:rule that createsapproval(rejection), with the hold id as its first argument, after the event recordapproval_evidence, whose reason names the SHA-256 of the file and of the arguments, the key id of the approver, and the nonce. A file whose MAC does not verify, which names another run or another held message, or whose nonce was used before, changes nothing and is recorded asunauthorised_approvalwith the reasonunauthenticated,wrong_run,wrong_message, orreplayed.cadl mcp-message DIR 'X -> Y : n' --key FILEwrites any other message, such as a grant, authenticated with the key of its sender. Without keys the gateway refuses the directory unless--insecure-approvalsis given, which is for tests; an approval accepted that way is recorded asapproval_unauthenticated. The first line of the trace and the header of the log say which mode the run used (approvals). - The time is that of a monotonic clock since the start, in seconds
rounded to milliseconds, and the first line of the trace gives a
random
run_idand the wall-clock time oft = 0asepoch. The gateway writes every step to the trace before it decides it: each decided message, a line{"t": t}when the deadline of a hold has passed, the lines withwithdrawandhost_events, and a last line{"t": t}when it stops.cadl agents-runon that trace makes the same decisions and writes the same audit log, byte for byte.
The tests of the chain alter every byte of two logs of ten lines, one
unkeyed and one keyed (about 5 100 bytes each), in two ways each; all
20 434 altered logs fail verification. So does every deletion of a
line, every insertion of a line of the same or of another log, every
exchange of neighbouring lines, every cut of the tail, a rewritten
header, a duplicate key, whitespace, an escape, or the form of a number
changed without changing a value, a log of another CADL file or of
another run checked against this one, and a rewritten or cut log
checked against its anchor. A rewrite of the whole log passes without
a key and fails with one, and a keyed log rewritten as unkeyed passes
when no key is given, as G.8 states. The gateway is tested with a fake
MCP server and a fake client in separate processes, without network,
and in process with a fake clock: on the scenarios of G.12 (allow, deny
without permission, undeclared tool, escalation that is approved,
rejected, or expires with its fallback, grant and delegated call, and
revocation), malformed input, a server that exits, a client that
disconnects with a held call, approvals that cannot be read or name
another hold, and two calls in flight while a third is held. An
independent review of the first version of the gateway found that a
client could hide a complete tools/call inside another message with
bare carriage returns, which a server that reads with universal
newlines executed without a decision and without a record; that
duplicate keys were read last-wins by the gateway and could be read
first-wins by a server; that a tool name with a trailing line feed
stopped the gateway; that every method other than tools/call was
passed undecided; that the server could answer a held call; that the
inbox followed links and could be written by others; that a lone
surrogate in an approval stopped the gateway; that approvals were not
authenticated; and that a call cancelled and then approved was recorded
as released. Each is corrected, and each has a test that failed before
the correction: the line is parsed strictly and passed on re-serialised,
methods pass by a list, responses only for a request in flight,
approvals are authenticated and bound to the run, the hold, and the
held message, and a cancelled call is withdrawn. In every scenario the
server receives no call that was not allowed or released, and cadl agents-run on the trace written by the gateway writes the same audit
log, byte for byte, as the gateway. The changes to the runtime were
checked against cadl 0.3.23: agents-run on 309 pairs of a file and
a trace (the bundled traces, every pair of the review files of the
tests, and four malformed traces), in text and JSON, gave the same exit
status, output, and error messages, and the same values in the audit
log; and of the 1 917 replays that the test suite runs, the 1 885 on
traces without the new keys gave the same result, or the same error, as
the runtime of 0.3.23. The other 32 are traces of the gateway with
withdraw or host_events, which 0.3.23 does not read. A second
review found that a number that overflows to infinity (1e999) passed
the parser and made the forwarding fail after the decision, so that the
log showed an allowed or released call that was never sent, and that
the approver could not see the arguments of what was approved; both are
corrected, with tests that failed before (an injected failure of the
sending, and two held calls of the same tool at the same time with
different arguments, of which an approval of one does not release the
other).
A2A gateway. From cadl 0.3.25, cadl a2a-gateway FILE --agent-actor Y --upstream URL --client-keys KEYS.json --audit OUT.jsonl is the A2A gateway of G.11 for the JSON-RPC binding of A2A
1.0.0: an HTTP server in front of the agent Y of the file
(kind: llm_agent, protocol: a2a), which passes requests on to the
agent at URL. It shares the enforcement point, the trace, the log, the
holds, and the inbox with the MCP gateway, and cadl agents-run on its
trace writes the same audit log, byte for byte. From 0.3.28 it also
serves the HTTP+JSON binding and, as an optional extra, the gRPC
binding, can require client certificates, and relays push notifications
under an allowlist. Where G.11 leaves a
choice, the gateway takes the one that lets less through. Its readings
are these.
- The sender is authenticated for every request, before the body is
read as JSON. A2A leaves the scheme to the agent card; the gateway
uses keys of the actors, as the approvals do. The request carries
exactly one header
Authorization: CADL-HMAC actor="X", nonce="N", mac="M", whereXis a concrete actor,N32 andM64 lowercase hexadecimal digits.Mis the HMAC-SHA256 under the key ofXof the canonical JSON of G.8 of the object{"scheme": "cadl-a2a-request/1", "actor": X, "run_id": R, "nonce": N, "method": "POST", "path": "/", "body_sha256": D}, whereRis the run id of the gateway andDthe SHA-256 of the body in lowercase hexadecimal. The fieldschemeseparates this MAC from the MAC of an inbox file, also when an actor uses one key for both. The headersA2A-VersionandContent-Typeare not covered by the MAC. For the HTTP+JSON binding (from 0.3.28)methodandpathare the HTTP method and the whole request target, path and query, as sent; for the gRPC binding they arePOSTand the path of the RPC, such as/lf.a2a.v1.A2AService/SendMessage, andDis the SHA-256 of the serialized request message as it arrived. A nonce is accepted once in a run. The gateway keeps the nonces of each actor in memory, so memory grows with the authenticated requests of a run; after 1 000 000 requests of one actor it refuses the further requests of that actor (reasonnonce_limit) until it is started again, with a new run id. The other actors are not affected. A bearer token, which whoever sees it can send again, is not accepted. Every actor of the keys is an actor of the file. A request without a valid header gets HTTP 401 with the run id, is recorded asunauthenticated_request, and is not decided. - The extension of G.11 has the URI
https://www.ertl.jp/cadl-spec/a2a/agents-message/v0.1; its value is{"name": e, "args": [...]}, whereeis an identifier of at most 64 characters and the arguments are at most 16 strings of at most 256 characters. A message without it is answered with a rejected task and recorded asunauthorised_messagewith the reasonno_name, without a decision; a value of another form is a JSON-RPC error -32602. An agent card given with--agent-cardhas to declare the extension undercapabilities.extensions, or the gateway does not start. - Approvals do not come as A2A messages. A message whose name is that of
a
counts_as:rule that createsapprovalorrejection, whatever the receiver of the rule, is rejected and recorded asunauthorised_messagewith the reasonapproval_as_message. Approvals come through the inbox, as for the MCP gateway, bound to the arguments of the held message, which are the wholeparamsof itsSendMessage; an A2A message would carry the hold id and nothing that binds it to what the approver saw. An approval through the inbox is given to the runtime and never delivered, so the receiver of such a rule, when it is a set, a range, or an index variable, is resolved to a concrete actor. An index variable takes its value from the bindings of the contract instance of a ground of the hold, in the rule's contract (from 0.3.26). Otherwise the receiver is the actor of the gateway (Y, or the tool server of the MCP gateway) when the reference can match it, else, at the MCP gateway, its client (--agent) when the reference can match it, else the first declared member of the set. A gateway does not start when a contract that its actor is a party of escalates and has nocounts_as:rule that createsapproval; G-9 already makes such a file an error. - Only
SendMessageandSendStreamingMessageare decided.GetTask,CancelTask, andSubscribeToTaskcarry no message between actors; they pass, without a decision, for tasks that the agent or the gateway gave to the same actor in this run.CancelTaskchanges the state of the agent and is recorded astask_cancelbefore it is passed on;GetTaskandSubscribeToTaskare not recorded. ASendMessagelikewise names only such tasks (taskId,referenceTaskIds) and contexts (contextId). Anything else isTaskNotFoundError(-32001) and is recorded astask_refused; a context id that the gateway has not seen is refused too, because it may be a context of another client or of an earlier run.tenantis refused (-32602), because tasks are kept by their id.ListTasksandGetExtendedAgentCardare refused withUnsupportedOperationError(-32004), without--push-allowthe methods of push notifications and aSendMessagewith a push notification configuration withPushNotificationNotSupportedError(-32003), and any other method with -32601; all are recorded asmethod_refused. The headerA2A-Versionhas to be1.0or1.0.N, with surrounding spaces removed; otherwise, also when it is missing, the request getsVersionNotSupportedError(-32009), because under A2A 1.0.0 a missing header means version 0.3. - A denial is a task of the gateway in
TASK_STATE_REJECTEDwhose status message names the reason, the norms, the hold, the fallback, andnotify. A held request that waits for its answer (a blocking request) waits until the hold closes; withreturnImmediatelythe client gets a task of the gateway inTASK_STATE_SUBMITTED, which keeps its id after a release and shows the agent's task under it. If the released request cannot be passed on, that task becomesTASK_STATE_FAILEDand the log getsforward_failed. A client that cancels the task of a held request, or closes the connection of a held blocking request, withdraws the request (G.6). Bytes that the client sends while its request is held are read and dropped; a half-closed connection (the client has shut down its sending side) counts as closed, which withdraws the request. A withdrawal is a step of the enforcement point, and the answer comes from the closing record of the hold: a hold whose deadline passed before the step isexpired, and the client gets a rejected task. - Streams (from
cadl0.3.26).SendStreamingMessageis decided once, with the checks ofSendMessage, before anything is passed on, and its answer is a stream of Server-Sent Events, each event one JSON-RPC response on onedata:line, re-serialised by the gateway. An allowed request is passed on as a stream, and the agent's events are relayed one at a time; each is parsed strictly, has to answer this request, and has to belong to one task, or one message, of the same client, otherwise the stream ends withInvalidAgentResponseError(-32006,invalid_response) and nothing after it is passed on. A line of the agent with a carriage return other than at its end ends the stream in the same way, and comments of the agent are not passed on. A denial is a stream of one event, the rejected task. A held stream sends SSE comments (one a second) until the hold closes, then the events of the released request or one rejected task; a client that closes the connection withdraws the request, as for a blocking request. WithreturnImmediatelya held stream is one event, the submitted task of the gateway, and the released request is passed on asSendMessage.SubscribeToTaskfollows a task of the client: the stream of the agent for it, and, for a task of the gateway that is held, comments until the hold closes, then the stream of the agent's task under the id of the gateway's task, or the final task. So every event of the agent that reaches a client belongs to an allowed or released request of that client. A stream keeps its place among the requests handled at the same time until it ends or its client goes: while the agent is silent, the gateway reads from the client's connection, as for a held request, and sends a comment once a second; a client that has gone ends the stream and the request to the agent. A plain JSON answer of the agent to a streamed request is read as any other answer: at most 16 MiB, strict UTF-8. Errors found before the stream begins are answered as plain JSON-RPC errors, as A2A allows. - Mutual TLS (from
cadl0.3.28). With--client-caa client presents a certificate of that CA whose subject has exactly one common name, which is a concrete actor of the keys of the gateway. The handshake ends before the connection takes one of the readers below; a failed handshake, and a certificate that names no such actor, close the connection and are recorded ashandshake_failed. The certificate does not replace the headerCADL-HMAC: the header has to name the same actor, otherwise the request gets HTTP 401 andunauthenticated_requestwith the reasoncertificate_mismatch. A TLS session authenticates a connection, not a request: it does not bind a request to its body, to the run of the gateway, or to one use, which the MAC, the run id, and the nonce do. With push notifications the agent's actor may present a certificate too, which only delivers notifications. - The HTTP+JSON binding (from 0.3.28). The gateway serves the routes of
A2A 11.3 on the port of the JSON-RPC binding:
POST /message:send,POST /message:stream,GET /tasks/{id}with the query parameterhistoryLength,POST /tasks/{id}:cancel, the subscription/tasks/{id}:subscribewithPOST, as 11.3.2 gives it, and withGET, as thea2a.protoof A2A gives it, and the routes of/tasks/{id}/pushNotificationConfigs. A request is authenticated as above and then turned into the JSON-RPC request with the sameparams(11.4): the body, and the parameters of the path and of the query; it is decided, held, recorded, and passed on as that request, so the trace is the same as for JSON-RPC. A body isapplication/jsonorapplication/a2a+json;GETandDELETEhave no body. A route that 11.3 does not have, a route with a tenant before it, a query parameter other than those named, and a body whoseidortaskIddiffers from the path are refused;GET /tasksandGET /extendedAgentCardare refused as their methods are. An error is agoogle.rpc.Statuswith the HTTP status of 5.4 and anErrorInfowhose reason is that of 11.6 and whose domain isa2a-protocol.org; HTTP 401 and 503 of the gateway carry noErrorInfo. A stream has the result of each JSON-RPC response asdata(aStreamResponse, 11.7), and an error as anerrorevent. With--upstream-binding restthe gateway speaks this binding to the agent: the answers are checked as strictly as those of JSON-RPC, and an error answer without anErrorInfoof the domain of A2A and a known reason isinvalid_response. - Push notifications (from 0.3.28). Without
--push-allowthey stay refused, as above. With it, a client may give a configuration withSendMessageor create one for its own task (A2A 3.1.7 to 3.1.10). The agent never gets the client's URL: it gets a configuration of the gateway, whose URL is that of the gateway with a path of its own and whose token and credentials are random values of the gateway. The gateway takes a notification there only with these values and, with mutual TLS, from the agent's certificate; it has to be oneStreamResponseof the task of the configuration, and the gateway has to have recorded the client of the configuration as the owner of that task and of its context. A configuration given withSendMessageis bound to the task that the agent's answer names: the result of an allowed or released request, or the first event of its stream, which the gateway claims for the client before it binds the configuration. Until then a notification of that configuration is dropped, and a notification never makes the client the owner of a task or a context; so an agent that sends notifications before its answer loses them. A configuration whose request got no answer, an error, or an answer that names no task is removed, recorded aspush_droppedwith the reasonno_task, since it could never be bound, listed, or deleted. Then the gateway sends it to the client's URL with the client's token and credentials (A2A 4.3.3) and recordspush_sentorpush_failed; anything else ispush_dropped. The client's URL is checked when the configuration is given, and again at every notification, since a name can resolve to other addresses later: it matches an entry of--push-allow(a URL, whose path is a prefix when it ends with/, a host with an optional port, which without a port allows every port and every path of that host, or an IP address or network, which allows the addresses that a matching host resolves to and, for a single address, that address as a host, but no host name by itself); its path has no.or..segment, no backslash, and no percent-encoded dot, slash, backslash, or percent sign (so also no%252e, which decodes twice to a dot), so that the path that is compared is the path that the server reads; it ishttpsunless its host is a loopback address orlocalhost; and every address that its host resolves to is a global unicast address, or lies in an address or a network of the allowlist. Private, loopback, link-local, shared, reserved, and multicast addresses are refused, also when they are embedded in an IPv4-mapped, NAT64, 6to4, or Teredo address, and an address of a metadata service of a cloud is allowed only when the allowlist names that address itself, not by a network that contains it. The request goes to an address that was checked, without a second lookup; a redirect is not followed and is a failure; the exchange ends within--push-timeout(10 seconds) from the connection to the answer, and at most 64 KiB of the answer are read. A notification is at most 1 MiB, as any request. A configuration given to the agent, or deleted, is recorded aspush_configbefore the agent gets it, and a refused one aspush_refused. The token and the credentials of a configuration in aSendMessageare not shown in its published hold.GetTaskPushNotificationConfigandListTaskPushNotificationConfigsare answered by the gateway;DeleteTaskPushNotificationConfigstops the relay at once and is passed on. A client has at most 64 configurations, and the gateway relays at most 16 notifications at the same time; a configuration that waits with a held request, or for the agent's answer, counts against the 64, and the count and the addition are one step. Not covered: a configuration created withCreateTaskPushNotificationConfigfor a held task of the gateway (it is given with theSendMessage), and retries of a failed notification. - The gRPC binding (from 0.3.28), as the optional extra
cadl-lang[grpc]. It installs the officiala2a-sdkwith gRPC, whose modulea2a.types.a2a_pb2is generated from the normativea2a.protoof A2A (10.1; packagelf.a2a.v1, serviceA2AService); cadl adds no definitions of its own and no dependency that is not optional.--grpc-listenserves the service, with TLS and mutual TLS as above; an address other than loopback needs TLS. The metadataauthorizationcarriesCADL-HMACanda2a-versionthe version (10.2). A request message with a field thata2a.protodoes not define is refused (-32602,INVALID_ARGUMENT); otherwise its JSON (ProtoJSON, theparamsof JSON-RPC) is decided as above, and the answer is parsed into the response message, strictly: an answer of the agent that does not fit isinvalid_response. An error is a gRPC status of 5.4 with agoogle.rpc.Statuswhose details hold theErrorInfo, in the trailing metadatagrpc-status-details-bin(10.6). The gateway receives the request message itself (its handlers take the request as a stream), because gRPC hands a unary call to a worker before its message has arrived. A call is refused at once, before its message is awaited, unless its metadata has a header that could authenticate: one header of the form above that names an actor with a key and, with mutual TLS, the actor of the certificate. Then, until its message has arrived, the call takes one of the places of calls not yet authenticated, with the caps of the HTTP listener (4 per remote address, 16 per IPv4 /24 or IPv6 /48, 64 in all; beyond themRESOURCE_EXHAUSTEDandoverloaded), and it is cancelled at the read deadline (read_timeout). The service has workers for these 64 calls next to--max-handlersplus 16 handled ones, so calls that wait for their message cannot take the workers of authenticated calls. HTTP/2 is limited to 16 concurrent streams per connection, 16 KiB of metadata, pings no more often than every 10 seconds without data, and 2 minutes of an idle connection; a request message is at most 1 MiB. What remains is the same as at the HTTP listener: whoever knows the name of an actor with a key can forge a header of the right form, and such calls of one address or network can hold its places until the read deadline.grpciooffers no point at which a server can count or refuse a connection before its calls (an interceptor sees calls, not connections). The gateway therefore accepts the connections of--grpc-listenitself, in a front listener (one thread, standard library only), and passes the bytes of each one unchanged to the gRPC server, which listens on a Unix socket in a directory that only the user that runs the gateway can open (on 127.0.0.1 where there are no Unix sockets; other local processes can then connect to that port without the caps, and their calls are refused,UNAVAILABLE). Withlocalhostthe front listener listens on each of its addresses (127.0.0.1 and ::1), as gRPC did; an address that cannot be bound (::1 where IPv6 is off) is logged and left out. TLS and mutual TLS still end in gRPC: the front listener does not take part in them, so certificates and identities are as above. It keeps at most 4 open connections of one remote address (an IPv4 address or an IPv6 /64;--max-grpc-connections-per-address), 16 of one IPv4 /24 or IPv6 /48 (--max-grpc-connections-per-prefix), and 64 in all (--max-grpc-connections); a connection beyond the cap of its address or prefix is reset at once and recorded at the capped rate (overloaded,connections). Fromcadl0.3.31, a connection that finds only the cap in all reached waits for a place up to--grpc-connection-wait(10 seconds; 0 resets it at once): at most 64 connections wait, a waiting connection counts against the caps of its address and prefix, and a place that comes back goes, before any new connection, to the waiting connection whose address, then whose /24 or /48, holds the fewest connections (then to the one that came first); one that gets no place is reset and recorded as above. A connection on which no call has reached the gateway within the read deadline (--read-timeout, counted from its accept or from the end of its wait) is reset and recorded (read_timeout,grpc handshake): one that sends nothing, never starts or never ends TLS, sends its handshake a byte at a time, or is half-open. Fromcadl0.3.31 a call that gRPC refuses itself before a handler runs (an unknown method,UNIMPLEMENTED, or one beyond the workers,RESOURCE_EXHAUSTED) counts as a call of its connection, with TLS as without.grpciooffers no public hook for it, so the gateway wraps the internal function ofgrpciothat refuses such a call (grpc._server._reject_rpc, only when it has the expected parameters) and looks up the peer of the call; with agrpciowithout it these calls do not count, as in 0.3.30. A client that opens its channel before its first call and waits longer than the deadline is still reset, and connects again. After its first call, the gRPC server closes a connection that has had no call for 2 minutes, and one with a call open whose peer does not answer a ping (sent after 60 seconds without data) within 20 seconds. The front listener reads the gRPC server on while up to 256 KiB wait for the client, so it sees that close also when the client reads nothing; it then closes the client's side after what was sent to it, or resets it after 5 seconds. When more waits for the client, or the gRPC server does not take the client's bytes, and that backlog does not drain within 30 seconds, both sides are reset and recorded (read_timeout,grpc stalled). Fromcadl0.3.31 the gRPC server sends GOAWAY to each connection at--grpc-max-connection-age(300 seconds, at least 1, with a jitter of 10 %). The GOAWAY is staged: a first GOAWAY and a PING, and the final GOAWAY when the PING is answered or at the ping timeout (20 seconds); from then on the connection takes no new call, and the client's channel opens a new connection for its next calls (which may wait for a place). By default the calls under way on the old connection go on to their end, and the gRPC server closes it when the last one has ended; the front listener then closes the client's side within 5 seconds. A connection on which no authenticated call has run (the gateway marks the connection of each call that authenticates) is reset by the front listener when its calls without a key must have ended, at the read deadline + 1.1 × age + 20 + the read deadline + 10 seconds after the end of its wait (read_timeout,grpc age); this also ends a client that keeps the answers of the gRPC server pending by reading slowly. One case is not covered: when the first authenticated call of a connection starts between the first and the final GOAWAY (its earlier calls had no key or were refused), its handler starts more than 10 seconds after the call reached the gRPC server (for example behind a backlog of calls without a key), and the call lasts long, the connection can be reset before it is marked, which cuts that call. With--grpc-max-connection-age-gracethe gRPC server closes every connection at most that many seconds after the final GOAWAY, and the front listener resets one still open at the read deadline + 1.1 × age + 20 + grace + 10 seconds after the end of its wait. That gives every connection a hard bound, at a cost: a call still under way at the end of the grace is cut withUNAVAILABLE, so a blockingSendMessageheld for approval (G.6) is withdrawn, a unary call that the agent has already processed gets no answer (sent again, it is a second request), and a stream (SendStreamingMessage,SubscribeToTask) ends and is subscribed to again. A connection counts against the caps until its sockets are closed. Each connection to the gRPC server comes from an address of its own (a Unix socket bound to a path of its own, or a port of its own), which gRPC gives as the peer of its calls; the gateway maps it back to the accepted connection. The caps on calls not yet authenticated therefore count the real address of the client, as before, and a call that does not come through the front listener is refused (UNAVAILABLE). What is bounded: one remote address has at most 4 connections and so at most 64 concurrent calls (16 streams each), of which at most 4 wait for their message; one /24 or /48 has at most 16 connections and 256 calls; all clients together have at most 64 connections, and the workers bound the calls in all. A call without a key ends within the read deadline (it waits at most that long for its message and is refused when it does not authenticate), so with the defaults the gRPC server closes a connection without an authenticated call at most 1.1 × 300 + 20 + 10 = 360 seconds after its handshake, the client's side is closed within 365 seconds when the client reads, and the front listener resets it at the latest 10 + 330 + 20 + 10 + 10 = 380 seconds after the end of its wait, 390 seconds after its accept, which also ends a client that does not read. What remains: any call, even one refused for its header, keeps its connection past the deadline. Without mutual TLS, hosts with at least 16 addresses in at least 4 networks can therefore hold the 64 connections, each up to that bound, and connect again as soon as one ends. A client with a key keeps a connection past its age for as long as one of its calls is under way: a blockingSendMessageheld for approval until the decision, a call whose agent answers within--upstream-timeout(300 seconds), or a stream until its task ends. Operators who want a hard bound for these too give a finite grace; with 60 seconds every connection ends at most 10 + 10 + 330 + 20 + 60 + 10 = 440 seconds after its accept. A client that waits for a place when one comes back gets it before them if its address and its /24 or /48 hold fewer connections than those of the other waiting connections; a client that is not waiting at that moment (it waited 10 seconds in vain, and its channel backs off before it tries again) can be kept out for as long as they connect again at once, and other hosts, with 16 other addresses in 4 other networks, can also fill the 64 places to wait and come before it when they came first. With mutual TLS only holders of a client certificate of the CA get as far as a call. Behind a proxy every client has the address of the proxy, so the caps per address and per prefix are raised there. - A request is read with one
Content-Lengthof at most 1 MiB and withoutTransfer-Encoding, one request per connection; the body is parsed as strictly as a line of the MCP gateway and passed on re-serialised, with a JSON-RPC id and headers of the gateway; the client'sAuthorizationis not passed on. A header line with whitespace before its colon, a folded header line, or a bare carriage return in the headers is refused with HTTP 400 (from 0.3.26): the parser of the standard library takes such a line as the end of the headers, so that aTransfer-Encodingafter it would not be seen. A task or context that the agent gives to a second actor is not shown to it (-32006,invalid_response). A request that cannot be sent after an allow or a release gives -32603 andforward_failed; one that was sent and got no valid response gives -32006 andinvalid_response. An address other than loopback needs TLS, and--upstream-tokenneeds anhttpsagent or a loopback address. - The request line, the headers, and the body of a request have to
arrive within 10 seconds in all (
--read-timeout); otherwise the connection is closed and recorded asread_timeout. Before authentication, at most 4 connections of one remote address (an IPv4 address, or the /64 prefix of an IPv6 address, since one host usually has a whole /64; an IPv4-mapped IPv6 address counts as its IPv4 address) (--max-readers-per-address), at most 16 connections of one IPv4 /24 or IPv6 /48 (--max-readers-per-prefix, from 0.3.26), and at most 64 connections in all (--max-readers) are read at the same time. A further connection of an address that has 4, or of a prefix that has 16, gets HTTP 503 at once (overloaded,addressorprefix; before 0.3.26 it was closed without an answer); when all 64 are in use, a connection waits up to one second for one and then gets HTTP 503 (overloaded,readers). A request is counted against the 64 requests handled at the same time (--max-handlers) only after it is authenticated, also while it is held; beyond that it gets HTTP 503 (overloaded,handlers). So unauthenticated connections cannot take the places of the clients. One actor may have at most 16 requests handled at the same time (--max-handlers-per-actor), held blocking requests and requests to a slow agent included, and at most 64 holds, blocking or not (--max-holds-per-actor); a further request of that actor gets HTTP 503 before its decision (overloaded, with the reasonhandlers_per_actororholds_per_actorand the actor). So one client cannot take every place, or create holds without end; the cap on holds also refuses that actor's messages that would not be held. The records ofunauthenticated_request,overloaded, andread_timeoutare kept to at most 20 a second for each event; the next record of the event counts the requests that were not recorded (;not_recorded_before=Nin itsreason). The read deadlines of all connections are kept in one thread. What remains: hosts in at least four different /24 (or /48) networks together can keep the 64 readers busy, 16 per network, and make the gateway refuse every new connection for as long as they go on; one /24 or /48 alone cannot. A process cannot tell such hosts from clients before they authenticate, so where this matters the gateway belongs behind a proxy or a firewall that limits connections. With--client-ca(from 0.3.28) a connection takes one of the readers only after its handshake has ended with a certificate of a client, so peers without one cannot hold the readers. What remains then is a handshake that is slow but valid. Before the handshake has ended, the gateway does not know who the peer is: under TLS 1.3 the client sends its certificate at the end of the handshake. A peer whose handshake is slow therefore holds a thread and one of at most 256 places for handshakes (--max-handshakes) until the read deadline, within the caps of 4 per address and 16 per /24 or /48. Hosts in at least 16 such networks can keep all 256 places busy for as long as they go on; meanwhile a new connection waits up to one second for a place and is then closed without an answer (overloaded,handshakes), since nothing can be answered before a handshake. Behind a proxy every client has the address of the proxy, so--max-readers-per-addresshas to be raised there, or the proxy has to buffer the requests before it passes them on.
The gateway does not read the header A2A-Extensions, does not answer
ExtensionSupportRequiredError (-32008), does not read A2A-Version as
a query parameter, and does not check that a part raw is base64.
Signed holds. From cadl 0.3.26, both gateways take --hold-key FILE: every hold that they publish in the inbox then carries
"kind": "hold" and hold_mac, the HMAC-SHA256 under that key of the
canonical JSON of G.8 of the hold without hold_mac, which includes the
run, the held message, the times, the arguments, and their SHA-256, and
run.json says "holds_signed": true. cadl mcp-approve --hold-key FILE verifies the MAC before it shows or signs the hold, and refuses a
hold without it or with a wrong one; without --hold-key it refuses a
signed hold, and it warns for an unsigned one unless run.json of the
inbox says holds_signed or it is given --require-signed-hold: then
it refuses an unsigned hold. --require-signed-hold does not depend on
the inbox, whose run.json whoever can write the inbox can change. In
every case it refuses a hold whose shown arguments do not have the
SHA-256 that it names, and it shows the arguments with every character
that is not shown as itself escaped as \uXXXX: controls, format
characters such as bidirectional overrides and zero-width characters,
private use, surrogates, unassigned code points, and line and paragraph
separators. The hold key is a key of the gateway: it differs from the
key of the log, from every approver key, and, at the A2A gateway, from
every client key, and the approvers hold it to verify, so an approver
detects a hold that was changed by someone who can write the inbox but
cannot read that key, as the gateway detects such a change of an
approval with the approver keys. The authentication of the approvals
does not depend on the hold key, and
without it the gateway still refuses an approval of other arguments
than those held (wrong_message), but the approver could be shown
arguments that are not the held ones. A hold is authenticated for the
approver only when mcp-approve is given --hold-key; the option is
optional for backward compatibility.
SDKs. The gateways are tested with the official SDKs (from cadl
0.3.26): an MCP server of mcp 2.3.0 over stdio behind
cadl mcp-gateway, driven by the ClientSession of the SDK, which
negotiates the revision 2025-11-25 with initialize, and by its
Client, which negotiates 2026-07-28 with server/discover; and an
A2A agent of a2a-sdk 1.3.0 (JSON-RPC, Starlette, and uvicorn) behind
cadl a2a-gateway, driven by the a2a-sdk client, with and without
streaming, with the header CADL-HMAC added by an event hook of its
httpx client. The scenarios are allow, deny, a hold approved and one
rejected through cadl mcp-approve, returnImmediately with
GetTask, CancelTask, and SubscribeToTask, and streams that are
allowed, denied, or held; in each the agent or server receives nothing
that was not allowed or released, and cadl agents-run on the trace
writes the same audit log. These tests found no incompatibility of the
non-streaming paths. The one incompatibility was the refusal of
streaming: the SDK client streams by default when the agent card says
streaming: true, and the gateway answered -32004; 0.3.26 implements
the streams. From 0.3.28 the same client is also tested over mutual TLS,
with a client certificate given to its httpx client; over the
HTTP+JSON binding, with the agent spoken to over JSON-RPC and over the
HTTP+JSON binding; with push notifications, which the push sender of the
SDK agent sends to the gateway and the gateway relays to a webhook of
the test; and over gRPC, with interceptors of grpc.aio that add the
header over the serialized request. These found no incompatibility. They
showed two readings that the gateway has to make. The routes of 11.3.2
subscribe with POST, and the a2a.proto with GET; the SDK server
takes both, and so does the gateway. The table of 5.4 on the published
page of A2A 1.0.0 gives 400 for TaskNotCancelableError and 500 for
InvalidAgentResponseError, as the SDK does, where
docs/specification.md at the tag v1.0.0 of the repository of A2A
gives 409 and 502; the gateway follows
the published page. The tests are skipped where the SDKs are not installed, and
a job of the continuous integration installs them on Python 3.12; they
are not dependencies of cadl.
The A2A gateway is tested with a fake A2A agent in a thread of the test
and a fake client, standard library only, in 101 tests: allow,
denial by the default, a message without name, escalation that is
approved, rejected, or expires, with and without returnImmediately, a
held task that is cancelled before a signed approval arrives or after
its deadline, a client that closes the connection of a held request over
TCP (also after sending more bytes, or by a half-close) and over TLS, a
grant through the inbox, an approval re-addressed to another held
message with other arguments, approval rules with a set or a range as
receiver at both gateways,
eight kinds of failed authentication, 27 kinds of malformed input, an
agent that is down or answers wrongly, a release that cannot be passed
on, more requests than handlers, slow connections that send their
body a byte at a time, more connections than readers, peers of one
address that reconnect at once, more requests and more holds of one actor
than allowed, the nonces of one actor, the isolation of
tasks and contexts, streams that are allowed, denied, held and approved
or rejected, withdrawn when the client goes, or ended by a bad event of
the agent, clients that leave while the agent is silent, subscriptions, signed holds and forged hold files, receivers
bound by the hold's instance, malformed header lines, and the caps per
address and per prefix. In every scenario the agent receives no request that was not
allowed or released, and cadl agents-run on the trace writes the same
audit log as the gateway. An independent review of the first version
found that a context id that the gateway had not seen was claimed by
whoever named it first, also in a later run, so that a client could
continue the context of another; that tenant let a client read the
task of another tenant with the same id; that an approval rule with a
set as receiver was not recognised, so that an approval came as an A2A
message, not bound to the held arguments, and was passed on to the
agent; and that a TLS client that closed with close_notify did not
withdraw its held request. A second review found that the correction of
the third defect left holds under such a rule that could never be
approved, also at the MCP gateway; that a client that sent more bytes
and then closed was not seen as gone; that a cancellation after a
deadline that the ticker had not yet observed was answered as cancelled
while the log said expired; and that a cancellation reached the agent
without a record. A third review found that slow unauthenticated
connections could take every handler slot, because a slot was taken
before the request was read and authenticated and the timeout applied
to each read only; that the correction of the set receiver refused to
start with files that cadl 0.3.24 accepted; and that one client could
use up the cap of the nonces for all. A fourth review found that peers
of one address that reconnected at once kept every reader busy, that the
holds of returnImmediately requests were not capped per actor, and
that one actor could take every handler with requests to a slow agent.
A fifth review, of 0.3.25, found that a connection beyond the cap of its address
was closed without an answer, that each connection had a timer thread
of its own, that an index variable as receiver of an approval rule was
not resolved with the bindings of the hold, and that a header line with
whitespace before its colon hid the headers after it.
Each is corrected and has a test.
From 0.3.28, 25 more tests (tests/test_a2a_bindings.py) cover mutual
TLS (a certificate and a header of different actors, no certificate, one
of another CA, one of no actor, one with two common names, a replayed
nonce, peers that never end their handshake and take no reader, the cap
on handshakes), the HTTP+JSON binding (allow, deny, holds, streams,
subscriptions with POST and GET, refused routes, parameters, bodies,
and authentications, and an agent of
that binding), push notifications (a configuration with SendMessage
and one created, Get, List, Delete, a notification for a task of another
client, forged credentials, an unknown configuration, refused URLs, a
redirect, a slow and a failing webhook, a host name that resolves to
loopback, a held request with returnImmediately, the agent's
certificate), the checks of addresses with a resolver of the test, and
the gRPC binding (allow, deny, a hold, streams, errors, failed
authentication, unknown fields, mutual TLS, push notifications, calls
that never send their message) and its front listener (floods of
connections from one address and from one network, connections that
send nothing, never start TLS or send their handshake a byte at a time,
half-closed and half-open connections, a client that stops reading
after its call, the real address of the client
behind the splice, an authenticated call of another address served
while one address holds all its connections, over mutual TLS, and from
cadl 0.3.31 calls refused by gRPC itself (an unknown method, over
mutual TLS, and no free worker) that keep their connection, the end of
a connection at its age with a stream under way that goes on without a
grace and is cut with one, the reset without a grace of a connection
without an authenticated call while one with such a call is kept, the
reset of a
connection that gRPC keeps past its age, and the order in which waiting
connections get a place). In each,
the agent receives nothing that was not allowed or released, no
notification reaches a client that did not register it, and
cadl agents-run writes the same audit log. An independent review of
these bindings found no request that reached the agent without a
decision, no way around the authentication or the checks of addresses,
and no replay. It found that a configuration given with SendMessage was
not bound to its task, so that its client could not list or delete it
and the first notification bound it to any task it named; that calls of
the gRPC listener that never sent their message held its workers without
a deadline; that gRPC with mutual TLS accepted a certificate with two
common names; and that dot segments, also percent-encoded, let a callback
URL leave the path prefix of its entry. Each is corrected and has a
test. The new tests ran five times in a row and three runs at the same
time without a failure.
None of the reviews found a request that reached the agent without a
decision; the first checked
this also in a run of 12 threads whose log of 280 records
cadl agents-run reproduced.
The trace is that of cadl norms-eval (JSON Lines with t,
bindings, request, values, messages, state, amend, end),
read for the whole enforcement point, with more keys: epoch, the
time of t = 0 as an ISO 8601 time stamp, which makes the times of
the records time stamps; instances, the contract instances that a
host creates and ends, with their bindings; run_id on the first line;
withdraw, the holds whose message the host withdraws at the line
(G.6); and host_events, the event records of the host (G.8), which
change no decision. Every instance has to
bind the index variables of the parties of its contract, the single
instance of a contract without host through the bindings of the first
line, and each value has to be the index of a member of the set that
the party names; otherwise the trace is rejected, with the contract,
the instance, the variable, and the value in the message. A binding of
a variable that no party has is ignored, with a warning. A value has
to be the index of a member of every declared set that the variable
indexes in the contract, not only of the party's set. The key
quantities of the first line gives the quantity names of the run
(F.5); then exactly these names are quantities, from the start and for
every instance. Without it the runtime takes a name as a quantity from
the first line on that gives it a value, so that no decision depends on
a later line (G.5); a bare name without a value so far is a symbolic
value. This can differ from the verdicts of cadl norms-eval on the
same lines for a name before its first value, and the runtime warns
when a name that a predicate uses gets its first value after a message
was decided. Nothing after the end of an instance has an effect on
it. Which contracts have host-created instances is likewise fixed on
the first line: a contract that the first line names in instances,
or lists under the key host_instances when its first instance is
created later, has the instances that the trace creates, and none
before; every other enforced contract has its single instance from the
start, and a later line that creates an instance of it is a trace
error. When a message is decided while a flag is unknown for missing
data (G.5), the runtime warns once per norm and names the quantity
without a value. Messages sent before the first values of such
quantities are therefore denied or escalated; a trace gives the initial
values on its first line to avoid that. A grant that is sent while the
until: of the delegable permission is undefined is recorded as
unauthorised_grant with the reason no_authority, because the
permission is not known to be in force, and has to be sent again. Two
limits remain for missing data. A message that would create a blocking
event under an if: that is undefined creates nothing (G.5, G-19);
the runtime warns and names the rule, the event, and the quantity. And
the rule does not reach through an obligation: while the predicate
trigger: of an obligation is undefined, the obligation is not
activated, so it is not violated, and a prohibition that is its
reparation: does not arise. One line is processed in
this order: holds whose deadline lies before its time expire; the holds
of withdraw are withdrawn; the host_events are recorded; instances
are created; the time and the values of the line are observed without
message (G.5), together with an amendment; each message is decided, and
an allowed one is one observation; a change of lifecycle state and the
end of instances are a last observation. Messages after the end of an
instance are still decided and recorded.
From cadl 0.3.36 the runtime and the gateways follow the current
regime of a file in which a regime of regimes: does not have an
enforced contract in force
(Appendix A, A.7.1,
"Runs"); in 0.3.33 to 0.3.35 they refused such a file. A line of the trace
names the regime with the key regime, as a trace of cadl norms-eval
does, and before the first one the run is in the initial regime. At a
line the named regime is current first, after the expired holds, the
withdrawals and the host events; then the versions that take effect
there are applied
(Appendix K, K.11);
then the line goes on as above. Every policy input carries the regime
(G.10), so a contract that the regime does not have in force governs no
message, and a decision record lists only the instances of the
contracts in force. An instance of such a contract sees nothing while
the contract is not in force (F.5, "Contracts not in force"): its
deadlines, the windows of its prohibitions and the in-force flag of a
violated prohibition are measured on the clock of the contract, a
change of lifecycle state other than to a terminal state is not seen,
and an instance that ends then is settled on the stopped clock. A hold
of such a contract stays held: its approval is a message that the
contract does not govern then, so it approves nothing until the
contract is in force again or the hold expires. The deadline of a hold
is a time of the trace, not of the clock of the contract: the hold
expires at it also while the contract is not in force. A version that takes
effect while the contract is not in force reaches the instance at its
next observation (an instance that has observed nothing yet starts on
the version in force then), and a regime must be a regime of every
version that the run uses. amend in such a run is refused, as in
cadl norms-eval: F.6 amends an instance at an observation, and an
instance whose contract is not in force has none. A gateway takes the
regime of its first line from --init and later changes from its
inbox, as files of the kind regime that
cadl mcp-regime DIR REGIME [--key FILE] writes; it writes each
accepted change as a trace line with regime and the host event
regime_change (G.8), so the replay by cadl agents-run gives the
same log. Given --regime-key FILE, the gateway authenticates every
such file with HMAC-SHA256 under that key over the canonical JSON of
G.8, with the run id and a nonce, also under --insecure-approvals
(which then leaves only approvals and other messages unauthenticated),
and says regimes_signed in the published run.json. With
--approver-keys and without --regime-key it refuses every change
of regime (unauthenticated); under --insecure-approvals without
--regime-key it reads a change without authentication, for tests.
cadl mcp-regime without --key refuses, with a nonzero exit status,
an inbox whose run.json says approver_keys or regimes_signed. A
refused change (G.8) leaves the regime as it was, and the gateway goes
on; this includes, with versions, a regime that a version that the run
used, the version in force, or a later version of the run does not
have, which K.11 ("Versions and regimes", item 3) would make the run
fail on when that version takes effect. The gateway refuses to start
when the regime of its first line (from --init or the initial regime)
is such a regime, and when the run starts in no regime (the version in
force at its first line has no regimes:) while a version of the run
has regimes:, which K.11 forbids. A gateway that does not start
removes the audit log, the trace, and run.json that it created. The tests of cadl
0.3.36 compare every decision with the decision function on its input
and the verdicts of every contract instance with cadl norms-eval on the
observations that the enforcement point made, on 400 random traces of
five files and on 120 runs with two versions whose regime bindings
differ, without a difference.
Three points are readings of the implementation and not rules of this
appendix. An amendment applies to the enforced contracts whose
definition differs between the two versions, and it may not add or
remove an enforced contract. After a violation, the window clock of a
prohibition stops while the prohibition is suspended, as it does before
(F.5). A message matches the content of an obligation, for the verdict
excused, as at the boundary: on sender, receiver, and name.
Known limits. Without a key, the chain of the log does not detect a
log that is rewritten from a changed line on; keeping the last digest
elsewhere (--anchor), or a key, does; the hash field of the header
is not authenticated, so the verifier has to know whether a log is
keyed. The MCP gateway over stdio and the A2A gateway over JSON-RPC,
HTTP+JSON, and gRPC have been tested with fake servers, agents, and clients, and from
0.3.26 with the official SDKs named above, not with other
implementations. The A2A gateway needs a client that computes
the header CADL-HMAC, keeps the owners of tasks and the push
notification configurations only for one run, and does not support
ListTasks, GetExtendedAgentCard, or tenants. A gateway
observes messages and time, not values: a norm that reads a
quantity sees missing data (G.5). It does not create or end
host-created contract instances after its first line. The approver's
tool signs the held message that the gateway publishes, so it trusts
the gateway for what it shows; with --hold-key it verifies that the
gateway published it. The keys of the approvers separate them
only when each approver uses an account of their own: whoever shares
the account of the gateway can read every key in its keyring, and the
directory protects only against parties that cannot read the key
files. The log has no record for a change of
the in-force flag of a norm (G.8). A holder whose derived instance is
active but no longer valid after an amendment of to: cannot be
granted the permission again: the grant is the no-op of condition 5
(holder_exists). A trace gives time as a finite number of at most
253 in absolute value; with an epoch, every time and every
deadline of a hold has to be an instant that an ISO 8601 time stamp can
express. A trace error on a later line is raised before anything is
printed or written, but after the earlier lines have been decided in
memory; the audit file is written only when the whole trace was
replayed. The functions of the runtime refuse a file with errors of
cadl check and an instance without the bindings of its parties; a
switch for tests turns both off, and only then is the resolution of
unknown occurrences (G.5) reached. The decision function
cadl agents-decide still takes instances without bindings and treats
the match as unknown (G.4). Up to cadl 0.3.22 the runtime, like cadl norms-eval, did not
evaluate a predicate with a quantifier or an aggregate. From cadl
0.3.23 it evaluates them as F.5 defines; a quantified predicate that
is undefined because its domain is open is missing data (G.5). Up to
cadl 0.3.23 it did not evaluate a wildcard or range reference
outside the domain of a quantifier (A[*].x > 0). From cadl 0.3.24
it rewrites such a reference as F.5 defines ("Wildcard and range
references"), with the same code as cadl norms-eval, so
A[*].x > 0 is judged as for all j in A[*]: A[j].x > 0. Up to
cadl 0.3.29 a norm whose trigger:, until:, or content: was a
predicate that F.10 does not evaluate, such as an aggregate argument
with references to two sets, was not judged, and its in-force flag was
unknown for the whole run; by G.5 such a prohibition always applied and
such a permission never did. From cadl 0.3.30 such a norm is an error
of N-16 (F.7), and the runtime and the gateways do not start with it.
The tests replay each step of the runtime through the decision function
with the state the runtime computed, and through the generated Rego
policy under OPA 1.22.3: 81 decisions of nine hand-written scenarios
(the three calls of G.12, rejection, timeout, a prohibition between a
trigger and an until:, delegation with a depth limit, two contracts
with bound indices and host-created instances) and 7 800 decisions of
26 generated traces over eleven files gave the same result in both. The
generated traces have host-created instances with different bindings,
senders outside the declared sets and undeclared senders, a hold with a
ground in one of two contracts, and revocations, ends of instances, and
amendments between a hold and its approval. Every release in them, 176
with 15 denied, and 13 more with 8 denied under random amendments, was
checked from its recorded policy input against the rules of G.6. A
second model of G.4 to G.7 and F.3, written by the reviewer from the
text of the appendices without code of the reference implementation,
gave the same 8 102 decision and closing records on 108 further traces
over seven files: 60 traces with every index bound, run as
cadl agents-run runs them, and 48 with instances that bind nothing or
with two files that cadl check rejects by G-17 and G-18, run with the
switch for tests. That model has no powers and no obligations. For
them, 60 generated traces of 200 messages over two files check that
without a binding no power is exercised, no institutional event is
created, and no obligation is fulfilled, and that with a binding only
the bound member does these things. The expected records
of the scenario tests were derived from the text of this appendix
before the runtime was run, and the runtime produced them.
An independent review of the first version of the runtime found
defects that these tests had not shown, in the implementation and in
the text. All of them let a message take effect that should not have,
and all are corrected. The grounds of a hold were kept per contract and
not per contract instance, so an approval also covered the same
prohibition in an instance created later (G.6). The re-check of a
released message tested only new prohibitions, so a message was
released although another governing contract no longer allowed it, for
example after a revocation (G.6; the text said "nothing else is
re-checked"). An actor reference with a range in a trigger:, an
until:, or a counts_as: rule matched every actor of that name, and
A[*] matched actors outside the declared set; this was a defect of
cadl norms-eval since 0.3.20 (F.3, F.10). An instance observed
messages that its contract does not govern (G.5). The generated traces
had also shown one defect: holds that expired together were closed in
the order of creation, not of their deadlines.
A second review confirmed these corrections and found what the rule of
governed observations had opened. A message event of an enforced
contract that names an actor who is not a party could never occur, so a
prohibition triggered by such an actor never came into force; G-17 now
makes that an error. An index variable that the contract instance does
not bind matched every member of the set in a trigger:, an until:,
or a counts_as: rule, so any member could activate a permission or
lift a prohibition; G-18 excludes it, and the runtime resolves the
unknown occurrence fail-closed (G.5). A set with a symbolic upper bound
took an index below its lower bound as a member, in the decision
function, the Rego policy, and cadl norms-eval.
A third review found that the unbound index was still a way through
for powers and obligations, which the second model does not have: with
a bearer SUP[k] and no binding for k, any member of SUP exercised
a power that suspends a prohibition or activates a permission, and a
message to any member fulfilled an obligation whose reparation is a
prohibition. The cause was the same in every case, a contract instance
that runs with an index unbound, and it is now removed at the root:
G-18 covers every index variable of an enforced contract, the runtime
refuses an instance that does not bind the indices of its parties, and
its functions refuse a file with errors. The fail-closed resolution of
G.5 is complete and remains as a second line. G-17 also rejects a
literal index outside the declared set, and says that coverage is by
one party reference.
A fourth review found the same cause once more, in a place the rule
did not yet name: an index variable in a predicate. A prohibition with
the trigger: W[j].alarm == true and no party W[j] passed the
check and never came into force. G-18 now covers every predicate of an
enforced contract, with the exception of a variable that a quantifier
binds, and the runtime resolves such a predicate as an unknown
occurrence. The review also found that the runtime took the quantity
names of an instance from the whole trace, so a value given after the
end of an instance could change its verdict from violated to
fulfilled, and that it accepted a binding outside the declared set, so
a prohibition of W[i] applied to nobody; both are corrected.
A fifth review found that decisions depended on later lines of the trace. The runtime had taken the quantity names from the whole trace since its first version, and the correction after the fourth review had only narrowed that to the lines of the instance: a value that a later line gave to a name changed how an earlier predicate read that name, and with it an earlier decision from deny to allow. The runtime now decides causally (G.5): the names are given with the trace, or a name becomes a quantity with its first value. The tests check, for every prefix of generated traces, that the decisions on the prefix are the first decisions on the whole trace; that invariant was missing. G-18 also missed an index variable inside an index expression and inside the arguments of a message event; it is now stated by its binders, and the checker walks every expression of the contract.
A sixth review found one more look-ahead of the same kind: whether a
contract has host-created instances was read from the whole trace, so
an instances entry on a later line removed the single instance from
the start and changed an earlier denial into an allowance. It is now
fixed on the first line. The review also led to the rule for missing
data in G.5: a prohibition whose trigger: could not be evaluated for
want of a value was not in force, and a message was allowed on data
that the enforcement point did not have.
A seventh review found that this rule looked only at the predicate of
the norm itself: a prohibition whose trigger: is an institutional
event that a rule creates from a predicate was not in force while that
predicate had no value. The rule of G.5 now reaches through such an
event, and G-19 and the two limits above state what it does not
reach.
Writing and reviewing the runtime showed these gaps in the text of
agents 0.1, which this revision of the appendix closes: the state on
which a message is decided did not include deadlines that had passed
since the last observation, and it was not said which contract
instances observe an allowed message (G.5); the grounds of a hold, the
contract instance in which an approval has to be created, the
decision at a release, and the order of holds that expire together were
not stated or were stated too weakly (G.6); whether the until: of a
delegation ends the entry or its instances was open (G.7); the
fallback that G.12 lets the sender find in a closing record was
excluded by G.10; the records of grants, revocations, unauthorised
acts, and other changes of state had no format (G.8); and nothing
required the contract to govern the messages its events name, or to
bind the indices they use (G-17 and G-18, added at the end of G.9; no
earlier rule changes).
The generated policies have been run with OPA 1.22.3 and the Cedar CLI
4.14.1 and compared with cadl agents-decide on one input space. Its
first part is a file with two enforced contracts in three variants (the
default: of one contract omitted, allow, or deny): every message
of 12 senders, 9 receivers, and 9 names, each without instances and
with 16 sets of contract instances, bindings, in-force flags, and
derived instances with valid and invalid chains (49 572 inputs). Its
second part is 300 random files with one to three enforced contracts
(and sometimes one that is not enforced), static and non-static
permissions and prohibitions, default: allow, deny, or omitted,
escalation, fallbacks, and delegations, each with 7 040 inputs from
random instance sets. Under OPA the full result was equal for the
49 572 inputs of the first part and for 211 200 inputs of 30 random
files. A Cedar request carries the message only; for each of the
530 916 requests the Cedar answer was the decision for the message
alone on the contracts without their norms that are not static. Of the
2 161 572 inputs, 2 022 265 are in the cases of G.10, and for each of
them the Cedar answer was the decision for the full input, where Deny
stands for deny and escalate. Each reason
for which G.10 leaves an input to the runtime (a governing contract
without a running instance, a permission or a prohibition that is not
static and can match, a derived instance that can match) occurs, and
for each some input has a decision that differs from the Cedar answer.
The tests of the reference implementation repeat both comparisons on a
smaller sample when opa or cedar is installed. This comparison found
that the comment that cadl 0.3.26 and earlier write at the top of the
Cedar policies called a Deny by the forbid policy of a static
prohibition final. It is not final when the contract of the prohibition
has no running instance and the message is not a tool call, because that
contract then decides by its default; the second case of G.10 states
this, and cadl 0.3.27 writes the three cases into the comment. The
policies themselves were correct. An earlier run, on fewer inputs,
found a defect in the Rego policy of cadl 0.3.20: a reference A[i] whose
index the contract instance does not bind was treated as no match
instead of unknown (G.4), so a prohibition with such a bearer did not
apply, and a contract with default: allow allowed the message.
cadl 0.3.21 corrects it; a policy generated by 0.3.20 SHOULD be
generated again.
G.14 Backward compatibility
Files written against CADL v0.3 without this extension remain valid and
are read the same way; so are files that declare only norms: 0.1. A
contract without the key enforcement: is not enforced, and its norms
keep exactly the meaning of Appendix F. For an
enforced contract this appendix makes these additions to F.5 and no
other change: the instance of a contract without host exists from the
start of the enforcement point; a denied or held message is not an
observation; an instance of an enforced contract observes only the
messages that its contract governs, and an occurrence that depends on
an unbound index is unknown; the in-force flag is unknown while a
quantity that it depends on has no value, without a change to the
states of F.5; the time of a decision is observed
before the message is decided; permissions and prohibitions have an in-force flag; an
obligation whose content the contract itself denied or held is
excused (all G.5); approval and rejection carry a hold id, the
order of steps is extended, and a released message does not violate
its grounds (G.6); permissions have derived instances (G.7).
A file that uses agent:, enforcement:, delegations:, or
on_denied: without declaring agents: 0.1 does not conform to this
appendix. An agents-aware processor does not interpret these keys in
such a file (they are not checked and not lowered to the IR) and SHOULD
emit one warning per file that names the keys used. A file that
declares agents: 0.1 without norms: 0.1 gets the error of G-1.
Processors that do not
implement the extension MUST NOT reject files that use it; they SHOULD
emit a single informational diagnostic per file.