Agent autonomy by repository path
How far an agent may go in a repository depends on where it is changing code, not only on how well it has done before. A payments directory can be capped at root-cause analysis while the UI directory allows an automatic attempt, and a handful of paths (CI definitions, migrations, infrastructure) are closed to every agent in every repository.
This sits beside the earned-autonomy ladder (docs/autonomy-ladder.md). The two are intersected:
a run's rung is the lower of its category rung and its path rung. A demotion on the ladder
applies on top of the path cap, and a loose path cap never lifts a demoted category. No rung
reaches merge: the rungs are RCA_ONLY, DRAFT_PR and AUTO_ATTEMPT, and merging stays a
human act.
The autonomy block
In bucker.yml, per repository, under extensions::
version: 2
extensions:
autonomy:
- project: checkout
repository: acme/checkout # a repository this organization has connected
paths:
- { glob: "src/payments/**", maxRung: RCA_ONLY }
- { glob: "src/ui/**", maxRung: AUTO_ATTEMPT }
deny:
- "src/secrets/**"
| Field | Meaning |
|---|---|
paths[].glob, maxRung |
The highest rung a run may hold when its blast radius touches a matching path. Where several caps match, the lowest wins. |
deny |
Globs no agent patch may touch, in addition to the defaults. |
Globs are repository-relative, forward-slashed, with * and **; no leading /, no .., no !.
Matching is case-insensitive, so Infra/x does not slip past infra/** on a case-insensitive
checkout.
The defaults are not optional
These are denied in every repository whether or not a policy is stored, and a file's deny can only
add to them: .github/**, **/migrations/**, infra/**, **/CODEOWNERS, **/bucker.yml,
**/bucker.yaml. They are the paths whose edit changes what runs next with the repository's own
credentials, or who decides what is allowed. An unconfigured project is the defaults, never "no
policy". The policy digest covers the defaults, so a release that changes them changes the digest.
Several repositories in one project
A run's blast radius comes from stack frames through code mappings, which can span repositories, and a run that cannot say which repository a path belongs to must not be judged by the most permissive one. A project's effective policy is therefore the union of every repository's deny globs and the lowest cap per glob.
What it does
- Before a run is queued. The evidence radius is intersected with the policy. A denied path is
dropped from the radius, with the reason recorded where the certificate will carry it. A run left
with nothing it may touch is refused (
403, codeAUTONOMY_PATH_DENIED) before it is queued and before anyone is asked. A cap becomes a risk floor on the proposal (RCA_ONLYis critical,DRAFT_PRsensitive), so an organization that letspr.proposethrough automatically still has to be asked for a run capped atRCA_ONLY. A cap can only make a decision stricter. - For an inbound patch from an outside agent. A patch touching a denied path is refused (
403,AUTONOMY_PATH_DENIED, every offending path named) before validation and long before a sandbox, without opening an approval request. The deny globs also travel on the radius the patch is judged against, so a denied path cannot come back inside a prefix the run owns (test/migrations/…insidetest/). The handoff bundle an outside agent receives carries the same bounded radius. - On the certificate. The certificate's
pathPermissionclaim carries the policy digest, the cap and the paths dropped. It is read off the radius the run was bounded by, and it is covered by the signature. A certificate without the claim predates path policy: "not attested".
Who changes it
autonomy_policy.update is human-only and maps to org:admin (an owner), like the other acts that
change what agents may do. An agent, a delegated OAuth client or any non-owner is refused before the
organization or any policy is read. There are two doors, and both write the row and its audit record
in one transaction:
- the dashboard; and
bucker config apply, with the plan hash.
An agent can never apply a change. It can PLAN the autonomy kind (so a future config.propose
door, which would open a draft pull request only, can carry one), but the apply step re-asserts a
person in their own right, and any pull request is merged by a person and applied by a person. Removing an entry
from the file does not delete its row; narrowing is an edit (set a lower cap), and a policy that
quietly vanished because a line was deleted would be the widest edit there is.
Reading it
The MCP tool autonomy_policy_get (agents toolset, project:read, 500 tokens) returns the defaults,
each repository's stored caps and denies with their digests, and the effective combination. Globs and
repository names are text a person typed, so they are sanitized and declared in trust.untrustedFields.