A Tool Gateway That Refuses on Tier, Not on Argument

A refusal is an interface. If you do not define it, every caller interprets your denials differently and every auditor asks a question your logs cannot answer.

The minimal contract has three parts. The status is 403, signalling an authenticated caller who is not permitted. The body carries a stable machine-readable reason code, the requested tool, the required tier and the caller's tier. The gateway writes an authorization record with the same fields plus identifiers that let an investigator join the refusal to a trace.

Auditors ask specific questions about a sensitive action: who initiated it, whether approval was required, which policy allowed it, and whether denies are logged at all the agent audit trail guide. That last point is the one teams skip. A log of successful tool calls cannot show the control is active. The recommended evidence envelope includes agent identity, the human principal or delegation chain, tool and parameters, policy ID and version, decision plus reason, approval record, timestamp, request and trace IDs, tenant and environment, and the outcome of the side effect.

A workable refusal record:

{
  "event": "tool.gateway.refusal",
  "decision": "deny",
  "reason_code": "TIER_INSUFFICIENT",
  "caller_id": "agent:reporting-worker-17",
  "principal_id": "user:8f2c1a",
  "tool": "refund.create",
  "required_tier": "payments-write",
  "caller_tier": "payments-read",
  "policy_id": "tool-gateway-tiers",
  "policy_version": "14",
  "request_id": "req_01J9",
  "trace_id": "4bf92f3577b34da6",
  "tenant": "prod-eu",
  "side_effect": "none"
}

Three fields deserve attention. reason_code must be an enumerated value, not prose, because you will alert on it. policy_version lets you reconstruct which rules were in force, which is what makes replay meaningful: replaying reconstructs the decision from the same principal, tool, resource, policy version and attributes rather than re-running a model the agent audit trail guide. And side_effect: "none" is a claim, not decoration. Your fixtures prove it.

Keep the refusal log separate from prompt text. Prompts belong under a different privacy and retention model than authorization evidence, and mixing them weakens both.

The tier check is only as good as the lookup behind it. Two failure patterns account for most broken implementations.

The first is implicit inheritance. A subagent is a new execution principal with its own instructions and often a narrower task, and treating it as identical to the parent collapses the trust boundary the subagent MCP analysis. Real reports show the consequence: an issue filed against Claude Code describes subagents spawned through the Task tool running shell commands without inheriting the user's configured deny rules the subagent bypass report. Whatever a given product does about it, the lesson is that the tier must be resolved for the calling principal, never copied from a parent by default.

The second is treating an allowlist as authorization. A configured list of permitted tools answers what could ever be called. The gateway answers what is allowed right now for this caller, this action, these arguments and this consent the subagent MCP analysis. Microsoft's guidance draws the same line: deny unreviewed tools by default, and log agent identity, role, effective scope, action, resource, correlation ID and the on-behalf-of user Microsoft's least privilege guidance.

A lookup that respects both:

TIER_RANK = {"anonymous": 0, "basic": 10, "payments-read": 20,
             "payments-write": 30, "admin": 40}

def resolve_caller_tier(principal, agent):
    # Agent tier is bound at issuance. No fallback to the parent's tier.
    record = tier_store.get(agent.id)
    if record is None or record.revoked:
        return None
    human = tier_store.get(principal.id)
    if human is None:
        return None
    # Effective tier is the weaker of the agent grant and human entitlement.
    return min(record.tier, human.tier, key=lambda t: TIER_RANK[t])

The min is the decision rule worth arguing for. An agent acting for a user should never hold more than either its own grant or the user's entitlement. This matters when an agent is provisioned with broad credentials during a pilot and never narrowed, the permission creep pattern Microsoft names as a common cause of excessive effective access Microsoft's least privilege guidance. The broader evidence supports treating this as ordinary access control: among organizations that experienced an AI-related breach, 97 percent lacked proper AI access controls, according to IBM's Cost of a Data Breach Report as cited by AvePoint the AvePoint least privilege guide.

Fail closed on a missing or stale tier record. A lookup that errors and returns a default tier is worse than one that refuses, because the default is almost always the permissive one.

A policy test that passes proves your rule matched a happy case. It does not prove the gateway refuses, and it certainly does not prove the tool was untouched. That is what runtime fixtures add.

The technique is a spy adapter. Wrap every tool in a test double that records invocations, and assert the count is zero on denied paths. Without that assertion, a gateway that returns 403 after silently calling the tool passes your status-code test.

def test_widened_scope_never_reaches_tool():
    adapter = SpyAdapter("refund.create")
    gw = Gateway(tools={"refund.create": adapter},
                 required_tier={"refund.create": "payments-write"})

    resp = gw.handle(caller=caller(tier="payments-read"),
                     tool="refund.create",
                     args={"amount": 10, "order": "o_1"})

    assert resp.status == 403
    assert resp.body["reason_code"] == "TIER_INSUFFICIENT"
    assert adapter.calls == 0
    assert adapter.any_side_effect() is False

Add a parser spy if your gateway has a distinct validation stage, and assert it was never entered for a tier denial. That is the ordering property your design claims.

A second fixture class covers delegation. Spawn a child agent with a narrower tier than its parent, request a tool the parent could use, and assert the child is refused with a reason code naming the tier mismatch rather than a tool-not-found error. That fixture catches inheritance regressions before they reach production.

Note the ordering evidence in the last two rows. A caller who passes the tier check but sends bad arguments gets a 400 with no tool calls, and a misconfigured tier record never falls through to an argument error. If your gateway returns 400 for an unresolved tier, the ordering is backwards and the fixtures say so.

Run these in CI alongside the policy tests. Policy engines are built for this: rules as a separate reviewable artifact, testable in CI with the engine's own runner, independent of the SDK the AI SDK policy tool approvals documentation. The gateway fixtures then prove the tested policy is the one on the request path.

Tier enforcement and human approval solve different problems. A tier is a standing property of an identity. An approval is a one-time decision about one action under one set of conditions. Conflating them produces a gateway that either over-blocks or under-blocks.

Where an action is both high tier and high consequence, the gateway should return a third outcome. Policy engines model it directly: allow runs the tool, deny returns a result the model can reason about, and requires-approval pauses the run until a human responds the AI SDK policy tool approvals documentation. Watch the default. In that SDK an unmatched call normalizes to a status treated as allow, so the documentation recommends adding a default-deny rule the AI SDK policy tool approvals documentation. A gateway without a default deny is one configuration mistake from open.

Approvals must produce evidence, not just a pause. Record the approval ID, who approved or rejected, when, and which request it applied to, linked to the same trace ID as the tool call the agent audit trail guide. Otherwise you can show a human clicked something but not that the control decided correctly.

The oversight literature explains why approvals alone are not a safety story. A position paper argues that current agent design impedes effective oversight and that extended use degrades the cognitive capacity needed for it, so oversight has to be designed for at the interface and organizational level rather than assumed the arXiv paper on agents and human oversight. A gateway that refuses on tier does the opposite of assuming oversight: it keeps the decision out of the human's queue unless the action genuinely needs a person.

The same reasoning applies to escalations that silently stall. When a subagent requests a tool needing consent and no escalation event is routed, the child waits indefinitely and operators cannot tell whether it was denied or never reviewed the subagent MCP analysis. Give approvals a timeout with fail-closed behavior and a deterministic denial reason.

Beyond the runtime fixtures, cover the scope logic itself.

Allowed. The caller holds exactly the required tier and the tool has no other constraints. The caller holds a higher tier. A child agent holds a tier equal to the required tier and its parent holds the same. An approval was granted within the timeout and the tool is dispatched exactly once.

Denied. The caller holds one tier below required. The agent grant is above required but the human entitlement is lower, and effective tier resolves to the lower. The child's tier is below required though the parent's is above. The policy in force raised the required tier for this tool after the grant was issued. A harness attempts a call after its grant is revoked.

Misconfigured. The tool is not registered. The tool is registered without a required tier. The tier store returns null or errors. Tier names in policy and caller record differ by case or whitespace. The default deny rule is missing from the bundle. The gateway runs an older bundle than the tests exercised.

That last case is not hypothetical. The split between gateway enforcement and service-level policy is a known source of drift: gateways standardize coverage while service-level rules add precision, and the two must be monitored for gaps and bypasses the analysis of gateway versus service-level enforcement. A gateway on a stale bundle is one where tested and enforced policy differ.

Two habits close the loop. Emit the policy version on every decision so drift is visible in logs, and alert on refusals during rollout: a spike in TIER_INSUFFICIENT after a policy change is either a legitimate tightening or a misconfiguration, and both deserve a look.

Build the gateway yourself if your tool surface is small and your policy logic is a few dozen rules. The design above is a few hundred lines plus fixtures. What gets expensive is breadth: every tool, every provider, every model, every tenant, plus an audit requirement that each of those has a decision record with a policy version.

That breadth is where a managed boundary earns its keep, and where one entry point for many models simplifies the gateway's own job. When every model call and tool call already traverses one governed path, the tier check has one home rather than one per provider integration. Quanta Inference puts text, image, video, audio and embedding models behind one OpenAI-compatible API, so the model side of your gateway stops multiplying Quanta Inference.

If your team is moving from a proven policy test to a production gateway and wants the surrounding work built with you, that is the kind of scoped build Quanta takes on: describe the gateway, the refusal contract and the fixtures, and a specialist works it through with you Quanta.