Skip to content
bucker

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

  1. 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, code AUTONOMY_PATH_DENIED) before it is queued and before anyone is asked. A cap becomes a risk floor on the proposal (RCA_ONLY is critical, DRAFT_PR sensitive), so an organization that lets pr.propose through automatically still has to be asked for a run capped at RCA_ONLY. A cap can only make a decision stricter.
  2. 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/… inside test/). The handoff bundle an outside agent receives carries the same bounded radius.
  3. On the certificate. The certificate's pathPermission claim 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.