Keeping AI coding agents within scope

Keeping AI coding agents within scope takes four separate steps: write the scope down as paths, approve it as a distinct decision, check writes while the agent runs and compare the final diff with what you approved. Most people only do the first step, usually as one line in a prompt ('only touch the invoice module'), and then find that the agent also reformatted a config file, renamed a helper used elsewhere and updated a lockfile. A prompt instruction is a request. It shapes behavior, but nothing holds the agent to it. The workflow below treats scope as data you can compare against, and it works with Claude Code, Codex CLI or any agent that edits a git working tree. It also spells out what a pattern-based check can and cannot catch, because a tripwire you overestimate is worse than one you understand. If an agent has already strayed, start with what to do when an agent changes files you did not ask for instead.

Step 1: Write the scope as paths, not intentions

Scope should be something a script can check. 'Keep changes small' cannot be checked. A list of paths can. For a task like 'Add a VAT line to the invoice PDF', a usable scope looks like this.

Editable: src/invoices/pdf.py, src/invoices/vat.py, tests/invoices/test_pdf.py. New files allowed: tests/invoices/fixtures/vat_invoice.json. Read only: src/billing/ (the agent may read it to understand totals, not change it). Out of scope: migrations, lockfiles, CI configuration.

The read-only list matters as much as the editable one. Agents often fix what they read, and a shared billing helper is exactly the file you do not want changed as a side effect. Put the scope in the task record, not only in the prompt, so it outlives the session and you can compare against it afterwards. If you cannot name the files yet, the task is not ready for edits: run a review-only session that proposes the file list first, then write the scope from its answer. For more on task wording, see writing tasks an agent can finish.

Step 2: Approve the scope separately, with an expiry

Whoever writes a task proposes a scope. Approving it is a different act, and it should be visible as one. If editing a task's file list is enough to let an agent work on those files, then anyone with edit rights (including an agent updating its own task) can widen its authority by accident.

A simple way to make approval concrete is to approve a fingerprint: a hash of the sorted path list together with the task's revision. If the list changes after approval, the fingerprint no longer matches and the approval has to be given again. Add an expiry, such as the end of today's working session, so an approval from last week does not quietly authorize a rerun next month. Keep revocation separate as well: ending a session is not the same as withdrawing permission, and you should be able to do either one without the other.

Write down who approved, when, the fingerprint and the expiry. That record is what you check later when the diff contains a surprise.

Step 3: Enforce what you can during the run

Use the strongest mode your tool offers for the job. For planning, there is no need to allow edits at all: Claude Code has a plan mode, and Codex CLI has sandbox and approval modes including read-only. For edit runs, a hook or guard can compare the target path of each file-editing tool call with the approved list and refuse anything outside it.

Be clear about what that is. A pattern check compares a path in a supported tool call with a list of allowed paths. It sees what the tool reports as a file edit. It does not see a shell command that writes a file: sed -i, an output redirect, a Python one-liner or a code generator can change any file the user account can reach. Some guards inspect shell commands too, but parsing arbitrary shell is heuristic and easy to get wrong in both directions. A pattern check is a tripwire, not containment and not an operating-system sandbox. If you need real isolation, run the agent in a separate checkout, container or user account, and still keep the path check, because it catches honest mistakes early.

Step 4: Compare the diff with the approved scope

After the run, list what actually changed: git status --porcelain for modified and untracked files, and git diff --name-only against the commit you started from. Compare that list with the approved paths. Untracked files count; agents often leave scratch scripts and generated fixtures behind.

For every path outside scope, make an explicit decision. Revert it if it is noise. If the change is genuinely needed, do not quietly widen the original task after the fact. Record it as separate work with its own scope and approval, as described in handling work an agent discovers mid-task. Retroactive widening is how a two-file task becomes a twelve-file change that nobody reviewed as such.

Keep the result with the task: approved paths, actual paths and what you did about the difference. Over a few weeks this record shows you which kinds of task drift and which agents need tighter scopes, and it gives a reviewer the context for a cross-file review.

QUESTIONS

Can I stop an AI coding agent from editing files outside one folder?

Partly. Hooks and permission settings can refuse file-edit tool calls aimed outside an approved list, and read-only modes stop edits entirely. A shell command can still write anywhere your user account can, so path checks are tripwires rather than containment. For hard isolation, run the agent in a separate checkout, container or account, and compare the final diff with the approved list either way.

Is telling the agent which files to change in the prompt enough?

It helps, but it is a request, not a limit. Agents follow scope instructions most of the time and drift when a nearby fix looks obviously useful. Treat the prompt as the first of several layers: a written path list in the task record, a separate approval, a check on edits during the run and a diff comparison afterwards.

Why should an agent's scope approval expire?

Because the situation it approved changes. The code moves, the task gets edited and the person who approved it forgets the details. An expiry, such as the end of a working session, forces a fresh look before the next run. Pair it with a fingerprint of the path list so any edit to the scope also requires a new approval.

RELATED GUIDES

• How to create a project card in BRAIN FLUID Desk
• How to preview work with the BRAIN FLUID harness CLI

RELATED HARNESS PAGES

• Why does my AI coding agent change files I didn't ask about? Unrequested edits come from missing scope, vague tasks, formatters and refactor drift. How to tell them apart, revert them and catch them next time.
• Using an AI agent as a reviewer, not an implementer Using an AI agent as a reviewer, not an implementer: read-only review sessions, what to ask, and why findings are input rather than a verdict.
• Managing tasks an AI agent discovers mid-work Managing tasks an AI agent discovers mid-work: record each as a new linked task, mark it required or optional and never widen the current task silently.
• evidence gates for AI work Evidence gates for AI work: separate proposed from approved execution, run checks, and record outcomes so acceptance rests on evidence.