Repository Access Control Patterns for AI Coding Agents

Repository access control for AI coding agents must control autonomous execution as well as identify the developer’s automated stand-in. Agents read files, invoke tools, delegate tasks, and open PRs across long-running workflows. Effective control therefore requires a layered design that defines intended scope, enforces it at execution time, and preserves enough evidence to explain what happened.

Why human-centric permission models break when agents take the wheel

Traditional role-based access control gives people permissions based on jobs that stay much the same, with each person working in a separate session. Agent tasks do not fit that pattern. An agent can move from repository inspection to shell execution and subagent delegation without returning to a person for each decision. Creating roles such as “code-agent-repo-a” and “code-agent-repo-b” accommodates individual cases, but role proliferation exposes the mismatch between stable roles and task-dependent permissions.

Mohammadreza Rashidi’s execution-security systematization describes repository access, shell execution, prompt injection, and credential leaks as parts of a cascade. Prompt injection supplies an entry point, while shell execution and credential exposure can follow from it. Repository permissions determine how far the damage spreads. The research describes four patched CVEs in production agent execution systems, including startup code injection and project-load data exfiltration that happen before a user confirms trust.

Authentication cannot resolve this chain of failures. Proving an agent’s identity does not establish that its next operation is appropriate for its current task. Authorization must account for the action, the resource, and the conditions at execution time.

What agents actually do to files, and why advisory controls cannot stop it

The agent-native filesystem study looked at 290 public reports of agent filesystem misuse and found two gaps, too little information about what happens to the filesystem and too little control to stop harm before it occurs. These gaps reinforce each other during execution. An approval prompt can show a build command without showing that a malicious dependency will read SSH keys or change shell configuration. After execution, an agent may still misunderstand the result. In one documented case, an agent reported “No problems occurred” immediately after erasing a file.

Instructions do not close this control gap. An agent can ignore “do not read my SSH key,” and prompt injection can override such guidance. An agent can also get past command filters by using operations that do the same thing, such as replacing rm with Python’s os.remove. Blocking one spelling of an operation does not block its effect. Read-only access must therefore be a tool configuration enforced by infrastructure, such as a read-only filesystem mount.

The study proposes moving information and control into the filesystem through three primitives, namely introspect effects, undo mutations, and gate accesses. Introspection exposes what a command will touch, undo preserves intermediate states for correction, and gating enforces progressive permissions during execution. These primitives provide a concrete design vocabulary. On 11 tasks with hidden side effects, the implementation enabled agent self-correction in 8 cases and staged all mutations for user review. On routine tasks, it needed less input from the user and matched baseline success rates, showing that stronger enforcement can work with fewer interruptions.

Scoping agent access with repository-level configuration artifacts

Repository files such as AGENTS.md and CLAUDE.md communicate persistent project instructions, including build commands, test procedures, architecture, coding conventions, and workflow rules. They shape what an agent attempts to do. Their value is explicit, inspectable guidance that does not depend on repeated human prompts. Their limitation is equally specific, because text in a repository cannot enforce filesystem permissions.

An Exploratory Study of Agent Plans for Agentic AI Coding Tools in Open-Source Software examined a narrower, task-oriented artifact. The study screened over 36,710 GitHub repositories and found 85 Markdown plan files across a small number of repositories. Agent Plans, including Cursor’s plan files and equivalents, are hybrid artifacts drafted by an agent, reviewed by a developer, and then used to guide execution. They make intended task scope visible to both parties. The plans in the study often listed steps for implementation, named files and locations, and gave information on testing and validation.

That grounding can reduce hallucinated paths and unauthorized directory traversal by specifying where work belongs. It cannot make those boundaries compulsory. An injected instruction can cause an agent to disregard a plan, while a newly spawned subagent may not inherit the guidance unless explicitly configured to receive it. Configuration artifacts should be paired with infrastructure controls, treating the former as scope definition and the latter as enforcement.

Subagent isolation as a structural access control pattern

Delegation creates a new authorization boundary within a task. An orchestrator may need broad repository access to coordinate work, but a worker changing one module does not need the same reach. Each subagent should have a permission context rebuilt for its task in place of the orchestrator’s credentials. Its own context window, custom system prompt, and access to specific tools help keep it separate. Write access to a single module must be enforced through tool configuration.

Gas Town illustrates how task boundaries can coexist with persistent agent identity. Its Polecats are workers with ephemeral sessions whose identities and work histories survive task completion. Git worktree-backed Hooks and the Beads ledger preserve state across restarts, while each worker’s credential surface is bounded by its task independently of the Mayor coordinator’s credentials. Worktrees separate changes from main and provide a distinct working path. Permission enforcement must still bound what each worker can address.

The Bernstein orchestrator illustrates a complementary division of responsibility. Its Janitor checks tests, lint, types, and PII across parallel workers’ output before that output reaches the merge queue. Its access should cover what it needs for verification, with no broad permission to write. Rashidi’s systematization reports benign but out-of-scope actions at rates up to 17.1% under realistic prompting conditions, while finding no access-control paper in its corpus that addresses that failure mode. Narrow permissions constrain well-intentioned overreach as well as attacks.

Time-of-check-to-time-of-use gaps and the agent-specific race condition

A permission check can become stale before the permitted operation executes. Agent workflows make this gap especially important because execution is multi-step, time-extended, and interruptible. Repository state or credentials can change after an agent establishes that an action is allowed.

A path check provides a concrete example. An agent can validate that a file lies within its permitted path, then write after a symlink has been swapped. The check succeeds against one state, while the write reaches another. Rashidi’s systematization connects this time-of-check-to-time-of-use problem with MCP tool validation races. Tool descriptions can change between inspection and invocation, producing the same validate-then-act failure across a different interface.

The design implication is atomic validation and action at the enforcement layer. Sequential application-level checks leave an interval in which the validated state can change, whereas filesystem-level gating places the access decision at the operation itself. An approval recorded earlier in a task is therefore insufficient evidence that the eventual action was authorized. Audit records must preserve the earlier decision and make the execution context interpretable.

What a useful audit trail for agent access actually captures

Human-oriented audit logs typically record who did what and when. To tell intended execution from manipulation, people investigating agents also need the context for decisions, the order of tools used, and the states between steps. The relevant evidence includes which code the agent touched, which tests informed its work, and whether that context remained current when it acted.

Alibaba Cloud’s Executable Code Knowledge research describes a way to tie this evidence to the source. Each code unit combines stable identity, semantics, executable behavior, contracts, evidence, relations, provenance, validation state, and a query interface, making provenance usable by agents. The ECK prototype matched exact changed-line impact against independent manual labels on all 26 evaluated patches, with precision, recall, and F1 all at 1.0 for 12 unit links. In a separate freshness evaluation, code-structure-bounded fingerprints correctly classified 50 positive changes and 17 unrelated same-file controls, while static rule snapshots found none of the stale cases.

Freshness is therefore part of provenance. Transcript analysis adds behavioral evidence by identifying which tools ran, in what order, and which invocations contributed to the outcome. Calls that do not help with the task still widen the access surface. Live transcripts also expose drift between an agent’s intended skill set and its production behavior that offline benchmarks cannot reveal.

How PR volume from agents strains the access controls downstream of the repository

Agent-generated PR volume tracks parallel execution. A single developer directing multiple agents in separate worktrees can overwhelm review pipelines and merge queues sized for human throughput. Access pressure therefore extends beyond file operations. GitHub shipped a feature in June 2026 that limits the number of open pull requests users without write access may have in a repository, applying a rate-limiting control at the PR boundary.

An agent instructed to get a PR merged can repeatedly re-queue the same change, consuming full CI runs and triggering further work for entries behind it. The operation may be permitted on every attempt. Its frequency can nevertheless turn an authorized workflow into resource exhaustion. A permission model that considers only whether re-queuing is allowed misses the load generated by autonomous repetition.

Giving each queue entry an isolated full-stack environment separates test infrastructure serialization from merge decision serialization, letting the queue serialize the merge decision while testing proceeds independently. Isolation also prevents agents from observing or interfering with other agents’ in-flight changes. Testing access need not imply merging authority.

The recommended operating model follows that separation. Agents should be able to run all tests against a merge-queue-equivalent environment through a separate command that validates mergeability without touching main. The queue retains the merge decision.

Assembling the layered access control model for a software factory

Platform engineers should put these controls together in layers that work with each other, starting with the infrastructure closest to where the agent runs. Read-only mounts, containerized execution environments, and filesystem primitives enforce boundaries independently of agent instructions. Scope artifacts then set out the task through project rules and reviewed plans. Neither layer replaces the other’s function. Infrastructure constrains possible actions, while guidance helps the agent select appropriate actions within those constraints.

Distinct identities and independently scoped subagent credentials keep a coordinator’s broad permissions from spreading through every worker. Fine-Grained Authorization belongs at this layer, where it checks access decisions in real time based on how agents, users, and resources relate to each other. Tool configuration supplies the enforcement boundary for delegated permissions. Freshness-aware code provenance and transcript analysis then make resulting behavior explainable and expose unnecessary tool use.

PR rate controls address submission pressure, isolated test environments separate concurrent work, and agent-operated queue management preserves human escalation paths for meaningful decisions. This is where throughput and authorization converge. A system can permit the right operation yet still fail if it permits autonomous repetition without accounting for shared resources.

The architectural recommendation is composability rather than a monolithic platform configured to cover every layer. Components built for specific jobs cover different enforcement surfaces, while fast changes in agent tooling leave gaps at the edges of all-in-one systems. The software factory needs permissions designed for autonomous execution from the filesystem through the merge decision.