Permission Tests That Catch a Widened Subagent Tool

Before writing an assertion, write down what each tier may reach. A workable starting point, derived from the approval table above:

The decision rule: a tool belongs to the highest tier any single invocation can reach, not the average of its uses. A file tool with a --force flag, or a shell tool exposed through an exec wrapper such as watch, is privileged, because approving a narrow-looking command can grant the full wrapped capability. The Claude Code docs call out exec wrappers and find actions as a specific place where approval scope is easy to misjudge (Claude Code permissions).

Least privilege for agents means granting only the data, systems and actions the current task requires, for as long as the task takes (AvePoint on AI agent least privilege). Microsoft's guidance adds the operational version: deny unreviewed tools, plugins and cross-tenant paths by default, and re-review access when workflows, tools or data scope change materially (Microsoft's least privilege pattern). Every material change is a diff, and every diff is what your suite should catch.

Fixtures must describe what the subagent can actually call after policy evaluation, not what the policy file says. The useful shape is: a subagent definition, a policy input, and the expected allowed set per tier. Then the test resolves the policy and compares sets.

Keep the fixture next to the policy so a change to either is visible in the same diff:

# fixtures/reporting-subagent.yaml
subagent: reporting-subagent
tier: read-only
context:
  parent_session: analytics
  delegated_token: child-bound
expect:
  allowed: [fs.read, grep, search.logs]
  denied: [fs.write, bash, web.fetch, deploy.release]
must_not_expand: true

The must_not_expand flag is the one that matters. A read-only fixture whose resolved set is a strict subset of the expected set passes; a resolved set containing anything outside it fails, even if the extra tool is never called in the happy path. This inverts the usual test habit of asserting success cases only.

Beware of fixtures copied from production configuration. Organizations grant broad roles to unblock pilots and then never narrow them as workloads stabilize, and layering several narrow roles can create overly broad effective access that is easy to underestimate without an aggregate analysis (Microsoft on agentic identities and RBAC). So the fixture should state intent, and the resolver should read the real policy. If the two disagree, the test fails, which is the point.

For the widened case described in the article brief, the fixture is deliberately adversarial: allow fs.write inside docs/ and tool: bash must be absent from the resolved set. When someone adds bash to the docs-editor policy to "make the agent more capable", the test fails on the allowlist comparison rather than after a shell command ran on the build host.

If your team writes policy in Rego, the AI SDK's OPA integration is a ready reference: policies live as .rego files, are testable in CI with opa test, and map to allow, deny, requires-approval and not-applicable decisions, with unmatched calls defaulting to allow unless you add a default deny (the AI SDK policy tool approvals docs). Add default deny to any fixture that models read-only or scoped-write tiers.

Three assertion families cover most of the risk, and they compose.

Set containment. Resolve the effective tool set for each fixture and assert that every member belongs to the tier's allowed set. This catches new tools and inherited ones. Implement it as one test per tier so the failure message names the tier.

# tests/test_tool_scope.py
import pytest
from scope import resolve_tools, TIER_ALLOWED

@pytest.mark.parametrize("fixture", load_fixtures("fixtures/"))
def test_resolved_tools_within_tier(fixture):
    resolved = set(resolve_tools(fixture.subagent, fixture.context))
    allowed = set(TIER_ALLOWED[fixture.tier]) | set(fixture.expect.allowed)
    extra = resolved - allowed
    assert not extra, f"{fixture.subagent} ({fixture.tier}) exceeds tier: {sorted(extra)}"

def test_readonly_agent_cannot_reach_shell():
    resolved = resolve_tools("reporting-subagent", {"parent_session": "analytics"})
    assert "bash" not in resolved
    assert "fs.write" not in resolved

Deny wins. Every tier above read-only gets at least one assertion that a specific denied tool is absent even when the parent session holds a token that could perform it. This is the direct test for silent token inheritance: if the resolver reports fs.write for a read-only child because a broad parent token was reused, the test fails. The recommended pattern is no inheritance by default, with child-bound, scope-minimized, time-bounded credentials (Permit).

Decision record shape. Assert that the resolver emits the fields an auditor would ask for: agent identity, tool, resource, action, policy version, decision and reason, approval if any, and correlation ID (Permit on audit trails). This is a cheap test that pays off when someone asks how you know the control is live.

A fourth, optional family: negative tests on the resolver itself. Feed it a policy that grants bash to a read-only tier and assert the resolver plus test combination produces a failure. A permission suite that has never failed on a known-bad policy is unverified. Treat that as an adversarial probe: invoke the resolver with an intentionally widened policy in a test that expects rejection, which is the same logic described for callable testing subagents whose output must be reproducible and whose privileges cannot self-expand (NHI glossary on callable testing sub-agents).

For decision history over time, not just arguments of the current call, pass the run history into the policy input and assert on it: require approval after N writes, deny a second irreversible action in the same conversation, cap cumulative spend (AI SDK policy docs). Those checks are deterministic and belong in the same suite.

The gate is the simplest part and the most often skipped. Put the permission suite in its own CI job, make it required, and make it fast enough that nobody is tempted to mark it optional.

# .github/workflows/permissions.yml
name: permissions
on: [pull_request]
jobs:
  scope:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: opa test policy/ -v          # policy-level checks
      - run: pytest tests/test_tool_scope.py -q   # resolved-set checks

Two properties make this a real blocker. First, the job must run on changes to policy files, agent definitions and fixtures, not only on application code, otherwise a policy-only pull request slips through. Second, scope the credentials used to resolve effective permissions as narrowly as the tier under test, because a suite that itself runs with a broad token can mask an inheritance bug. Microsoft's guidance to test revocation paths and to log effective scope with a correlation ID applies to the CI job as much as to production (Microsoft).

A worked release decision makes the value concrete. Suppose the docs-editor subagent ships with four allowed tools and one pending pull request adds bash to its policy to let it run a formatter. The set-containment test fails on the scoped-write fixture, the job exits non-zero, and the release is held. The author has two legitimate fixes: keep the agent's scope and move formatting into the build pipeline, or promote the agent to the privileged tier, which requires the approval path and the audit fields that tier demands. Either choice is a visible, reviewed decision rather than an inherited one.

Keep the suite honest with three rules. Run the negative resolver test on every build so the suite can fail. Store the fixture set in version control alongside the policy so reviewers see them in one diff. Review any test deletion as a security change, because deleting an assertion is the cheapest way to widen scope without touching the policy.

If your subagents run across several model providers, or you are standardizing the policy layer while you build this out, Quanta Inference puts text, image, video, audio and embedding models behind one OpenAI-compatible API key, which keeps the model call out of the fixture and the scope check where it belongs (https://quantaintelligence.ai/inference).

Tests do not remove the need for approval; they define which tier requires one. The tier table above already encodes that: privileged tools pause for a human, read-only tools do not. Keep the approval record in the same evidence chain as the decision, so a sample of a sensitive action shows the policy required approval, a named person approved at a time, and the side effect ran, all joined by one trace ID (Permit on audit trails).

Two failure modes to test for explicitly, because they are invisible in happy-path runs. Silent stalls: a subagent requests an approval that never routes, and the child waits indefinitely with no deny and no retry signal; the fix is an explicit escalation channel with a timeout that fails closed and a deterministic denial reason (Permit). And allowlist-only trust: payments-prod is in the server list, so a subagent whose task was "draft customer response" can call refund.create, because the allowlist defined connectivity and nobody checked intent at runtime. Your fixture for that agent should be scoped-write with refund.create absent, and the test should fail the moment it appears.

There is a broader design argument for keeping humans meaningfully able to review these boundaries: oversight degrades when the approval surface does not show what an action would permit, and human oversight of agents should be designed rather than assumed (Mitchell, Ghosh and Passi on agents and human oversight). A permission suite is one of the few places where that design is written down in a form a machine enforces.