pi-readonly-bash

Provides a bash_readonly tool that enforces a read-only policy — allows inspection commands (ls, cat, grep, find) but blocks anything that mutates state (rm, mv, redirects, pipes to files).

I built this for use with pi-modes, where Ask and Brainstorm modes should let the agent inspect code without risking accidental changes.

Install

pi install npm:@pedro_klein/pi-readonly-bash

What it provides

• Tools: bash_readonly — executes shell commands after policy validation

How it works

The extension registers a bash_readonly tool. When the LLM calls it:

1. The command string is passed through the policy classifier
2. If the command is safe, it runs via pi's built-in bash executor (identical behavior to the bash tool)
3. If blocked, it returns an error explaining why — without executing anything

Allowed (read-only inspection):

• File inspection: ls, cat, head, tail, wc, find, grep, rg, fd
• Git read: git log, git status, git diff, git show, git branch -a
• Build/test: npm run, npm test, go test, go build, cargo test, cargo build
• Network read: curl (GET only — no -d, -X, -o)
• Pipes between allowed commands

Blocked (mutating or dangerous):

• Filesystem: rm, mv, cp, mkdir, touch, chmod, ln
• Content mutation: sed, awk, perl, patch
• Redirects: >, >>, tee
• Execution: eval, backticks, $() command substitution
• Package installs: npm install, pip install, brew install
• Shell wrappers: bash -c, sh -c
• Privilege: sudo, su

The policy is a denylist — known-dangerous patterns are blocked; everything else is allowed. Structural rules (no redirects, no heredocs, no command substitution) act as the safety net for novel mutations.

Configuration

No configuration required. The policy rules are built-in.

To customize allowed/blocked patterns, modify src/bash-policy-rules.ts and rebuild.

Development

pnpm test           # run tests
pnpm build          # build for publish
pnpm typecheck      # type-check without emitting

License

MIT