Review an agent policy change as a behavioral diff

A policy change adds one permit. In the code review, it looks small. At runtime, it may authorize a new operation for many agents.

Before approving it, ask what the agent will be able to do that it couldn't do before. Write that answer beside the tests, rollout steps, and recovery plan so the next reviewer can check it.

Write the proposal before the rule

Consider a hypothetical deployment agent that can currently inspect staging status. The proposed change lets it restart a staging service, but not deploy to production.

Here's what the review could look like:

Change: allow staging-service restart for deployment-agentIntended new allow: restart the approved staging serviceMust remain denied: production deployment, other services, other agentsPolicy scope being changed: agentOther applicable scopes: organization, tenant, workspaceInput contract: resolved tool identity; no caller-asserted environment overrideEvidence: synthetic decision matrix plus historical decision-diff reviewRollout: controlled staging requests, then intended application workflowRollback trigger: any unintended new allow or loss of required status readsRecovery: restore the prior agent bundle and verify observed decisionsOwners: service owner approves the effect; security approves authority

This is an illustrative review record, not deployable policy or a completed change.

The authorization foundation explains effective rules and decision boundaries. The proposal applies that model to a change another reviewer can accept or reject.

Check the other rules that still apply

Dome's authorization model combines applicable organization, tenant, workspace, and agent rules.

The edited agent bundle is therefore only part of the decision. A broad permit elsewhere may already allow the operation; a higher-scope forbid may prevent it. In the first case, adding a narrower permit does not narrow access. In the second, the new permit cannot override the forbid.

Ask to see the other applicable rules, including generated access rules. The edited file might add no new permission at all—or grant more than intended if another condition changes with it.

Treat input changes as part of the policy change

If the rule depends on a label, represented-user claim, or operation argument, include its producer and meaning in the review.

Renaming a service tag can change authorization without changing rule text. Removing a claim from the identity mapping can break a delegated workflow. A new tool version can move the operation selector to another argument.

Review those changes together when they affect the same boundary. Otherwise, the code repository contains a perfectly reviewed rule while the runtime supplies different facts.

For the staging example, using a resolved staging tool avoids depending on an environment string asserted by the agent. If that assumption changes, reopen the review.

Show what becomes allowed—and what stays denied

Use the authorization test procedure to produce the synthetic cases and historical decision differences. Do not paste only a successful simulator screenshot.

The reviewer needs to see the intended new allow, the neighboring operations that remain denied, and previously legitimate calls that must keep working. Each historical deny-to-allow result needs an explanation; each allow-to-deny result needs a service-impact assessment.

Dome's simulation tools support these checks without performing the remote action. Keep live identity and backend verification in the evidence packet where the change depends on them.

Decide when to roll back

Record the prior bundle and the expected runtime decision after synchronization. Watch the approved staging workflow and the chosen negative controls, not only aggregate error rates.

Rollback is a change too. Restoring the earlier bundle should be followed by a request-level check that the intended behavior returned. Do not promise that a successful management write immediately changed every gateway decision.

If rollback would restore authority now known to be unsafe, prefer the prepared containment action and repair the policy. “Return to the old version” is not automatically the right incident response.

Keep the process proportionate

A small team can keep this record in its ordinary change review. It does not need a separate policy bureaucracy. Larger estates can reuse the same fields across teams so reviewers recognize the evidence.

Try the template on your next rule change. Before approving it, a reviewer should be able to say: “This agent can now restart this staging service; production deployment is still denied.” If that sentence is hard to write, the permission needs another look.