Declare traits and bounds

Use this when you want a bag to publish policy: a named grant of tools that a session can select, or a named restriction that takes access away. A bag declares both in bag.yaml, with no code, so a team can share one policy bag across identities. The example is review-policy, which grants read-only access to the octo bag from Write a tool and keeps the agent away from credential files.

Before you begin

• Create a bag, or use an existing one. A policy bag needs only a bag.yaml.
• Know the namespaces you want to grant. A bag’s tools carry their namespace, usually the bag’s name.

Know the traits a bag gets for free

A bag that provides tools or skills gets two automatic traits, named after it:

• <bag> grants every tool namespace and skill the bag provides, with read and write access. A bag that composes others with bags: absorbs their namespaces and skills too.
• <bag>:read includes <bag> and carries the readonly bound. Bounds merge across a session, so selecting it makes the whole session read-only, not only the bag’s tools.

A bag that provides no tools and no skills, such as a policy bag, a service-only bag, or a bag of actions, gets no automatic traits. To replace the automatic ones, declare a trait with the bag’s own name, or one named read for the read-only twin.

Declare the traits, bounds, and constants

name: review-policy
description: A read-only reviewer trait over the octo bag, kept away from credential files.

constants:
  credential-files: ["*.env", "*.pem", "~/.ssh/**"]

bounds:
  no-credentials:
    description: Keep file tools away from credential files
    bound:
      files:
        deny: {constant: credential-files}

traits:
  reviewer:
    description: Read GitHub through octo, with writes and credential files out of reach
    bags: [octo]
    access: read
    bounds: [no-credentials, readonly]

Each section does one job:

• constants names a value once. A {constant: name} reference replaces the whole value before Barry validates the manifest, so a list two bounds share stays in one place. To use another bag’s constant, write {constant: bag:name} and compose or require that bag.
• bounds declares named restrictions. Each has a description and a bound in the shape the bound reference describes. The schema is strict, so a misspelled key fails the manifest instead of restricting nothing.
• traits declares named grants. Each needs a description. bags lists the tool namespaces it grants; a bag’s tools carry the bag’s name as their namespace, so these are usually bag names. access is read or readwrite, and bounds names restrictions it carries. A trait can also list skills, instructions, other traits it includes, and an inline bound.

access defaults to read on a declared trait, and Barry reads write as readwrite.

Name things the way Barry qualifies them

Barry gives every trait and bound a bag declares the bag’s name as a prefix. In this bag, reviewer becomes review-policy:reviewer and no-credentials becomes review-policy:no-credentials. Inside the manifest, refer to your own declarations by their bare names; Barry qualifies those references too. Refer to another bag’s trait or bound as bag:name, and to a shipped bound such as readonly by its plain name.

The one exception is a trait named after its bag: it keeps the bare name, so it can replace the bag’s automatic trait. A bag can’t declare a name under another bag’s prefix.

Sync the declarations

Install and pack the bag; packing syncs its traits and bounds into Barry:

Terminal

barry install ~/repos/review-policy
bonanza pack review-policy

After you edit traits: or bounds: in a packed bag, run barry bag sync-traits review-policy to sync them again.

Verify

To list every trait with what it grants, run:

Terminal

barry trait list

The list includes review-policy:reviewer, with octo as its namespace, read access, and its two bounds. barry bound list shows review-policy:no-credentials and its file patterns. To use the trait, start a session with it:

Terminal

bonanza session start --traits review-policy:reviewer

The session has the octo read tools and no write tools.

If it fails

• The manifest fails to parse. A key under bound: or a trait is misspelled, or a constant reference has keys besides constant. Run barry bag check on the bag to see the key.
• A session with the trait refuses to start. A bound or trait it names doesn’t exist. Qualify another bag’s trait or bound as bag:name, and pack the bag that declares it.
• The session lacks tools the trait grants. Install and pack the bag that provides the namespace. See Troubleshooting.

What’s next

• Policy resolution for how grants and bounds combine in a session.
• Empowering with traits to choose traits for sessions.
• Restricting with bounds for the shipped bounds.
• The bag.yaml reference for every trait and bound field.