Step-by-step guide
Set an agent’s authority
Start from the responsibility and grant only the capabilities required to fulfill it.
What this changes
Permissions make a role concrete. A reviewer, investigator and implementation agent can collaborate precisely because they do not all carry the same authority.
-
01
Smaller blast radius
A focused role cannot accidentally turn every mistake into a system-wide effect.
-
02
Clearer delegation
A lead knows which specialist can safely own each kind of work.
-
03
Easier review
The role’s authority can be discussed separately from the quality of its instructions.
Minimum setup
Start with one working configuration.
Use grants to decide which tools one agent receives. Use the guard to decide what shell commands may run across the workspace. Both layers matter, and neither replaces the other.
{
"guard": {
"type": "shell",
"mode": "on",
"allowed_commands": ["git status", "git diff", "ls", "cat", "bun test"],
"denied_commands": ["git push", "rm -rf /*"]
}
}The block above is the settings file on its own. Grants live in a second file, one Markdown profile per agent at ~/.clarvis/agents/<name>.md, and the working patterns below show both halves together: the guard cannot hand a tool to an agent that was never granted it, and a grant cannot get a command past the guard. Keep personal defaults in ~/.clarvis/settings.json and repository policy in .clarvis/settings.json. A workspace guard block replaces the global guard block, so repeat the entries that must remain effective.
Working patterns
Adapt it to work you actually do.
Open a pattern to see the complete files and the reason behind each choice.
Pattern 01 Let this project's own commands run without asking Configuration +
Every `bun test` and `bun run typecheck` stops the run with a confirmation prompt, and you approve it every time. Approving by reflex is how a prompt stops protecting you, so persist the decision instead.
File: <workspace>/.clarvis/settings.json
{
"guard": {
"type": "shell",
"mode": "on",
"allowed_commands": [
"git status",
"git diff",
"git log",
"ls",
"cat",
"head",
"tail",
"grep",
"rg",
"bun test",
"bun run typecheck",
"bun run lint",
"bun run build",
"docker compose logs*"
],
"denied_commands": ["git push", "npm publish", "bun publish"]
}
}
Why the list repeats entries you already have globally: the workspace `guard` block
replaces the global one whole. Copy across whatever you still want.
`docker compose logs*` contains a `*`, so it is an anchored glob over the whole
normalized command: it matches `docker compose logs` and `docker compose logs -f api`.
`bun test` has no `*`, so it matches `bun test` exactly or anything starting
`bun test `, which includes `bun test --watch`.Pattern 02 Take exec away from one agent without touching the rest Configuration +
Your reviewer agent has drifted into running builds and editing files. You want it back to reading only, and you want the change to be visible in the file rather than in a setting nobody can find.
Before, in ~/.clarvis/agents/reviewer.md:
---
description: Reviews changes and reports findings.
grants:
- read_workspace
- edit_workspace
- run_commands
- use_skills
---
After:
---
description: Reviews changes and reports findings.
grants:
- read_workspace
- use_skills
---
Deleting `run_commands` removes `shell`, `monitor_start`, `monitor_poll`,
`monitor_stop` and `monitor_list` from this agent. Deleting `edit_workspace`
removes `write_file`, `edit_file`, `multi_edit`, `apply_patch`, `replace`,
`move`, `copy`, `mkdir` and `remove`. The tools are not advertised at all, so
the model cannot call them and there is nothing for the guard to rule on.
Delete `read_workspace` as well and the agent is handed no coding tools of any
kind. Keep the `grants` key out entirely, or write an empty list, and the result
is the same. If you prefer clicking: `/settings agents`, pick the agent, open the
`grants` field, toggle the entries, save.Verify the behavior
Check the boundary, not just the happy path.
Use a small disposable task first. Confirm what works and what is deliberately unavailable before relying on the configuration in a real workflow.
- 01
A listed safe command runs according to the configured guard mode.
- 02
A denied command is refused before execution and cannot be approved ad hoc.
- 03
An agent without run_commands never receives the shell tool, even if the guard would allow the command.