Skip to content
Documentation

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.

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.

Press Shift+Tab to cycle the mode. The current mode is shown in the status line.

ModeFile editsCommands
ask (default)Asks every timeAsks every time
accept-editsRun without asking inside the workspaceStill ask
planRefusedRefused

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.

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.

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 example local_mcp__github__* for every tool of one local MCP server.
  • A local_read_file(...) deny rule, or a deny_read list, 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.

FileScope
--allowed-tools flagThis run only
$CONFIG/ai/projects/<id>.jsonYour saved answers for this project (“don’t ask again”, /permissions)
.champrep/settings.local.jsonYou, in this project (added to .gitignore automatically)
.champrep/settings.jsonEveryone in this project (commit it to share)
$CONFIG/ai/settings.jsonYou, 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.

These are enforced by the CLI itself, not by the model:

  • Blocked files. The agent never reads, lists the contents of, or sends .env files (except .env.example), private keys and certificates such as *.pem, *.key, *.p12, and id_rsa*, .npmrc, .pypirc, .netrc, your ~/.aws, ~/.ssh, and ~/.gnupg folders, 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 register and MCP credentials with /mcp instead.
  • 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.

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.
  • /trust shows the current state; /trust approve and /trust revoke change it.

Approvals are stored in $CONFIG/ai/trusted-projects.json.

Before every edit, the agent saves the file’s previous state on your machine.

CommandEffect
/diffShow every file change made in this session.
/undoRevert the last set of changes.
/rewindPick 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 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.