{"slug": "how-to-catch-out-of-scope-coding-agent-tasks-before-execution", "title": "How to catch out-of-scope coding-agent tasks before execution", "summary": "A developer maintains Agent Role Contracts (ARC), an MIT-licensed Node.js library and CLI that performs deterministic preflight checks on coding-agent task declarations before any write executes. In a reproduced demo on Node.js 24.11.1 with the pinned v1.0.0 source, a task targeting secrets/production.txt against a declared src/** write scope fails with TASK_WRITE_SCOPE_OUTSIDE_AUTHORITY and exit code 1, while an in-scope task passes with exit 0; the tool invokes no LLM and checks declarations only, leaving runtime permissions and approval gates to the surrounding workflow.", "body_md": "Coding agents work across files, roles, and review stages.\n\nHere's a small failure case worth checking *before* handing a task to an agent:\n\n`src/**`.` secrets/production.txt`.\nThe task conflicts with the declared write scope. The useful response is a deterministic preflight failure, before an agent or tool attempts the write.\n\nI maintain [Agent Role Contracts (ARC)](https://github.com/suirindo/agent-role-contracts), 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.\n\nRequirements: Git and Node.js **22.5 or newer**.\n\n```\ngit clone --depth 1 --branch v1.0.0 https://github.com/suirindo/agent-role-contracts.git\ncd agent-role-contracts\nnpm run demo --silent\n```\n\nThe demo reads the packaged example declarations and exercises the actual checker. Its relevant output is:\n\n```\n1. Normal task\n   Scope: src/example.mjs; allowed: src/**\n   PASS: declarations are consistent.\n   Implementer: implementer (write_scoped)\n   Reviewer: reviewer (read_only; separate declared role)\n\n2. Request an out-of-scope change\n   Scope: secrets/production.txt; allowed: src/**\n   FAIL (expected): TASK_WRITE_SCOPE_OUTSIDE_AUTHORITY\n\n3. Repair the task scope\n   Scope: secrets/production.txt -> src/example.mjs\n   PASS: declarations are consistent again.\n\nDemo complete: PASS -> FAIL (expected) -> PASS.\nChecks declarations only; execution is NOT authorized.\n```\n\nThe 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.\n\nRun the invalid task directly:\n\n```\nnode bin/agent-role-contracts.mjs explain \\\n  --bundle examples/starter-bundle.json \\\n  --task examples/starter-task-outside-scope.json \\\n  --format text\n```\n\nThis is an expected failure. The CLI reports:\n\n```\nFAIL: explain (declarations only; execution NOT authorized)\nAccountable: implementer\nImplementers: implementer\nReviewers: reviewer\nHuman approval required: true\nTASK_WRITE_SCOPE_OUTSIDE_AUTHORITY task/inputs/scope: Task scope is outside declared write scopes for role implementer: secrets/production.txt\n```\n\n**Exit status: `1`.** The shortened output above omits the role-capability detail lines that the CLI also prints.\n\nTry the allowed task:\n\n```\nnode bin/agent-role-contracts.mjs explain \\\n  --bundle examples/starter-bundle.json \\\n  --task examples/starter-task.json \\\n  --format text\n```\n\nThe 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.\n\nThe shipped declaration checks cover several common workflow inconsistencies:\n\n| Supplied declarations | Example of a detectable mismatch | \n|---|---|\n| Implementer write authority + task scope | Requested path exceeds `src/**` | \n| Implementer + reviewer roles | Same declared role assigned to both | \n| Reviewed task/action + binding | Task or action changed after its declared review binding | \n| Handoff and lifecycle declarations | Declared task/subject relationships become stale | \n\nARC 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.\n\nA 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.\n\nFor 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.\n\nThe recently merged [external evaluation kit](https://github.com/suirindo/agent-role-contracts/tree/main/experiments/external-evaluation) 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.\n\nIf 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.\n\nThe first external workflow feedback report, [Burs-IA WORKNET](https://github.com/suirindo/agent-role-contracts/issues/45), 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.\n\nHere are the relevant links:\n\n**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.\n\n*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.*", "url": "https://wpnews.pro/news/how-to-catch-out-of-scope-coding-agent-tasks-before-execution", "canonical_source": "https://dev.to/suirindo/how-to-catch-out-of-scope-coding-agent-tasks-before-execution-d3m", "published_at": "2026-10-19 12:40:35+00:00", "updated_at": "2026-10-19 12:44:35.156510+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-safety"], "entities": ["Agent Role Contracts (ARC)", "Node.js", "GitHub", "Codex", "Claude Code"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/how-to-catch-out-of-scope-coding-agent-tasks-before-execution", "markdown": "https://wpnews.pro/news/how-to-catch-out-of-scope-coding-agent-tasks-before-execution.md", "text": "https://wpnews.pro/news/how-to-catch-out-of-scope-coding-agent-tasks-before-execution.txt", "jsonld": "https://wpnews.pro/news/how-to-catch-out-of-scope-coding-agent-tasks-before-execution.jsonld"}}