A risk-based approval matrix for autonomous coding agents

The problem with blanket repository access

Most teams that adopt coding agents start with a binary decision: the agent either has write access or it does not. That framing collapses several distinct permissions -- proposing a change, modifying files, executing tests, merging to a protected branch, deploying to production -- into a single yes/no. The result is either too much friction (every agent PR needs a human review, even for a typo fix) or too little (the agent can push a destructive migration with the same ease as a docs update).

A more useful model separates what the agent is allowed to do from how much evidence it must supply before doing it. The separation lets you keep routine work fast while forcing a pause on changes that are hard to reverse or that touch sensitive systems.

This guide gives you a concrete, copyable matrix you can commit to your repository today, a walkthrough showing how a single change moves through it, and a review routine to keep the matrix accurate as your team learns what agents handle well and where they need supervision.

Quick-start path

If you need to move fast, do these four things first:

1. Pick one change type your agents already handle -- dependency patch upgrades are a common starting point.
2. Copy the two tables in the next section into a file called agent-policy.md in your repository root.
3. Replace the example rows with your team's actual change archetypes and adjust cell assignments in a 30-minute meeting with your team.
4. Enforce the merge and deploy columns using your existing branch protection rules, not agent self-enforcement.

Then run the policy for two weeks, record exceptions, and revisit. Everything below helps you do that well.

Four dimensions of change risk

Before building the matrix, you need the axes it sits on. Four dimensions cover most of the cases platform teams encounter:

Blast radius. How many services, users, or downstream consumers does the change affect? A CSS tweak in a single-page app has a different blast radius than a shared library version bump consumed by dozens of services.

Data sensitivity. Does the change touch authentication, authorization, PII, financial records, or encryption keys? Changes in these areas carry regulatory and trust consequences that justify higher scrutiny regardless of size.

Reversibility. Can you undo the change with a revert commit, or does it require a data backfill, a coordinated rollback across services, or manual customer communication? Destructive database migrations and permission changes are often practically irreversible once they reach production.

Test confidence. How well do existing automated tests cover the affected code paths? An agent working in a well-tested module provides more evidence of correctness than one modifying code with no coverage.

These dimensions are not independent -- a high-blast-radius change in a poorly tested module is worse than either factor alone -- but scoring them separately makes the reasoning explicit and auditable.

The decision matrix

The tables below map combinations of risk dimensions to five discrete agent permissions. Each row is a change archetype. The first table covers risk classification; the second covers what the agent is allowed to do at each stage.

How to use these tables

Copy both tables into your repository's CONTRIBUTING.md or a dedicated agent-policy.md file so the policy is versioned alongside the code it governs. Replace the example change types in the left column with the archetypes your team actually encounters -- you may have fewer rows or more, depending on your domain. Walk through each cell with your team before enforcing: the blast-radius and sensitivity ratings should reflect your architecture, not a generic assumption. When a new change type appears that does not fit an existing row, add a row rather than forcing it into the closest match. Treat the tables as a living document: every quarterly review (see the review routine below) should ask whether any row needs to move up or down in strictness.

Table 1: Risk classification by change type

Table 2: Permission boundaries by change type

Assumptions baked into these tables

• Classify the actual diff, not the label. A patch release can still break behavior, a docs change can alter executable examples, and a flag can expose sensitive paths. Escalate whenever the actual risk exceeds the row's assumptions.
• Test execution is sandboxed. Tests run only in an isolated environment without production credentials or unrestricted network access. Tests and dependency installation can execute untrusted code.
• CI runs automatically on every PR. If it does not, shift the "Execute tests" column to require human triggering.
• "Auto-review gate" is not human approval. It means a lightweight automated check (linting, diff size, file-path allowlist). You still need to define what that gate checks.
• Deploy permission is never granted to the agent. Teams that want agent-triggered deploys should treat that as a separate policy with its own escalation path.
• Single-repo or well-bounded service scope. Monorepo setups may need path-based scoping on top of this matrix.

This matrix is a starting point. Your organization's tolerance for risk, regulatory environment, and test maturity will shift cells left or right. The value is not the specific cell assignments but the practice of making them explicit and reviewable.

Escalation evidence: what the agent must supply

When a change requires human review, the agent should not just open a PR and wait. The review is faster and better when the agent supplies structured evidence:

• Diff summary. A plain-language description of what changed and why, not just the raw diff.
• Affected systems. Which services, databases, or external integrations are touched?
• Test results. CI status, coverage delta, and any new tests the agent wrote.
• Recovery path. How to revert or roll back if the change causes problems in production. For irreversible changes, what is the mitigation plan?
• Responsible owner. Which human is accountable for this change once merged? The agent cannot own an incident.

Requiring this evidence up front turns the review from "read every line of the diff" into "verify the agent's claims against the diff." The evidence gives the reviewer a starting point; it does not replace inspecting the affected code and checking assumptions the agent may have omitted. Teams using agent-assisted workflows should ensure these evidence requirements are built into the agent's output template, not left to the reviewer to request after the fact.

Adapting evidence requirements to team context

A five-person startup and a platform team inside a regulated enterprise will weight these evidence fields differently. The startup might collapse "affected systems" and "recovery path" into a single sentence because the blast radius of any change is well-known to the whole team. The enterprise team may need "affected systems" to include a link to the service catalog entry and "recovery path" to reference a runbook. Adjust the template to match your review bottleneck: if reviewers already understand the systems but struggle with why the agent made a choice, emphasize the diff summary. If reviewers are on-call engineers unfamiliar with the codebase area, emphasize affected systems and recovery path.

Hypothetical walkthrough: a shared library patch upgrade

Suppose your team uses a coding agent to keep dependencies current. The agent detects that a shared HTTP client library has a new patch release (hypothetically, version 2.3.1 to 2.3.2) with a security fix.

Step 1: Classify the change. The agent checks the matrix. This is a non-breaking dependency upgrade (patch). Blast radius is "single service" if the library is pinned per service, but "multiple services" if it is in a shared lockfile. Suppose it is shared -- the agent escalates to the "breaking dependency upgrade" row to be conservative.

Step 2: Propose and modify. The agent updates the lockfile and opens a PR.

Step 3: Execute tests. CI runs. Integration tests across affected services pass.

Step 4: Supply escalation evidence. The agent attaches: a summary ("Bumps http-client from 2.3.1 to 2.3.2; patches CVE-XXXX-XXXXX"), the list of six services that import the library, CI results showing all green, and a recovery path ("Revert the lockfile commit; previous version is cached in the artifact registry").

Step 5: Human review. One reviewer checks that the CVE is real, the changelog matches the agent's summary, and the integration tests are meaningful for the affected paths. The reviewer merges.

Step 6: Deploy. The standard deploy pipeline handles rollout. The agent has no deploy permission.

Now consider an exception: the CI run reveals a flaky test unrelated to the upgrade. The agent flags the flaky test but does not suppress it. The reviewer decides whether to merge with the known flake or fix the test first. The agent does not make that judgment call -- it supplies the evidence and stops.

This distinction matters. The agent's job is to reduce the cost of proposing and documenting a change, not to make risk-tolerance decisions on behalf of the team.

Failure symptoms, corrective actions, and escalation points

Measurement limits to acknowledge

This matrix relies on classification, and classification is only as good as the metadata available. Some limits worth stating plainly:

• Blast radius is hard to compute automatically. Static analysis can approximate it, but runtime dependencies, feature flags, and data pipelines create indirect coupling that tooling may miss. Do not assume the agent's blast-radius estimate is complete.
• Test confidence is not binary. A module with high line coverage but no integration tests may give false assurance. The matrix treats test confidence as a scalar, but in practice you need to judge the kind of coverage, not just the percentage.
• Agent self-assessment is unreliable for novel changes. If the agent encounters a pattern it has not seen before, its risk classification may be wrong. The matrix should default to escalation when the agent's confidence in its own classification is low.
• The matrix does not prevent social engineering. Enforce merge and deployment permissions outside the agent's control. Input validation and file-path allowlists are complementary controls, not substitutes for the matrix.
• Exception logs require honest recording. If overrides are not logged, the review routine has nothing to work with. Make logging the override easier than skipping the log.

Ongoing review routine

A matrix that never changes will drift out of alignment with your codebase, your team's skills, and the agent's capabilities. Schedule three recurring reviews:

Weekly (10 minutes): Spot-check agent merges. Pick two or three agent-merged PRs from the past week. Verify the classification was correct, the evidence was present, and no unexpected files were touched. This is not a full audit -- it is a smoke test that the auto-review gate is working. Rotate this responsibility across the team so no single person becomes the bottleneck or the only one who understands the policy.

Monthly (30 minutes): Review the exception log. Pull up every override and misclassification from the past month. Ask three questions: (1) Did any override lead to a problem? (2) Are there change types that get overridden so often the matrix row should change? (3) Are there new change types the agent is handling that have no row in the matrix? Update the matrix tables and commit the change to the repository.

Quarterly (60 minutes): Reassess dimensions and permissions. Zoom out. Has the team's test coverage improved enough to loosen a permission? Has a new service or data store been added that changes blast-radius assumptions? Has the agent's behavior changed after an update? This is the time to add or remove rows, adjust the evidence template, and check whether the deploy boundary still makes sense. Bring incident data and the monthly exception summaries to this meeting. Examining engineering delivery across both agent-authored and human-authored changes can inform this review, though the matrix revision itself is a team judgment call.

Where to start: next-action checklist

• Choose one change type your agents already handle (e.g., dependency patch upgrades).
• Copy the two tables above into agent-policy.md in your repository root.
• Replace example rows with your team's actual change archetypes.
• Walk through cell assignments with your team; adjust for your architecture and risk tolerance.
• Define what your auto-review gate checks (linting rules, diff size limit, file-path allowlist).
• Build the escalation evidence template into your agent's PR output format.
• Enforce merge and deploy permissions via branch protection rules, not agent self-enforcement.
• Create a shared document or channel for logging overrides and exceptions.
• Schedule the first weekly spot-check and monthly exception review.
• After two weeks, review the exception log and decide whether to extend the matrix to a second change type.

Pick the narrowest scope that lets you learn something real. A versioned policy file with four rows your team actually discussed will outperform a comprehensive document nobody references. Name the people accountable for exceptions, commit the matrix alongside the code it governs, and revise it after real outcomes -- not on a theoretical schedule. For more practical approaches to engineering workflow decisions, see our guides.