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.
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/**
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.txtARC 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.Catch mistakes in the rules you hand to agents
Each result below comes from a fixture shipped in the 1.0.1 stable package.
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.
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.
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 --silentThe 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 textExpected 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.
Public verification, listings, and documentation
- README for 1.0.1Commands, schemas, and fixtures.
- Use ARC in your repository (experimental)Source-only setup examples for the published 1.0.0 checker. Choose one entry point.
- Current workflow evaluation kit (experimental)Use two checkouts: arc-kit for the current source-only helper on main, and arc-v1 for the fixed v1.0.0 core under evaluation. Record the helper commit separately. Start with a synthetic baseline, then compare one real workflow with your existing controls.
- Workflow evaluation guide for 1.0.1The guide included in the stable release; use the current kit above for the two-checkout setup.
- npm package@netsujo/agent-role-contracts@1.0.1
- Watch the 30-second overviewIntroduction recorded for version 0.5.0; this page covers 1.0.1.
- GitHub repositoryPublic source and issues. The maintainer ran a synthetic four-case comparison with ShipRules-free; counterpart execution and review remain pending. Feedback on role and path mapping was incorporated into the evaluation guide.
- openPR press releasePublished English press release.
- Trust infrastructure R&DHow this declaration layer fits into Netsujo Agent OS and the broader trust-infrastructure direction.
- Three conditions revised through public dialoguePublic feedback changed authority provenance, evidence attribution and retry conditions. The October 31 update separates bounded native observations from ARC enforcement: no extra native enforcement was demonstrated. Human-value measurement across two genuine tasks remains open.
- What a PASS establishesThe technical article, including where the checker stops.
- Listing in awesome-agent-trustSelf-submitted; on 2026-10-30, added to this third-party curated list after maintainer review. A listing, not a security audit, certification, or evidence of production use.
- Listing in awesome-ai-coding-toolsOn 2026-10-30, added to launchapp-dev's list by an automated bot merge.
- Listing in awesome-ai-agent-toolsOn 2026-10-19, added to michielhdoteth's list by an automated bot merge.
- Listing on SilentStarsOn 2026-10-31, accepted by this directory's automated review. Not an expert endorsement.
- AlternativeTo product profilePublic product profile, checked on 2026-10-31. See the README above for current specifications.
- SaaSHub product profileSoftware comparison directory. Checked live on 2026-10-31.
- ITreview product profileJapanese IT product review site. Checked live on 2026-10-31.
