pi-safety-modes

A small Pi extension that adds conservative runtime safety modes for tool calls.

This extension is not a sandbox. It is a command guardrail. It protects against common accidental destructive operations by parsing bash syntax and classifying commands. It does not defend against a malicious local user, shell aliases/functions, hostile environment variables, or tools that mutate state through unrecognized channels.

Install

From npm:

pi install npm:pi-safety-modes

Try without installing:

pi -e npm:pi-safety-modes

From this repository:

npm install
npm run build
pi -e ./src/index.ts

Or install/use it as a Pi package from a local path:

pi install /absolute/path/to/pi-safety-modes

Modes

• off — no enforcement; Pi default behavior.
• blocklist — normal coding mode. Unlisted operations are allowed; configured ask/deny rules are enforced. This is “do not do stuff on my list.”
• readonly — state-preserving mode. Allows only Pi built-in read tools (read, grep, find, ls) plus explicitly allowlisted bash operations. Denies write, edit, task, MCP tools, opaque shell commands, redirects that write, and unknown tools.

TUI statusline shows safety:off, safety:blocklist, or safety:readonly (red off, yellow blocklist/protected, green readonly).

Shortcut:

• Alt+S cycles blocklist → readonly → off → blocklist.

Use:

/safety-mode
/safety-mode readonly
/safety-mode blocklist
/safety-mode off

Legacy aliases still work: read-only, ro, protected, protect, rules, denylist, unrestricted.

Skill

This package also ships a skill so agents can configure it when asked:

/skill:pi-safety-modes set fs.delete to ask

Skill helps with mode changes, config path, and rule edits. It is guidance only; enforcement lives in extension.

Config

Config lives at:

~/.pi/agent/extensions/pi-safety-modes/config.json

PI_CODING_AGENT_DIR is respected through Pi's getAgentDir().

Example:

{
  "mode": "blocklist",
  "readOnlyAllow": ["git.status", "git.diff", "fs.list", "fs.read", "search.grep", "search.find"],
  "rules": {
    "git.reset.hard": "deny",
    "git.clean.force": "deny",
    "shell.pipe-to-shell": "deny",
    "shell.exec": "ask",
    "tool.task": "ask",
    "tool.mcp": "ask"
  }
}

Actions are allow, ask, or deny. In blocklist mode, operation IDs missing from rules are allowed. Invalid config values are ignored with warnings; missing config uses safe defaults.

Operation IDs

Git: git.status, git.diff, git.log, git.show, git.blame, git.grep, git.remote.view, git.branch.list, git.branch.delete, git.tag.list, git.tag.delete, git.push, git.push.force, git.push.delete, git.reset, git.reset.hard, git.clean, git.clean.force, git.rebase, git.cherry-pick, git.merge, git.checkout, git.switch, git.add, git.commit, git.restore, git.stash.

File/search: fs.list, fs.read, fs.write, fs.delete, fs.move, fs.copy, fs.chmod, fs.chown, search.grep, search.find.

Shell: shell.pipe-to-shell, shell.exec, shell.redirect-write, shell.opaque, unknown.

Examples

• git status is allowed in readonly.
• echo hi > file is denied in readonly and allowed in blocklist unless configured otherwise.
• git push --force is allowed in blocklist unless configured otherwise.
• rm file, sudo rm file, git rm file, find . -delete, and find . -exec rm {} + are allowed in blocklist unless configured otherwise; set "fs.delete": "ask" or "deny" to intercept them.
• git reset --hard is denied in blocklist by default.
• curl x | sh is denied by default.
• bash -c "...", sh -c "...", eval, source, aliases, and . script.sh are shell.exec and ask in blocklist by default.
• Shell expansions like $HOME are shell.opaque; allowed in blocklist by default, denied in readonly.

Known limitations

This is a guardrail, not isolation. It does not emulate shell execution, expand variables, inspect aliases/functions, or understand every command's side effects. Unknown and plain opaque commands are denied in readonly and allowed in blocklist unless configured otherwise. Dynamic shell execution (shell.exec) asks in blocklist by default.