Lesson 5: Define What Agents Can Do Without Approval
What you'll learn: write a reusable permission file that specifies what an agent may do, what requires your approval, and what evidence belongs in its completion report. What you need: one ready spec from Lesson 1, with acceptance checks and excluded work; the repository layout from Lesson 4 or a single repository; and your coding agent. Time: about an hour to write and test the instructions. Cost: no additional services or subscriptions.
The idea#
An agent needs explicit rules for actions your task does not mention. Creating a file, running an existing test, adding a dependency, and changing a public route have different consequences. Write down which actions you authorize in advance and which require a new decision.
I use a file with three sections: permitted actions, actions requiring approval, and completion criteria. A final instruction tells the agent to stop and ask when those sections do not resolve a decision. A charter is written standing authority for a role. It depends on the agent following it; enforceable tool restrictions are separate.
Why start here#
The preceding lessons define the requested behavior, its rationale, checks, and repository scope. They do not specify every action an agent may take during implementation. A ready spec can authorize a feature while leaving a new dependency undecided.
The idea of defining authority once per role came from Clief Notes. The sections below are my version. Existing tool permission settings still apply; writing this file is not a reason to disable them.
The template#
Save CHARTER.md beside the standing instruction file in the directory where you launch sessions. Additional roles can use CHARTER-<role>.md. In this template, home means the repository assigned to the task:
# Builder: standing authority
Scope: one change at a time, from one ready spec, inside one home.
## You may, without asking
- Pick names, layout, and patterns, and use any library already in the project.
- Create or move files wherever the spec's scope reaches, and delete the ones it makes obsolete.
- Cover what you change with tests, and update the docs that describe it.
- Run any command that only reads, builds, or tests, inside your own checkout.
- Draft a decision record when you choose between two reasonable options, with its Decision line marked proposed for me to confirm.
## You must ask before
- Adding a dependency the project does not already have, or any new external service or cloud resource.
- Changing an interface the spec names as existing: a route, a schema, a public function.
- Deleting data, running a migration, rotating a secret, or any step you could not undo.
- Rewriting history: force-push, branch deletion, amending a commit you did not make.
- Touching a second home: another repository, another stack.
## Done means
- Every acceptance line in the spec passes and its verify command exited 0, both run in this session, and the closing message says so.
- Nothing listed under the spec's Out of scope changed.
- The work is on a fresh branch, pushed if the home has a remote, one commit per repository.
- Your closing message answers four questions in this order: what shipped; which choices you made between reasonable options, and why; what the spec could be read to demand that you left out, and why; which follow-ups deserve a spec of their own.
## When you are not sure
Come back with the question. Write it in one line, name the two answers you can see, say which you would pick and why, and stop. Never guess, and never narrow or widen the task to avoid asking.
Add this line to the session's standing file:
Read CHARTER.md before starting any task; it is your standing authority. Anything under "You must ask before" stops the task until I answer.
Each part, and the mistake it prevents#
The scope line restricts the role to one ready spec and one repository. Individual specs still determine which files and behaviors belong to each task.
The permitted-actions section records routine decisions you are willing to delegate. It lets the agent choose names, use installed libraries, and run relevant checks without requesting the same approval each time. Review the wording against your environment before adopting it. A command described as a test can still contact a service or change data.
The approval section names recognizable actions. "Rotating a secret" can be compared with a proposed command; "be careful" does not specify when to stop. Write these requirements from your project's actual dependencies, interfaces, and data operations.
The completion section requires evidence and a report of choices, omissions, and follow-up work. Check the evidence against each acceptance criterion. A zero exit status supports only what the command tested. The template's "what shipped" label means the reported implementation result; a branch and passing tests do not establish deployment.
For unresolved choices, the template requests a short question, two options, and a recommendation. That helps you make the decision without reconstructing the investigation. The agent should identify uncertainty before taking the action that requires approval.
A worked example#
The recorded exercise used Lesson 4's four repositories and specs/api/002-health.md. It required a health() function returning {"ok": true} and a test. Server wiring, web/, and infra/ were excluded. A fresh session received the standing file and a request to implement the spec on a branch:
`health()` now returns `{"ok": True}`, and the work is committed on branch
`002-health` [the session's branch name, shortened] in `api/` (commit
`3eb7c00`, off `main`). `python -m pytest
api/tests -q` ran from the project root in this session and exited 0 (1
passed).
I changed two files, both inside the api home: `api/src/health.py` and
`api/tests/test_health.py`. The test asserts the return value. Nothing under
the spec's Out of scope changed. The commit is local only, because `api` has
no remote to push to. I staged the two files by path, and the new
`__pycache__` folders are left untracked.
**Choices between reasonable options**
- **Test imports:** the test adds `api/src` to `sys.path` itself instead of
using a `conftest.py` or packaging config. That keeps the change to two
files and adds no dependency. The spec's verify command runs from the
project root, which is why an import path is needed at all.
[one bullet about a commit hook on my machine omitted]
**Left out:** I added no HTTP route, framework, or packaging, since the spec
rules those out.
**Follow-ups for their own spec:** wiring `health()` into a route, and adding
a `.gitignore` for `__pycache__` and `.pytest_cache` in `api/`.
The return-value test checked a local function. The report also named the two changed files, the local-only commit, and the excluded server work. It did not show a working HTTP endpoint or deployment, neither of which the spec requested.
A second run requested an uptime ping to a hosted status page every minute. That added an external service and scheduling work. The session stopped before editing:
I haven't changed anything yet. The uptime ping needs your answer first, and
CHARTER.md says that stops the task.
**Question:** The hosted status page is a new external service, and a
per-minute ping is a scheduled job that would live in `infra/` or `api/`. Do
you want a spec for the ping first, or should I build it as a scheduled job
inside `api/`, with the status-page URL and token supplied by you?
- **A (spec first):** You write or approve a spec that names the status-page
provider and the home. `specs/api/002-health.md` covers only the bare
`health()` function, and it lists infra/ and HTTP wiring as out of scope.
I'd do the health function now on a branch and leave the ping for its own
spec. I'd pick this, because the ping is a second change that adds an
external service, and the layout skill says to write the spec first.
- **B (ping inside `api/`):** You tell me which provider to use and approve
the new service, and I add the ping to `api/` as a scheduled job. It would
need a spec amendment, since 002 currently excludes anything beyond the bare
function.
I can start `health()` and its test on a fresh `api/` branch right away if you
say go.
All four repositories remained clean after this request. The two runs show that the agent followed the written instructions for these tasks. They do not establish that later sessions will always comply.
How it scales#
On June 9, I wrote five files in one afternoon for the builder, content, monitor, task runner, and interface-review roles. Each used the same sections, with different permitted actions. A monitor can be limited to reading and notifying, with every write requiring approval.
You decide the approval requirements and completion criteria. An agent can propose permitted actions based on recent tasks, but you approve the list. Record changes to standing authority with their reasons in a decision record, so later sessions can identify the approved version.
From the field#
An unattended agent on a small always-on Linux box at home read one of these files. Its approval requirements were also represented in tool-level deny rules. The agent attempted a command requiring approval. A rule denied it before execution, and the agent stopped instead of trying another route.
The written instruction did not prevent the attempt. The permission rule prevented that command from running. This incident supports a specific distinction: instructions define the expected behavior, while a configured control can reject an action within its coverage. That one denial does not establish coverage for every prohibited action.
Exercise#
- Save
CHARTER.mdbeside the standing file and add the instruction to read it. - Replace the approval list with concrete actions relevant to your project. Include the operations you need to review before execution.
- Ask the agent to propose permitted actions from recent tasks. Remove any action you still want to approve individually.
- Give a fresh session one ready spec. Compare its completion report with the criteria, inspect the evidence, and check the diff for excluded work.
- Request an action requiring approval, such as the uptime ping. Confirm the session asks before editing or executing that action. Perform this check in a disposable project with appropriate tool restrictions.
You're done when#
The permitted task should finish within its scope and report the evidence, choices, omissions, and follow-ups. The approval case should stop before the restricted action and provide the question and options. Inspect the files and command record instead of relying only on the final message.
If the agent asks about an already authorized action, inspect the wording and the context it received. If it performs an action requiring approval, the instruction check failed. Review both instruction delivery and tool-level enforcement before allowing that action unattended.
Common mistakes#
Vague approval rules leave the agent to decide what counts as risky. Missing completion criteria leave you to reconstruct the task afterward. Written instructions alone cannot establish that a prohibited command will be denied; test the relevant permission control separately.
Further reading#
Saltzer and Schroeder's The Protection of Information in Computer Systems describes least privilege. The Claude Code permissions reference documents tool permission rules. The AGENTS.md convention describes a format for standing agent instructions.
Next lesson#
Lesson 6: Build a Task Queue Agents Can Follow defines how agents select work from a backlog (the project's task queue) and when they must stop.
Questions this post answers
- Why define agent permissions before assigning work?
- Written permissions distinguish routine actions you have already authorized from actions that still require approval. The agent can consult the same rules in each session. You still need to check compliance and configure tool restrictions for actions that must be prevented.
- Which actions should require approval?
- Name actions with consequences you need to review: adding dependencies or external services, changing interfaces outside the approved spec, deleting data, rewriting shared history, or editing another repository. Choose rules for your project rather than relying on a general instruction to be careful.
- Does a written permission file prevent prohibited commands?
- No. It instructs the agent, which may fail to comply. Tool permission rules can deny matching commands before execution. The recorded incident shows one such denial; it does not prove every command or bypass is covered.
- Who approves the permissions?
- You approve the permitted actions, approval requirements, and completion criteria. The agent can draft them from recent tasks. Review the proposal before using it as standing authority.
Previous lesson: Lesson 4: Define Repository Boundaries and Isolate Agent Work