AI agent permissions and safety
The agent only proposes actions. Every file edit and command runs through a permission check on your machine before anything happens, and nothing can turn that check off.
What always happens without asking
Section titled “What always happens without asking”Read-only tools run freely inside the workspace: reading files, listing
directories, searching, and read-only git commands such as status, diff,
and log. The workspace is the directory where you started the agent plus
any directory added with --add-dir or /add-dir. Paths outside it, ..
escapes, and links that lead outside it are refused.
Permission modes
Section titled “Permission modes”Press Shift+Tab to cycle the mode. The current mode is shown in the status
line.
| Mode | File edits | Commands |
|---|---|---|
ask (default) | Asks every time | Asks every time |
accept-edits | Run without asking inside the workspace | Still ask |
plan | Refused | Refused |
In plan mode the agent researches and describes changes instead of making
them. /plan switches to plan mode for a planning request.
Set the starting mode with --permission-mode, with /permissions mode MODE,
or with defaultMode in a settings file. There is no mode that skips every
permission check.
Answering a permission prompt
Section titled “Answering a permission prompt”A prompt shows exactly what will happen: the diff for an edit, the full command line and working directory for a command, or the server and arguments for an MCP tool. You can choose:
- Yes to run it once.
- Yes, and don’t ask again for that command prefix or file pattern in this
project. The rule is saved in your own settings for this project, under
$CONFIG/ai/projects/, never inside the repository. - No, and tell the AI why, so the agent can adjust.
Some calls are always asked, and no rule can allow them: commands that
reference secret files or credential stores, changes to .champrep/ or
.git/ internals, and commands that are too complex to analyse safely.
Allow and deny rules
Section titled “Allow and deny rules”Rules have the form Tool or Tool(pattern):
{ "permissions": { "allow": ["local_bash(npm test*)", "local_bash(go test ./...)", "local_edit_file(src/**)"], "deny": ["local_bash(git push*)", "local_bash(rm -rf*)", "local_read_file(secrets/**)"], "defaultMode": "ask" }}- Command rules such as
local_bash(npm test*)match the command line. Commands joined with;,&&,||,|, or substitutions are split, and every part must be allowed. - Path rules such as
local_edit_file(src/**)match workspace-relative paths.*stays within one folder;**crosses folders. - Tool names can use
*, for examplelocal_mcp__github__*for every tool of one local MCP server. - A
local_read_file(...)deny rule, or adeny_readlist, also hides those files from every read and search tool.
Manage rules without editing files:
/permissions/permissions allow local_bash(npm run lint*)/permissions deny local_bash(git push*)/permissions remove local_bash(npm run lint*)/permissions mode accept-edits/permissions allow, deny, and remove edit your saved answers for this
project (under $CONFIG/ai/projects/). Edit the other files directly.
Settings files and precedence
Section titled “Settings files and precedence”| File | Scope |
|---|---|
--allowed-tools flag | This run only |
$CONFIG/ai/projects/<id>.json | Your saved answers for this project (“don’t ask again”, /permissions) |
.champrep/settings.local.json | You, in this project (added to .gitignore automatically) |
.champrep/settings.json | Everyone in this project (commit it to share) |
$CONFIG/ai/settings.json | You, in every project |
Earlier entries take precedence. Deny rules from any file always win. Your
saved answers apply right away because they live outside the repository. Allow
rules and defaultMode in the two .champrep/ files take effect only after you
trust the project’s .champrep/ configuration (see
Repository trust); deny rules in them always apply. Put
allow rules you want everywhere in your user settings. Your plan’s limits
apply on top of every file, and nothing local can raise them.
Run champrep ai paths to see where $CONFIG is on your machine.
Secret protection
Section titled “Secret protection”These are enforced by the CLI itself, not by the model:
- Blocked files. The agent never reads, lists the contents of, or sends
.envfiles (except.env.example), private keys and certificates such as*.pem,*.key,*.p12, andid_rsa*,.npmrc,.pypirc,.netrc, your~/.aws,~/.ssh, and~/.gnupgfolders, the operating-system keychain, and the CLI’s own configuration. The model is told the file is blocked; it never sees the content. - Redaction. Tool output is scanned before it leaves your machine.
High-confidence secrets such as cloud access keys, source-control tokens,
payment-provider keys, AI provider keys, private-key blocks, and bearer
tokens are replaced with
[REDACTED:<kind>]. - Pasted keys. If a prompt contains something that looks like a secret,
it is not sent. Register model keys with
/model registerand MCP credentials with/mcpinstead. - No credential inheritance. Commands the agent runs, hooks, and local MCP
servers never receive your CHAMPREP credentials or
CHAMPREP_*variables.
Add your own blocked paths with deny_read or local_read_file(...) deny
rules. The built-in list can be extended but never relaxed.
Repository trust
Section titled “Repository trust”A repository can ship agent configuration in .champrep/: custom commands,
skills, agents, hooks, MCP servers, and project settings. Opening an
unfamiliar repository must never run any of it, so this content stays
inactive until you approve it.
- When a project has such content, the agent asks once whether to trust it and shows what it contains.
- If the content changes later, you are asked again.
/trustshows the current state;/trust approveand/trust revokechange it.
Approvals are stored in $CONFIG/ai/trusted-projects.json.
Checkpoints, diff, and undo
Section titled “Checkpoints, diff, and undo”Before every edit, the agent saves the file’s previous state on your machine.
| Command | Effect |
|---|---|
/diff | Show every file change made in this session. |
/undo | Revert the last set of changes. |
/rewind | Pick an earlier message and restore files to their state before it. Esc twice also opens it. |
/rewind restores files only; the conversation itself is unchanged.
Checkpoints are deleted when the session ends unless you start with
--keep-checkpoints. Changes made by shell commands, for example a code
generator run through local_bash, are not checkpointed; use git for those.
Actions in CHAMPREP services
Section titled “Actions in CHAMPREP services”Actions that change data in your CHAMPREP services, such as sending an email, use the same approval flow as the web app. The agent shows an approval card, and you choose Approve, Reject, or Decide later. These actions are never approved automatically, whatever the local permission mode. In headless runs they stay pending for you to approve in the CHAMPREP web app.
/services shows which CHAMPREP services the AI may use. Change that list in
your CHAMPREP AI settings on the web.