Skip to main content

Agent Role Contracts · Open source

Catch role and scope conflicts before agents run.

Who implements, who reviews, and which files may change. ARC checks those declared rules against the task you hand to your agents.

Release
1.0.1 on npm (latest)
License
MIT
Runtime
Node.js 22.5 or later
Network
To download the source or package. Checks run offline.

Stable release 1.0.1 · MIT license. Public feedback has changed the evaluation guidance and design documents. Listed in awesome-agent-trust after maintainer review.

Netsujo Agent Role Contracts badge

Change one file path. See the conflict disappear.

The implementer is assigned src/**. Select a task inside that scope to change this example from FAIL to PASS.

This switches between two preset results. Run the actual checker with the commands below.

Implementing role
implementer
Declared write scope
src/**
Choose the requested file

Choose the task inside src/** to fix the conflict.

FAILThe requested file is outside the declared scope.

secrets/production.txt is outside src/**, the scope assigned to the implementer.

View the sample output
FAIL: explain (declarations only; execution NOT authorized)
TASK_WRITE_SCOPE_OUTSIDE_AUTHORITY task/inputs/scope:
  Task scope is outside declared write scopes for role implementer: secrets/production.txt

ARC checks declarations against a task. Your execution environment manages actual permissions.

Developer feedback from a self-reported synthetic, non-sensitive task trial of the ARC 1.0.0 standalone consumer starter, not a production deployment. This page covers 1.0.1.

It still catches declaration vs write-scope mismatches that prompt instructions alone miss.
— Prashant Chaurasiya, founder of Aryabhatt AI

Catch mistakes in the rules you hand to agents

Each result below comes from a fixture shipped in the 1.0.1 stable package.

  1. AUTHORITY_CONTRADICTION

    A role cannot be read-only and allowed to write

    A role that lists filesystem.write.scoped as both allowed and prohibited, or as read-only, is flagged.

  2. SELF_REVIEW_DECLARED

    The implementer cannot also be the reviewer

    A route that names one role as both implementer and reviewer is rejected, along with reviewers that are not read-only.

  3. ROLE_REFERENCE_UNKNOWN

    Roles must refer to roles that exist

    A relation that points to a role missing from the bundle, such as ghost, is reported instead of ignored.

Run the same check on your computer

With Git, Node.js 22.5 or later, and npm installed, run these commands in a folder without an agent-role-contracts directory. No API key or account is required.

git clone --depth 1 --branch v1.0.1 https://github.com/suirindo/agent-role-contracts.git
npm --prefix agent-role-contracts run demo --silent

The demo runs PASS → expected scope FAIL → repaired PASS. It requires no dependency installation. Git needs a network connection to download the versioned source.

Next, try your own task using the npm package below. Keep the role declarations and change the task for each new request.

Check a task with the npm package

Install the released package into an empty folder and check the bundled starter fixtures.

mkdir agent-role-contracts-first-check
cd agent-role-contracts-first-check
npm init --yes
npm install --ignore-scripts @netsujo/agent-role-contracts@1.0.1
npx --no-install agent-role-contracts explain \
  --bundle node_modules/@netsujo/agent-role-contracts/examples/starter-bundle.json \
  --task node_modules/@netsujo/agent-role-contracts/examples/starter-task.json \
  --format text

Expected output (Example, excerpt)

PASS: explain (declarations only; execution NOT authorized)
Accountable: implementer
Reviewers: reviewer
Human approval required: true
  • validate checks the bundle alone.
  • explain also checks one task’s write scope.
  • handoff checks a handoff document you supply separately.

Exit codes: 0 means PASS, 1 means a rule was violated, 2 means a CLI or file problem with no verdict.

To see a FAIL, swap starter-task.json for starter-task-outside-scope.json.

What a PASS means

It does mean

  • The declarations you supplied are consistent under the rules this version applies.
  • Only checks performed by the selected command count: validate covers the bundle; explain adds the supplied task; handoff also checks the supplied handoff.

It does not mean

  • Anything was executed, sandboxed, or enforced. It is not an agent runner or a sandbox.
  • Anyone’s identity or any evidence was verified, or the filesystem was scanned.
  • An agent’s output matches a schema, or a merge or deploy is approved.
  • The work is safe. Output of the command always says execution is NOT authorized.