Capability Authorization Gate

Capability Authorization Gate

Overview

Self-aware agents must understand their own capabilities and limitations. The Capability Model Pattern (Ch3, Example 3-5) makes operational parameters explicit, queryable structure: each capability declares what it requires, an authorization-level, and an optional quantitative limit. During planning the agent determines whether it has the access, authorization, and headroom to fulfill a request before attempting it — and routes/escalates when it does not.

The chapter's worked example: a Customer-Support-Agent can Answer-Product-Question (Public, needs only Product-Knowledge) but Process-Refund requires Supervisor authorization, Financial-System-Access, and caps at 500 USD. A 600-USD refund must be recognized as exceeding authority and routed appropriately — "creating more reliable, trustworthy automation with appropriate human oversight" — instead of attempting a prohibited action.

The gate returns three decisions:

• allow — capability declared, granted auth level >= required, all required resources present, amount (if any) within limit.
• escalate — the agent itself cannot, but a higher authority could: authorization too low, a required grant missing, or the amount over the limit. This is the "route appropriately" path.
• deny — the capability is undeclared. The agent has no such ability at all.

The DevOps manifestation (anchored in fictional AWS account 123456789012): capabilities like read_metrics (Public), query_logs (User), restart_instance (Supervisor + ec2:write), and scale_autoscaling_group (Supervisor, limit 10 instances) become the queryable authority model that gates tool orchestration in Ch6. A User-level latency investigator can read metrics and logs but escalates a restart or an over-limit scale.

When to Use

• An agent must decide "can I do this?" before invoking a tool or taking an action
• Modeling agent operational boundaries (authority, required grants, limits)
• Building the queryable authority layer that gates tool orchestration (Ch6)
• Implementing graceful escalation/routing instead of attempting prohibited actions

Phrases: "capability model", "can the agent do X", "authorization level", "operational limit", "escalate", "refund limit", "agent authority", "queryable authority", "tool authorization gate".

When NOT to Use

• Human RBAC/IAM enforcement. This is the agent's planning-time self-check, not your platform's identity policy. Real credential checks still happen at the API boundary.
• Validating the capability NODE shape. Use schema-pattern-selector (capability_model validation) to confirm a capability declaration is well-formed; this skill consumes well-formed declarations and decides.
• As the only security control. The gate prevents the agent from ATTEMPTING an over-authority action; it does not replace server-side authorization. Defense in depth: gate at planning AND enforce at the boundary.

Process

Rationalizations

Red Flags

• Gate returns allow for an action the downstream API then rejects. The agent's granted_resources/level are out of sync with reality — refresh the capability model from the actual authority source.
• Everything escalates. The agent's granted_level/resources are under-provisioned, or the capability declarations over-require. Re-check the spec; constant escalation defeats automation.
• A capability has a limit but callers never pass an amount. The gate warns; an unchecked limit is a silent over-authority risk. Always pass the amount for limited capabilities.
• deny for a capability the agent clearly should have. The capability is missing from the declaration — add it, do not work around the gate.

Non-Negotiable Verification

1. Run the benchmark battery. python cli.py benchmark must report 10/10:
   • Public capability with resources -> allow
   • $600 refund over $500 limit -> escalate (reason cites the limit)
   • undeclared capability -> deny (distinct from escalate)
   • Supervisor + resources allows $400 but still escalates $600
   • DevOps: User escalates restart_instance and over-limit scale, allows read_metrics
   • unknown authorization level raises at construction
2. Run the scenarios. python cli.py scenario support-refund and python cli.py scenario devops-latency print allow/escalate/deny across the chapter's cases (DevOps anchored in AWS account 123456789012).
3. Verify CLI help. python cli.py --help exits 0 and prints this SKILL.md description (so any harness can discover the skill from --help).

Security Posture

• Prompt injection. The agent spec JSON is untrusted configuration: an adversarial spec that inflates granted_level, pads granted_resources, or raises a capability limit turns the gate into a rubber stamp. The gate never executes spec content - load specs only from the real authority source, not from agent- or user-supplied text.
• Data exfiltration. No network calls, no file writes. Capability declarations may reveal internal authority topology; decisions go to stdout and the caller owns downstream piping.
• Privilege escalation. The gate is itself an anti-escalation control, but it is planning-time and advisory: an "allow" grants no credential, and a bypassed gate must still hit server-side IAM at the API boundary. Defense in depth - never let this replace boundary enforcement.

Source Attribution

Distilled from Agentic GraphRAG (O'Reilly, by Anthony Alcaraz and Sam Julien) Ch3 — Knowledge Representation, section "Capability Model Pattern" (Example 3-5: the Customer-Support-Agent with a $500 refund limit that escalates a $600 request). The DevOps capability-as-queryable-authority manifestation is from "Applying schema patterns to infrastructure", feeding the tool-orchestration authority model in Ch6.