Before Your AI Agent Writes a File, Check Its Task Scope

asagiman — Wed, 21 Oct 2026 08:38:07 +0000

Imagine an AI coding agent assigned to modify files inside src/**.

Its next task requests a change to secrets/production.txt.

The agent has received instructions, but the task conflicts with its declared scope.

Can we catch this contradiction before execution?

That's one of the problems we're working on at Netsujo.

Introducing Agent Role Contracts

Agent Role Contracts (ARC) is an MIT-licensed, open-source tool for deterministic pre-execution checks of AI-agent workflows.

ARC can detect contradictions involving:

Declared permissions and task scopes
Implementation and independent review roles
Stale handoffs and task bindings
Inconsistent action declarations

The checks run offline and produce reproducible diagnostics.

Try it in three minutes

With Git and Node.js 22.5 or newer:

git clone https://github.com/suirindo/agent-role-contracts.git
npm --prefix agent-role-contracts run demo --silent

The demo shows three outcomes:

PASS → FAIL → PASS

A task within its declared scope passes.
An out-of-scope task is rejected.
Repairing the task declaration restores a passing result.

ARC validates declared contracts. Runtime identity, actual permissions, enforcement, and execution approval remain separate responsibilities.

We're looking for real-world feedback

ARC v1.0.0 is available now.

We're especially interested in developers working with coding agents and multi-agent systems.

Where do responsibilities, permissions, or review boundaries become difficult to manage?

Which checks are already covered by your runtime or CI infrastructure?

We welcome both positive and negative evaluation results.

Try ARC: https://github.com/suirindo/agent-role-contracts

Evaluate a real workflow: https://github.com/suirindo/agent-role-contracts/issues/37

If you find the project useful and want to support its continued development:

GitHub Sponsors: https://github.com/sponsors/netsujo-inc

Developed by Netsujo in Kyoto, Japan.

This article was prepared with AI writing assistance and reviewed by the Netsujo team before publication.

How to catch out-of-scope coding-agent tasks before execution

asagiman — Mon, 19 Oct 2026 12:40:35 +0000

Coding agents work across files, roles, and review stages.
Here's a small failure case worth checking before handing a task to an agent:

An implementer is allowed to change files under src/**.
A separate read-only reviewer checks the proposed work.
The next task requests secrets/production.txt.

The task conflicts with the declared write scope. The useful response is a deterministic preflight failure, before an agent or tool attempts the write.

I maintain Agent Role Contracts (ARC), a small MIT-licensed Node.js library and CLI for checking those declarations. I reproduced the example below on macOS with Node.js 24.11.1 and the pinned v1.0.0 source on October 19, 2026.

Run the three-minute check

Requirements: Git and Node.js 22.5 or newer.

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

The demo reads the packaged example declarations and exercises the actual checker. Its relevant output is:

1. Normal task
   Scope: src/example.mjs; allowed: src/**
   PASS: declarations are consistent.
   Implementer: implementer (write_scoped)
   Reviewer: reviewer (read_only; separate declared role)

2. Request an out-of-scope change
   Scope: secrets/production.txt; allowed: src/**
   FAIL (expected): TASK_WRITE_SCOPE_OUTSIDE_AUTHORITY

3. Repair the task scope
   Scope: secrets/production.txt -> src/example.mjs
   PASS: declarations are consistent again.

Demo complete: PASS -> FAIL (expected) -> PASS.
Checks declarations only; execution is NOT authorized.

The example uses fictional paths. It opens no target task file, invokes no model, and performs no agent action. The demo returns exit 0 when it observes the expected PASS → FAIL → PASS sequence.

See the actual CLI rejection

Run the invalid task directly:

node bin/agent-role-contracts.mjs explain \
  --bundle examples/starter-bundle.json \
  --task examples/starter-task-outside-scope.json \
  --format text

This is an expected failure. The CLI reports:

FAIL: explain (declarations only; execution NOT authorized)
Accountable: implementer
Implementers: implementer
Reviewers: reviewer
Human approval required: true
TASK_WRITE_SCOPE_OUTSIDE_AUTHORITY task/inputs/scope: Task scope is outside declared write scopes for role implementer: secrets/production.txt

Exit status: 1. The shortened output above omits the role-capability detail lines that the CLI also prints.

Try the allowed task:

node bin/agent-role-contracts.mjs explain \
  --bundle examples/starter-bundle.json \
  --task examples/starter-task.json \
  --format text

The checker reports PASS: explain and exits 0. A CLI/input error exits 2. When integrating this preflight into CI or task dispatch, treat exit 1 or 2 as a stop condition and use your runtime's existing permissions and human-approval gates after a valid declaration check.

What ARC checks

The shipped declaration checks cover several common workflow inconsistencies:

Supplied declarations	Example of a detectable mismatch
Implementer write authority + task scope	Requested path exceeds `src/**`
Implementer + reviewer roles	Same declared role assigned to both
Reviewed task/action + binding	Task or action changed after its declared review binding
Handoff and lifecycle declarations	Declared task/subject relationships become stale

ARC works offline with JSON inputs. The example is model-agnostic: it can be evaluated alongside a Codex, Claude Code, or other coding-agent workflow, because the check itself invokes no LLM. Integration into an agent runtime remains the responsibility of that workflow's maintainer.

What a PASS establishes

A PASS establishes internal consistency of the supplied declarations under the checks executed. Actual file permissions, actor identity, reviewer independence at runtime, approval authenticity, side effects, and resulting code quality require checks from IAM, sandbox, CI, and runtime/evidence systems.

For instance, an independent reviewer role ID in JSON expresses the intended separation; the execution environment must authenticate the real reviewer. A write-scope declaration needs an actual filesystem/tool boundary to enforce it.

Test one of your workflows

The recently merged external evaluation kit adds a source-only helper pinned to the immutable v1.0.0 revision. It supports the expected scope contradiction, its repair, and a second distinct declaration check with the same bundle. The last step is useful for examining reusability; proof of a second real task still requires an actual second operation or independently linkable CI/commit evidence.

If you already use CI, a sandbox, a reviewer, or another preflight, I'd especially value a comparison on the same deliberate contradiction. A negative result — your current controls catch everything ARC catches — is useful feedback too.

The first external workflow feedback report, Burs-IA WORKNET, described a PASS → rejected scope mismatch → repaired PASS using ARC 0.5.0. That report is operator-provided; separate actual second-task reuse and independent reproduction remain open evaluation goals.

Here are the relevant links:

One concrete question: What mismatch between a coding agent's task, its declared authority, and its review handoff would you most want checked before dispatch? I can help map one small, non-sensitive workflow and compare the result against your existing controls.

Disclosure: I maintain ARC at Netsujo Inc. The example above is a synthetic preflight demonstration; external production adoption and second-task reuse are tracked separately.

DEV Community: asagiman