@highflame/policy 2.3.0 → 2.4.0

package/_schemas/guardrails/templates/dual_attribution.cedar

@@ -1,22 +1,77 @@
 // =============================================================================
 // Dual Attribution
 // =============================================================================
-// Blocks privileged agent actions that cannot be attributed to a human. "Which
-// agent did this?" is half an answer; the other half is "on whose behalf?" An
-// agent is not an accountable party — the person who pointed it at the work
-// is. Shield projects both sides of that pair, so the requirement can be a
-// policy rather than a reporting convention nobody enforces.
+// Routes privileged agent actions that no human answers for to explicit
+// human approval. "Which agent did this?" is half an answer; the other half
+// is "on whose behalf?" When an agent acts for a person, that person is the
+// accountable party. When it acts for nobody (an autonomous agent, a
+// workload, an api_key-rooted token), its sensitive tool calls run only when
+// someone explicitly authorizes them, never silently and never by default.
 //
 // The agent comes from the authenticated identity, never from the request
 // body: agent_id, agent_type, agent_trust_level, agent_framework. The human
-// comes from the identity claims on the credential, as the `principal` record
-// — its `act_sub` field names the party the agent is acting for.
+// comes from the identity claims on the credential, as the `principal`
+// record. Its `act_sub` field names the human the agent acts for, and is
+// absent when there is none: legacy tokens carry the delegating parent (or
+// the api key's creator), while rfc8693 tokens carry it only when the
+// delegation chain is rooted in a user. Autonomous, workload and
+// api_key-rooted rfc8693 tokens have no act_sub.
 //
-// Deploy in MONITOR mode first. Section 2 blocks unverified agents, and a
-// service key authenticates as unverified until the agent is registered and
-// adopted in Studio. Monitor records what each rule would have blocked on
-// every event without blocking anything; register the agent, then switch to
-// enforce.
+// How an agent call with no acting human is authorized: it needs an
+// explicit approval OR an explicit grant.
+//   1. Approval. Section 1 permits the call but suspends it for step-up
+//      approval (@step_up_required, AARM R4, CAP-ENF-004): Shield issues an
+//      OpenID CIBA challenge and the call runs only after an approver with
+//      the named AuthN role approves it; the timeout denies it (fail-closed).
+//   2. Grants. Allow/deny rows in Studio's agent access table compile to
+//      permits (grants) and forbids (restrictions) that Shield evaluates per
+//      agent. A restriction always denies. Section 1 carries
+//      @step_up_unless_granted, so when an allow grant explicitly matches
+//      the call under an ENFORCING access posture, Shield waives the
+//      challenge and the call runs (recorded as step_up_waived_by_grant).
+//      Under the default shadow posture a grant is only observed, so it
+//      waives nothing and approval decides. With no matching grant the call
+//      is challenged under either posture, not denied for lack of a grant.
+//   The waiver needs every step-up policy matching the call to carry
+//   @step_up_unless_granted: another step-up policy without it still
+//   challenges. Shield releases older than the grant waiver ignore the
+//   annotation: there a no-human call needs the approval even when granted,
+//   and under an enforcing posture an ungranted one is denied outright.
+//
+// A call carrying an acting human (act_sub present) is untouched by
+// Section 1, unless the agent is autonomous and not first_party.
+//
+// Customize Section 1 before deploying:
+//   - @step_up_unless_granted: remove it to require the approval even for
+//     calls an allow grant covers (grant AND approval).
+//   - role: must exist in authn.roles ("security_oncall" is a placeholder;
+//     unknown roles reject the policy at deploy time). Another step-up
+//     policy matching the same call must name the same role, or Shield
+//     denies the call (one approval cannot satisfy two roles).
+//   - timeout_seconds: this template sets 3600 (1h); when omitted the
+//     default is 86400 (24h). Bounds [60, 604800].
+//
+// Deploy this policy in ENFORCE mode. Section 1's approval gate exists only
+// in enforce mode: in monitor or alert mode Shield issues no challenge and
+// passes Section 1's Allow through unchanged. Section 1 is a permit, so in
+// a policy set without the baseline permit (organization.permit-baseline)
+// it is what lifts the implicit deny for these calls. In enforce mode that
+// lift is gated on approval (or a grant); in monitor mode the same calls
+// would be allowed with no approval at all, a widening, not an observation.
+//
+// Only Section 2 is safe to observe first. It blocks unverified agents, and
+// a service key authenticates as unverified until the agent is registered
+// and adopted in Studio. Either register and adopt the agents before
+// deploying, or move Section 2 into its own policy, deploy that one in
+// MONITOR mode to see what it would block, and switch it to enforce once
+// the agents are adopted. Mode is per policy, so never put this whole
+// template in monitor to trial Section 2.
+//
+// Change note: Section 3 (autonomous agents must be first_party) used to be
+// a hard block. It is now folded into Section 1, so a non-first-party
+// autonomous agent's sensitive call is routed to approval (or a grant)
+// instead of being denied. To restore the hard block, add the forbid kept
+// in the Section 3 comment below; it overrides approvals and grants.
 //
 // Detection layers:
 //   - agent identity (authentication layer, always available)
@@ -24,7 +79,8 @@
 //
 // Context keys consumed:
 //   - agent_id, agent_type, agent_trust_level: String
-//   - principal: record — act_sub names the accountable human
+//   - principal: record; act_sub names the acting human, absent when the
+//     agent acts for nobody
 //   - tool_is_sensitive: Bool
 //   - tool_category: String
 //
@@ -36,33 +92,69 @@
 // =============================================================================
 
 // ---------------------------------------------------------------------------
-// Section 1: No unattributed privileged action
-// `unless` because the rule must fire when attribution is ABSENT, and an
-// absent field cannot be compared — only tested for.
+// Section 1: No-human privileged action requires approval
+// ENFORCE mode only: in monitor mode this permit allows the call with no
+// approval (see the header).
+// Matches when attribution is ABSENT (an absent field cannot be compared,
+// only tested for), and also for autonomous agents that are not first_party
+// even when a human is attached: nobody watches an autonomous agent in real
+// time, and a legacy api_key token names the key's creator as act_sub
+// whether or not that person is directing the call.
+//
+// Cedar is deny-overrides and Shield issues step-up only when the decision
+// is Allow, so this permit must not coexist with a forbid on the same calls:
+// the forbid would deny every one of them and no approval would be asked.
+// To hard-block instead of gating on approval, replace this rule with:
+//
+//   @id("agent-identity.require-principal-for-sensitive-tools")
+//   @name("Block sensitive agent tools without a principal")
+//   @description("Blocks call_tool on a sensitive tool by an agent unless the credential carries a principal whose act_sub names the human the agent acts for.")
+//   @severity("critical")
+//   @tags("category:agent-identity,detection:rule,scope:per-agent,surface:call-tool,owasp:asi01,posture:deny-default")
+//   @reject_message("Tool execution blocked: this agent invoked a sensitive tool with no accountable human attached.")
+//   forbid (
+//       principal,
+//       action == Guardrails::Action::"call_tool",
+//       resource
+//   )
+//   when {
+//       context has agent_id && context.agent_id != "" &&
+//       context has tool_is_sensitive && context.tool_is_sensitive == true
+//   }
+//   unless {
+//       context has principal && context.principal has act_sub
+//   };
 // ---------------------------------------------------------------------------
 
-@id("agent-identity.require-principal-for-sensitive-tools")
-@name("Block sensitive agent tools without a principal")
-@description("Blocks call_tool on a sensitive tool by an agent unless the credential carries a principal whose act_sub names the human the agent acts for.")
+@id("agent-identity.step-up-sensitive-tools-without-principal")
+@name("Permit no-human sensitive agent tools with step-up approval")
+@description("Permits call_tool on a sensitive tool by an agent with no acting human (no act_sub), or an autonomous agent that is not first_party, but suspends it until an approver with the configured AuthN role approves, unless an enforcing allow grant explicitly covers the call.")
 @severity("critical")
-@tags("category:agent-identity,detection:rule,surface:call-tool,scope:per-agent,posture:deny-default,owasp:asi01")
-@reject_message("Tool execution blocked: this agent invoked a sensitive tool with no accountable human attached. Every privileged agent action must name the person it acts for.")
-forbid (
+@tags("category:agent-identity,detection:rule,scope:per-agent,surface:call-tool,posture:deny-default,owasp:asi01,step-up")
+@step_up_required("role=security_oncall,timeout_seconds=3600")
+@step_up_unless_granted
+permit (
     principal,
     action == Guardrails::Action::"call_tool",
     resource
 )
 when {
     context has agent_id && context.agent_id != "" &&
-    context has tool_is_sensitive && context.tool_is_sensitive == true
-}
-unless {
-    context has principal && context.principal has act_sub
+    context has tool_is_sensitive && context.tool_is_sensitive == true &&
+    (
+        !(context has principal && context.principal has act_sub) ||
+        (
+            context has agent_type && context.agent_type == "autonomous" &&
+            !(context has agent_trust_level && context.agent_trust_level == "first_party")
+        )
+    )
 };
 
 // ---------------------------------------------------------------------------
 // Section 2: Trust level gates the blast radius
 // Start in monitor: a service key is unverified until the agent is adopted.
+// Unverified agents are blocked outright, approval or not: registration and
+// adoption come before any per-call authorization.
 // ---------------------------------------------------------------------------
 
 @id("agent-identity.block-unverified-agent-sensitive-tools")
@@ -85,26 +177,29 @@ when {
 };
 
 // ---------------------------------------------------------------------------
-// Section 3: Autonomous agents get a higher bar
-// Nobody watches an autonomous agent in real time, so a sensitive tool call
-// from one requires first-party trust rather than merely "not unverified".
+// Section 3 (folded into Section 1): autonomous agents need first-party trust
+// This template used to forbid sensitive tool calls from autonomous agents
+// that are not first-party. A forbid would deny the very calls Section 1
+// routes to approval, so the condition now lives in Section 1 and those
+// calls require approval instead of being blocked. To hard-block them anyway
+// (overriding approvals and grants), add:
+//
+//   @id("agent-identity.restrict-autonomous-agent-sensitive-tools")
+//   @name("Block non-first-party autonomous agent tool use")
+//   @description("Blocks call_tool on a sensitive tool when agent_type is autonomous unless agent_trust_level is first_party.")
+//   @severity("high")
+//   @tags("category:agent-identity,threat:escalation,detection:rule,surface:call-tool,scope:per-agent,owasp:asi04")
+//   @reject_message("Tool execution blocked: autonomous agents must be first-party to call sensitive tools.")
+//   forbid (
+//       principal,
+//       action == Guardrails::Action::"call_tool",
+//       resource
+//   )
+//   when {
+//       context has agent_type && context.agent_type == "autonomous" &&
+//       context has tool_is_sensitive && context.tool_is_sensitive == true
+//   }
+//   unless {
+//       context has agent_trust_level && context.agent_trust_level == "first_party"
+//   };
 // ---------------------------------------------------------------------------
-
-@id("agent-identity.restrict-autonomous-agent-sensitive-tools")
-@name("Block non-first-party autonomous agent tool use")
-@description("Blocks call_tool on a sensitive tool when agent_type is autonomous unless agent_trust_level is first_party.")
-@severity("high")
-@tags("category:agent-identity,threat:escalation,detection:rule,surface:call-tool,scope:per-agent,owasp:asi04")
-@reject_message("Tool execution blocked: autonomous agents must be first-party to call sensitive tools. No human is in the loop to catch a mistake.")
-forbid (
-    principal,
-    action == Guardrails::Action::"call_tool",
-    resource
-)
-when {
-    context has agent_type && context.agent_type == "autonomous" &&
-    context has tool_is_sensitive && context.tool_is_sensitive == true
-}
-unless {
-    context has agent_trust_level && context.agent_trust_level == "first_party"
-};

package/_schemas/guardrails/templates/templates.json

@@ -637,7 +637,7 @@
     {
       "id": "agent-identity.dual-attribution",
       "name": "Dual Attribution",
-      "description": "Block privileged agent actions that cannot be attributed to a human. Deploy in monitor mode first; a service key is unverified until the agent is adopted.",
+      "description": "Require human approval or an explicit allow grant for sensitive agent tool calls that no human answers for (no acting human, e.g. autonomous or workload agents); calls with an acting human pass. Customize the approver role. Deploy in enforce mode: the approval gate does not exist in monitor mode. Adopt agents first (a service key is unverified until then), or trial the unverified-agent block as its own monitor-mode policy.",
       "category": "agent-identity",
       "file": "dual_attribution.cedar",
       "severity": "critical",
@@ -647,7 +647,8 @@
         "surface:call-tool",
         "scope:per-agent",
         "posture:deny-default",
-        "owasp:asi01"
+        "owasp:asi01",
+        "step-up"
       ]
     },
     {

package/dist/aarm-annotation.d.ts

@@ -92,6 +92,15 @@ export interface StepUpScopeDirective {
  */
 export interface StepUpFourEyesDirective {
 }
+/**
+ * Parsed form of `@step_up_unless_granted`. Marker: an explicit agent grant
+ * satisfies this policy's step-up approval. When the call is explicitly
+ * allowed by an enforcing allow grant, Shield waives the challenge, provided
+ * every step-up policy matching the call carries it. Written bare or as
+ * `@step_up_unless_granted("true")`. Only valid with `@step_up_required`.
+ */
+export interface StepUpUnlessGrantedDirective {
+}
 /**
  * Parsed form of `@single_use`. The allow produced by the permit carrying it
  * can be spent once. Only valid on a permit (see validateAARMAnnotationsForEffect).
@@ -113,6 +122,7 @@ export interface AARMDirectives {
     redactionStrategy?: RedactionStrategyDirective;
     stepUpScope?: StepUpScopeDirective;
     stepUpFourEyes?: StepUpFourEyesDirective;
+    stepUpUnlessGranted?: StepUpUnlessGrantedDirective;
     singleUse?: SingleUseDirective;
 }
 /** True iff at least one AARM directive was parsed. */

package/dist/aarm-annotation.js

@@ -48,6 +48,7 @@ export function hasAnyAARMDirective(d) {
         d.redactionStrategy !== undefined ||
         d.stepUpScope !== undefined ||
         d.stepUpFourEyes !== undefined ||
+        d.stepUpUnlessGranted !== undefined ||
         d.singleUse !== undefined);
 }
 /**
@@ -166,6 +167,14 @@ export function parseAARMAnnotations(raw) {
                     directives.stepUpFourEyes = r.directive;
                 break;
             }
+            case 'step_up_unless_granted': {
+                const r = buildStepUpUnlessGranted(def, params, value);
+                if (r.error)
+                    errors.push(r.error);
+                else
+                    directives.stepUpUnlessGranted = r.directive;
+                break;
+            }
             case 'single_use': {
                 const r = buildSingleUse(def, params, value);
                 if (r.error)
@@ -189,7 +198,7 @@ export function parseAARMAnnotations(raw) {
     // Without it the policy would permit outright while its author believes a
     // human approval is required, so reject rather than ignore.
     if (!directives.stepUpRequired) {
-        for (const key of ['step_up_four_eyes', 'step_up_scope']) {
+        for (const key of ['step_up_four_eyes', 'step_up_scope', 'step_up_unless_granted']) {
             if (key in raw && !errors.some((e) => e.key === key)) {
                 errors.push(new AARMAnnotationError({
                     key,
@@ -449,6 +458,22 @@ function buildStepUpFourEyes(def, params, raw) {
     }
     return { directive: {} };
 }
+function buildStepUpUnlessGranted(def, params, raw) {
+    // Bare or "true" only, as for four-eyes: "false" would read as present
+    // (grant waives the approval) to a consumer checking presence.
+    const v = params.enabled;
+    if (v !== undefined && v !== '' && v !== 'true') {
+        return {
+            error: new AARMAnnotationError({
+                key: def.key,
+                parameter: 'enabled',
+                rawValue: raw,
+                reason: 'value must be omitted or "true"',
+            }),
+        };
+    }
+    return { directive: {} };
+}
 function buildSingleUse(def, params, raw) {
     const gDef = mustLookupParam(def, 'granularity');
     const granularity = params.granularity || (gDef.default?.kind === 'string' ? gDef.default.value : 'tool');

package/dist/aarm-annotations.gen.js

@@ -129,7 +129,7 @@ export const AARM_ANNOTATIONS = [
     },
     {
         key: 'step_up_required',
-        description: 'Suspend the action pending human approval from an approver with the named role. AARM R4 STEP_UP decision: Shield issues an OpenID CIBA bc-authorize challenge and the action does not execute until an approver carrying the role resolves it (POST /oauth2/bc-authorize/{auth_req_id}/approve via AuthN), OR timeout_seconds elapses (fail-closed: timeout DENYs the action, never permits).',
+        description: 'Suspend the action pending human approval from an approver with the named role. AARM R4 STEP_UP decision: Shield issues an OpenID CIBA bc-authorize challenge and the action does not execute until an approver carrying the role resolves it (POST /oauth2/bc-authorize/{auth_req_id}/approve via AuthN), OR timeout_seconds elapses (fail-closed: timeout DENYs the action, never permits). One approver role per matching call: when two or more enforce-mode step-up policies of the same effect match one call and name different roles (\"self\" excepted, since any named role outranks owner approval), no single approval satisfies them, so Shield denies the call with step_up_internal_error. Policy authoring lints this as a warning (step_up_role_conflict).',
         aarmRequirement: 'R4',
         promotesCapability: 'CAP-ENF-004',
         decisionEffect: 'step_up',
@@ -181,6 +181,27 @@ export const AARM_ANNOTATIONS = [
             },
         ],
     },
+    {
+        key: 'step_up_unless_granted',
+        description: 'Let an explicit agent grant satisfy this policy\'s step-up approval. When the call is explicitly allowed by an enforcing allow grant on the agent\'s access table, Shield waives the challenge; otherwise the approval is required as usual. If another step-up policy matching the same call lacks this annotation, the challenge is still issued. Restrictions (deny grants) always deny. Bare (value-less) or @step_up_unless_granted(\"true\"); no other value is legal. Requires @step_up_required on the same policy.',
+        aarmRequirement: 'R4',
+        promotesCapability: '',
+        decisionEffect: '',
+        parameters: [
+            {
+                name: 'enabled',
+                type: 'bool',
+                required: false,
+                positional: false,
+                description: 'Always true when present. Accepted spellings are the bare annotation and the string \"true\"; \"false\" is rejected so the annotation cannot be present yet disabled.',
+                default: { kind: 'bool', value: true },
+                min: null,
+                max: null,
+                pattern: '',
+                valueSource: '',
+            },
+        ],
+    },
 ];
 /**
 * O(1) lookup over AARM_ANNOTATIONS. Use this when validating raw

package/dist/guardrails-defaults.gen.js

@@ -3894,22 +3894,77 @@ when {
 const GUARDRAILS_AGENT_IDENTITY_DUAL_ATTRIBUTION_CEDAR = `// =============================================================================
 // Dual Attribution
 // =============================================================================
-// Blocks privileged agent actions that cannot be attributed to a human. "Which
-// agent did this?" is half an answer; the other half is "on whose behalf?" An
-// agent is not an accountable party — the person who pointed it at the work
-// is. Shield projects both sides of that pair, so the requirement can be a
-// policy rather than a reporting convention nobody enforces.
+// Routes privileged agent actions that no human answers for to explicit
+// human approval. "Which agent did this?" is half an answer; the other half
+// is "on whose behalf?" When an agent acts for a person, that person is the
+// accountable party. When it acts for nobody (an autonomous agent, a
+// workload, an api_key-rooted token), its sensitive tool calls run only when
+// someone explicitly authorizes them, never silently and never by default.
 //
 // The agent comes from the authenticated identity, never from the request
 // body: agent_id, agent_type, agent_trust_level, agent_framework. The human
-// comes from the identity claims on the credential, as the \`principal\` record
-// — its \`act_sub\` field names the party the agent is acting for.
-//
-// Deploy in MONITOR mode first. Section 2 blocks unverified agents, and a
-// service key authenticates as unverified until the agent is registered and
-// adopted in Studio. Monitor records what each rule would have blocked on
-// every event without blocking anything; register the agent, then switch to
-// enforce.
+// comes from the identity claims on the credential, as the \`principal\`
+// record. Its \`act_sub\` field names the human the agent acts for, and is
+// absent when there is none: legacy tokens carry the delegating parent (or
+// the api key's creator), while rfc8693 tokens carry it only when the
+// delegation chain is rooted in a user. Autonomous, workload and
+// api_key-rooted rfc8693 tokens have no act_sub.
+//
+// How an agent call with no acting human is authorized: it needs an
+// explicit approval OR an explicit grant.
+//   1. Approval. Section 1 permits the call but suspends it for step-up
+//      approval (@step_up_required, AARM R4, CAP-ENF-004): Shield issues an
+//      OpenID CIBA challenge and the call runs only after an approver with
+//      the named AuthN role approves it; the timeout denies it (fail-closed).
+//   2. Grants. Allow/deny rows in Studio's agent access table compile to
+//      permits (grants) and forbids (restrictions) that Shield evaluates per
+//      agent. A restriction always denies. Section 1 carries
+//      @step_up_unless_granted, so when an allow grant explicitly matches
+//      the call under an ENFORCING access posture, Shield waives the
+//      challenge and the call runs (recorded as step_up_waived_by_grant).
+//      Under the default shadow posture a grant is only observed, so it
+//      waives nothing and approval decides. With no matching grant the call
+//      is challenged under either posture, not denied for lack of a grant.
+//   The waiver needs every step-up policy matching the call to carry
+//   @step_up_unless_granted: another step-up policy without it still
+//   challenges. Shield releases older than the grant waiver ignore the
+//   annotation: there a no-human call needs the approval even when granted,
+//   and under an enforcing posture an ungranted one is denied outright.
+//
+// A call carrying an acting human (act_sub present) is untouched by
+// Section 1, unless the agent is autonomous and not first_party.
+//
+// Customize Section 1 before deploying:
+//   - @step_up_unless_granted: remove it to require the approval even for
+//     calls an allow grant covers (grant AND approval).
+//   - role: must exist in authn.roles ("security_oncall" is a placeholder;
+//     unknown roles reject the policy at deploy time). Another step-up
+//     policy matching the same call must name the same role, or Shield
+//     denies the call (one approval cannot satisfy two roles).
+//   - timeout_seconds: this template sets 3600 (1h); when omitted the
+//     default is 86400 (24h). Bounds [60, 604800].
+//
+// Deploy this policy in ENFORCE mode. Section 1's approval gate exists only
+// in enforce mode: in monitor or alert mode Shield issues no challenge and
+// passes Section 1's Allow through unchanged. Section 1 is a permit, so in
+// a policy set without the baseline permit (organization.permit-baseline)
+// it is what lifts the implicit deny for these calls. In enforce mode that
+// lift is gated on approval (or a grant); in monitor mode the same calls
+// would be allowed with no approval at all, a widening, not an observation.
+//
+// Only Section 2 is safe to observe first. It blocks unverified agents, and
+// a service key authenticates as unverified until the agent is registered
+// and adopted in Studio. Either register and adopt the agents before
+// deploying, or move Section 2 into its own policy, deploy that one in
+// MONITOR mode to see what it would block, and switch it to enforce once
+// the agents are adopted. Mode is per policy, so never put this whole
+// template in monitor to trial Section 2.
+//
+// Change note: Section 3 (autonomous agents must be first_party) used to be
+// a hard block. It is now folded into Section 1, so a non-first-party
+// autonomous agent's sensitive call is routed to approval (or a grant)
+// instead of being denied. To restore the hard block, add the forbid kept
+// in the Section 3 comment below; it overrides approvals and grants.
 //
 // Detection layers:
 //   - agent identity (authentication layer, always available)
@@ -3917,7 +3972,8 @@ const GUARDRAILS_AGENT_IDENTITY_DUAL_ATTRIBUTION_CEDAR = `// ===================
 //
 // Context keys consumed:
 //   - agent_id, agent_type, agent_trust_level: String
-//   - principal: record — act_sub names the accountable human
+//   - principal: record; act_sub names the acting human, absent when the
+//     agent acts for nobody
 //   - tool_is_sensitive: Bool
 //   - tool_category: String
 //
@@ -3929,33 +3985,69 @@ const GUARDRAILS_AGENT_IDENTITY_DUAL_ATTRIBUTION_CEDAR = `// ===================
 // =============================================================================
 
 // ---------------------------------------------------------------------------
-// Section 1: No unattributed privileged action
-// \`unless\` because the rule must fire when attribution is ABSENT, and an
-// absent field cannot be compared — only tested for.
+// Section 1: No-human privileged action requires approval
+// ENFORCE mode only: in monitor mode this permit allows the call with no
+// approval (see the header).
+// Matches when attribution is ABSENT (an absent field cannot be compared,
+// only tested for), and also for autonomous agents that are not first_party
+// even when a human is attached: nobody watches an autonomous agent in real
+// time, and a legacy api_key token names the key's creator as act_sub
+// whether or not that person is directing the call.
+//
+// Cedar is deny-overrides and Shield issues step-up only when the decision
+// is Allow, so this permit must not coexist with a forbid on the same calls:
+// the forbid would deny every one of them and no approval would be asked.
+// To hard-block instead of gating on approval, replace this rule with:
+//
+//   @id("agent-identity.require-principal-for-sensitive-tools")
+//   @name("Block sensitive agent tools without a principal")
+//   @description("Blocks call_tool on a sensitive tool by an agent unless the credential carries a principal whose act_sub names the human the agent acts for.")
+//   @severity("critical")
+//   @tags("category:agent-identity,detection:rule,scope:per-agent,surface:call-tool,owasp:asi01,posture:deny-default")
+//   @reject_message("Tool execution blocked: this agent invoked a sensitive tool with no accountable human attached.")
+//   forbid (
+//       principal,
+//       action == Guardrails::Action::"call_tool",
+//       resource
+//   )
+//   when {
+//       context has agent_id && context.agent_id != "" &&
+//       context has tool_is_sensitive && context.tool_is_sensitive == true
+//   }
+//   unless {
+//       context has principal && context.principal has act_sub
+//   };
 // ---------------------------------------------------------------------------
 
-@id("agent-identity.require-principal-for-sensitive-tools")
-@name("Block sensitive agent tools without a principal")
-@description("Blocks call_tool on a sensitive tool by an agent unless the credential carries a principal whose act_sub names the human the agent acts for.")
+@id("agent-identity.step-up-sensitive-tools-without-principal")
+@name("Permit no-human sensitive agent tools with step-up approval")
+@description("Permits call_tool on a sensitive tool by an agent with no acting human (no act_sub), or an autonomous agent that is not first_party, but suspends it until an approver with the configured AuthN role approves, unless an enforcing allow grant explicitly covers the call.")
 @severity("critical")
-@tags("category:agent-identity,detection:rule,surface:call-tool,scope:per-agent,posture:deny-default,owasp:asi01")
-@reject_message("Tool execution blocked: this agent invoked a sensitive tool with no accountable human attached. Every privileged agent action must name the person it acts for.")
-forbid (
+@tags("category:agent-identity,detection:rule,scope:per-agent,surface:call-tool,posture:deny-default,owasp:asi01,step-up")
+@step_up_required("role=security_oncall,timeout_seconds=3600")
+@step_up_unless_granted
+permit (
     principal,
     action == Guardrails::Action::"call_tool",
     resource
 )
 when {
     context has agent_id && context.agent_id != "" &&
-    context has tool_is_sensitive && context.tool_is_sensitive == true
-}
-unless {
-    context has principal && context.principal has act_sub
+    context has tool_is_sensitive && context.tool_is_sensitive == true &&
+    (
+        !(context has principal && context.principal has act_sub) ||
+        (
+            context has agent_type && context.agent_type == "autonomous" &&
+            !(context has agent_trust_level && context.agent_trust_level == "first_party")
+        )
+    )
 };
 
 // ---------------------------------------------------------------------------
 // Section 2: Trust level gates the blast radius
 // Start in monitor: a service key is unverified until the agent is adopted.
+// Unverified agents are blocked outright, approval or not: registration and
+// adoption come before any per-call authorization.
 // ---------------------------------------------------------------------------
 
 @id("agent-identity.block-unverified-agent-sensitive-tools")
@@ -3978,29 +4070,32 @@ when {
 };
 
 // ---------------------------------------------------------------------------
-// Section 3: Autonomous agents get a higher bar
-// Nobody watches an autonomous agent in real time, so a sensitive tool call
-// from one requires first-party trust rather than merely "not unverified".
+// Section 3 (folded into Section 1): autonomous agents need first-party trust
+// This template used to forbid sensitive tool calls from autonomous agents
+// that are not first-party. A forbid would deny the very calls Section 1
+// routes to approval, so the condition now lives in Section 1 and those
+// calls require approval instead of being blocked. To hard-block them anyway
+// (overriding approvals and grants), add:
+//
+//   @id("agent-identity.restrict-autonomous-agent-sensitive-tools")
+//   @name("Block non-first-party autonomous agent tool use")
+//   @description("Blocks call_tool on a sensitive tool when agent_type is autonomous unless agent_trust_level is first_party.")
+//   @severity("high")
+//   @tags("category:agent-identity,threat:escalation,detection:rule,surface:call-tool,scope:per-agent,owasp:asi04")
+//   @reject_message("Tool execution blocked: autonomous agents must be first-party to call sensitive tools.")
+//   forbid (
+//       principal,
+//       action == Guardrails::Action::"call_tool",
+//       resource
+//   )
+//   when {
+//       context has agent_type && context.agent_type == "autonomous" &&
+//       context has tool_is_sensitive && context.tool_is_sensitive == true
+//   }
+//   unless {
+//       context has agent_trust_level && context.agent_trust_level == "first_party"
+//   };
 // ---------------------------------------------------------------------------
-
-@id("agent-identity.restrict-autonomous-agent-sensitive-tools")
-@name("Block non-first-party autonomous agent tool use")
-@description("Blocks call_tool on a sensitive tool when agent_type is autonomous unless agent_trust_level is first_party.")
-@severity("high")
-@tags("category:agent-identity,threat:escalation,detection:rule,surface:call-tool,scope:per-agent,owasp:asi04")
-@reject_message("Tool execution blocked: autonomous agents must be first-party to call sensitive tools. No human is in the loop to catch a mistake.")
-forbid (
-    principal,
-    action == Guardrails::Action::"call_tool",
-    resource
-)
-when {
-    context has agent_type && context.agent_type == "autonomous" &&
-    context has tool_is_sensitive && context.tool_is_sensitive == true
-}
-unless {
-    context has agent_trust_level && context.agent_trust_level == "first_party"
-};
 `;
 const GUARDRAILS_AGENT_IDENTITY_BLOCK_UNADOPTED_AGENT_SENSITIVE_TOOLS_CEDAR = `// =============================================================================
 // Unadopted Agents: No Sensitive Tool Calls
@@ -4518,11 +4613,11 @@ export const GUARDRAILS_TEMPLATES = [
     {
         id: 'agent-identity.dual-attribution',
         name: 'Dual Attribution',
-        description: 'Block privileged agent actions that cannot be attributed to a human. Deploy in monitor mode first; a service key is unverified until the agent is adopted.',
+        description: 'Require human approval or an explicit allow grant for sensitive agent tool calls that no human answers for (no acting human, e.g. autonomous or workload agents); calls with an acting human pass. Customize the approver role. Deploy in enforce mode: the approval gate does not exist in monitor mode. Adopt agents first (a service key is unverified until then), or trial the unverified-agent block as its own monitor-mode policy.',
         category: 'agent-identity',
         cedarText: GUARDRAILS_AGENT_IDENTITY_DUAL_ATTRIBUTION_CEDAR,
         severity: 'critical',
-        tags: ['category:agent-identity', 'detection:rule', 'surface:call-tool', 'scope:per-agent', 'posture:deny-default', 'owasp:asi01'],
+        tags: ['category:agent-identity', 'detection:rule', 'surface:call-tool', 'scope:per-agent', 'posture:deny-default', 'owasp:asi01', 'step-up'],
     },
     {
         id: 'agent-identity.block-unadopted-agent-sensitive-tools',
@@ -5186,7 +5281,7 @@ export const GUARDRAILS_TEMPLATES_JSON = `{
     {
       "id": "agent-identity.dual-attribution",
       "name": "Dual Attribution",
-      "description": "Block privileged agent actions that cannot be attributed to a human. Deploy in monitor mode first; a service key is unverified until the agent is adopted.",
+      "description": "Require human approval or an explicit allow grant for sensitive agent tool calls that no human answers for (no acting human, e.g. autonomous or workload agents); calls with an acting human pass. Customize the approver role. Deploy in enforce mode: the approval gate does not exist in monitor mode. Adopt agents first (a service key is unverified until then), or trial the unverified-agent block as its own monitor-mode policy.",
       "category": "agent-identity",
       "file": "dual_attribution.cedar",
       "severity": "critical",
@@ -5196,7 +5291,8 @@ export const GUARDRAILS_TEMPLATES_JSON = `{
         "surface:call-tool",
         "scope:per-agent",
         "posture:deny-default",
-        "owasp:asi01"
+        "owasp:asi01",
+        "step-up"
       ]
     },
     {

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from './category-layers.gen.js';
 export * from './decision-effects.gen.js';
 export * from './aarm-annotations.gen.js';
 export * from './aarm-annotation.js';
+export * from './step-up-role-conflict.js';
 export * from './privilege-catalog.gen.js';
 export * from './engine.js';
 export * from './builder.js';

package/dist/index.js

@@ -17,6 +17,9 @@ export * from './aarm-annotations.gen.js';
 // AARM annotation parser/validator (typed parse + fail-closed validation,
 // parity with Go's aarm_annotation.go).
 export * from './aarm-annotation.js';
+// Policy-set lint: warns when step-up policies naming different approver
+// roles can match the same call (Shield denies with step_up_internal_error).
+export * from './step-up-role-conflict.js';
 // Role -> capability privilege catalog (privilege_scope minted into
 // the trusted-service JWT; checked by role-conditioned Cedar policies).
 export * from './privilege-catalog.gen.js';

package/dist/step-up-role-conflict.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Authoring-time lint for @step_up_required role conflicts across a policy set.
+ *
+ * Shield picks one approver role per call. When two enforce-mode step-up
+ * policies of the same effect match one call and name different roles, no
+ * single approval satisfies both, so Shield denies the call with
+ * step_up_internal_error (highflame-shield internal/cedar/annotations.go,
+ * resolveStepUpRole). This lint warns about such pairs before they ship.
+ *
+ * It is a WARNING, not an error: the policy set is valid Cedar and the
+ * conflict only bites on calls both policies match.
+ *
+ * Parity: packages/go/step_up_role_conflict.go.
+ */
+import type { PolicyRule } from './builder.js';
+/** Stable code carried by every StepUpRoleConflictWarning. */
+export declare const STEP_UP_ROLE_CONFLICT_CODE = "step_up_role_conflict";
+/** Owner-approval role. Any named role outranks it, so it never conflicts. */
+export declare const STEP_UP_ROLE_SELF = "self";
+/** Two step-up policies whose roles differ and whose scopes could match the same call. */
+export interface StepUpRoleConflictWarning {
+    code: typeof STEP_UP_ROLE_CONFLICT_CODE;
+    message: string;
+    ruleIdA: string;
+    roleA: string;
+    ruleIdB: string;
+    roleB: string;
+}
+/**
+ * Returns one warning per pair of enabled rules that Shield would treat as a
+ * role conflict if both matched one call.
+ *
+ * The pair rule mirrors Shield's resolveStepUpRole:
+ *  - both rules carry a valid @step_up_required;
+ *  - both have the same effect (a forbid's step-up outranks a permit's, so a
+ *    forbid/permit pair never conflicts);
+ *  - neither role is "self" (a named role outranks owner approval);
+ *  - the roles differ (exact, case-sensitive comparison).
+ *
+ * Overlap heuristic (conservative; exact Cedar satisfiability is out of
+ * scope): the pair warns unless the scope heads clearly cannot match the same
+ * request. Heads are disjoint when the literal action sets do not intersect
+ * (no "*"), or when principal or resource are both exact/`is` constraints on
+ * different entity types, or on the same type with different entity IDs.
+ * `in` (hierarchy) constraints and when/unless conditions are assumed to
+ * overlap. Per-policy mode is not visible in Cedar text, so observe-only
+ * (monitor/alert) policies, which Shield excludes, can still warn here.
+ */
+export declare function lintStepUpRoleConflicts(rules: readonly PolicyRule[]): StepUpRoleConflictWarning[];

package/dist/step-up-role-conflict.js

@@ -0,0 +1,117 @@
+/**
+ * Authoring-time lint for @step_up_required role conflicts across a policy set.
+ *
+ * Shield picks one approver role per call. When two enforce-mode step-up
+ * policies of the same effect match one call and name different roles, no
+ * single approval satisfies both, so Shield denies the call with
+ * step_up_internal_error (highflame-shield internal/cedar/annotations.go,
+ * resolveStepUpRole). This lint warns about such pairs before they ship.
+ *
+ * It is a WARNING, not an error: the policy set is valid Cedar and the
+ * conflict only bites on calls both policies match.
+ *
+ * Parity: packages/go/step_up_role_conflict.go.
+ */
+import { parseAARMAnnotations } from './aarm-annotation.js';
+/** Stable code carried by every StepUpRoleConflictWarning. */
+export const STEP_UP_ROLE_CONFLICT_CODE = 'step_up_role_conflict';
+/** Owner-approval role. Any named role outranks it, so it never conflicts. */
+export const STEP_UP_ROLE_SELF = 'self';
+/**
+ * Returns one warning per pair of enabled rules that Shield would treat as a
+ * role conflict if both matched one call.
+ *
+ * The pair rule mirrors Shield's resolveStepUpRole:
+ *  - both rules carry a valid @step_up_required;
+ *  - both have the same effect (a forbid's step-up outranks a permit's, so a
+ *    forbid/permit pair never conflicts);
+ *  - neither role is "self" (a named role outranks owner approval);
+ *  - the roles differ (exact, case-sensitive comparison).
+ *
+ * Overlap heuristic (conservative; exact Cedar satisfiability is out of
+ * scope): the pair warns unless the scope heads clearly cannot match the same
+ * request. Heads are disjoint when the literal action sets do not intersect
+ * (no "*"), or when principal or resource are both exact/`is` constraints on
+ * different entity types, or on the same type with different entity IDs.
+ * `in` (hierarchy) constraints and when/unless conditions are assumed to
+ * overlap. Per-policy mode is not visible in Cedar text, so observe-only
+ * (monitor/alert) policies, which Shield excludes, can still warn here.
+ */
+export function lintStepUpRoleConflicts(rules) {
+    const candidates = [];
+    for (const rule of rules) {
+        if (!rule.enabled || !rule.customAnnotations)
+            continue;
+        const role = parseAARMAnnotations(rule.customAnnotations).directives.stepUpRequired?.role;
+        if (!role || role === STEP_UP_ROLE_SELF)
+            continue;
+        candidates.push({ rule, role });
+    }
+    const warnings = [];
+    for (let i = 0; i < candidates.length; i++) {
+        for (let j = i + 1; j < candidates.length; j++) {
+            const a = candidates[i];
+            const b = candidates[j];
+            if (a.role === b.role || a.rule.effect !== b.rule.effect)
+                continue;
+            if (!actionsCanOverlap(a.rule.action, b.rule.action) ||
+                !entitiesCanOverlap(a.rule.principal, b.rule.principal) ||
+                !entitiesCanOverlap(a.rule.resource, b.rule.resource)) {
+                continue;
+            }
+            const idA = ruleLabel(a.rule);
+            const idB = ruleLabel(b.rule);
+            warnings.push({
+                code: STEP_UP_ROLE_CONFLICT_CODE,
+                message: `Rules "${idA}" (@step_up_required("${a.role}")) and "${idB}" (@step_up_required("${b.role}")) ` +
+                    'can match the same call but require different approver roles; Shield allows one role per call ' +
+                    'and denies such calls with step_up_internal_error',
+                ruleIdA: idA,
+                roleA: a.role,
+                ruleIdB: idB,
+                roleB: b.role,
+            });
+        }
+    }
+    return warnings;
+}
+function ruleLabel(rule) {
+    return rule.annotations?.id || rule.annotations?.name || '';
+}
+/** Literal action set, or null for a wildcard (or unrecognized shape). */
+function actionSet(action) {
+    const list = typeof action === 'string' ? [action] : Array.isArray(action) ? action : null;
+    if (!list || list.length === 0)
+        return null;
+    const set = new Set();
+    for (const a of list) {
+        if (typeof a !== 'string' || a === '*' || a === '')
+            return null;
+        set.add(a);
+    }
+    return set;
+}
+function actionsCanOverlap(a, b) {
+    const sa = actionSet(a);
+    const sb = actionSet(b);
+    if (!sa || !sb)
+        return true;
+    for (const x of sa)
+        if (sb.has(x))
+            return true;
+    return false;
+}
+/**
+ * Whether two principal/resource constraints could both match one entity.
+ * null means any entity. An `in` constraint names an ancestor, whose type says
+ * nothing about the matched entity's type, so it is assumed to overlap.
+ */
+function entitiesCanOverlap(a, b) {
+    if (!a || !b || a.operator === 'in' || b.operator === 'in')
+        return true;
+    if (a.type !== b.type)
+        return false;
+    if (a.id && b.id && a.id !== b.id)
+        return false;
+    return true;
+}

package/dist/types.d.ts

@@ -6,6 +6,7 @@ export * from './category-layers.gen.js';
 export * from './decision-effects.gen.js';
 export * from './aarm-annotations.gen.js';
 export * from './aarm-annotation.js';
+export * from './step-up-role-conflict.js';
 export * from './privilege-catalog.gen.js';
 export * from './builder.js';
 export * from './errors.js';

package/dist/types.js

@@ -19,6 +19,9 @@ export * from './aarm-annotations.gen.js';
 // AARM annotation parser/validator (browser-safe — typed parse + fail-closed
 // validation; Studio lints with the exact rules Shield runs at sync time).
 export * from './aarm-annotation.js';
+// Policy-set lint: warns when step-up policies naming different approver
+// roles can match the same call (Shield denies with step_up_internal_error).
+export * from './step-up-role-conflict.js';
 // Role -> capability privilege catalog (browser-safe — Studio surfaces
 // the default scope per role; checked by role-conditioned Cedar policies).
 export * from './privilege-catalog.gen.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highflame/policy",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "engines": {
     "node": ">=18"
   },