🛡️ Gatekeeper

A pi extension that adds a permission system. File-mutating tool calls require user approval before execution.

How It Works

Gatekeeper uses a default-deny model with AST-based analysis:

1. edit and write tool calls are always gated
2. bash commands are parsed into an AST using tree-sitter-bash, then classified:
   • Every command in the AST is checked against a safe command allowlist
   • Output redirections (>, >>) are detected structurally
   • Dynamic/unresolvable constructs (command substitution, variable expansion, ANSI-C strings in command position) are always gated
   • Benign command wrappers (env, nice, nohup, timeout, etc.) are unwrapped to check the inner command
   • Compound commands (&&, ||, ;, pipes, loops, conditionals) have every sub-command checked
   • Parse errors trigger gating (possible obfuscation)
   • Falls back to regex patterns if tree-sitter is unavailable

Design principle: if the analyzer can't prove a command is safe, it's gated. False positives (unnecessary prompts) are annoying but harmless. False negatives (missed mutations) are dangerous.

Allowed without asking

Commands on the allowlist pass through silently. This includes:

Category	Commands
File viewing	cat, head, tail, less, bat
Listing	ls, tree, exa, eza
Search	grep, rg, ag, find (without -delete/-exec), fd
File info	file, stat, wc, du, df, readlink
Text processing	awk, sed (without -i), sort (without -o), uniq, cut, tr, jq
Comparison	diff, cmp, comm
System info	whoami, uname, env, printenv, uptime
Shell utils	echo, printf, pwd, which, type, test, cd
Network (read)	ping, dig, curl (without -o/-O), wget --spider
Git (read)	status, log, diff, show, blame, branch (list), tag (list)
Pkg mgrs (read)	npm ls, npm outdated, npm audit, cargo check, pip list
Interpreters	Only --version / -v checks
Redirects	> /dev/null, 2>&1, < input (input redirects)

See allowlist.ts for the complete list.

Gated (requires approval)

Everything not on the allowlist, including:

• File mutation: rm, mv, cp, mkdir, touch, chmod, ln, rsync, tee, dd, ...
• Output redirects: > file.txt, >> file.txt
• Git mutations: push, commit, add, checkout, reset, rebase, merge, ...
• Package mutations: npm install, npm run, yarn add, ...
• Shell execution: bash -c, sh -c, eval, source, exec
• Interpreters with code: python3 -c, node -e, ruby -e, ...
• Privilege escalation: sudo, doas
• Obfuscation: $(cmd) in command position, $var in command position, ANSI-C strings, parse errors

Obfuscation resistance

The AST-based approach defeats common evasion techniques:

Technique	How it's caught
$(echo rm) file	Dynamic command name (command substitution)
$cmd file	Dynamic command name (variable expansion)
$'\x72\x6d' file	Dynamic command name (ANSI-C string)
/bin/rm file	Path stripped → rm → not in allowlist
\rm file	Backslash stripped → rm → not in allowlist
"rm" file / 'rm' file	Quoted name resolved → rm → not in allowlist
env rm file	Wrapper unwrapped → rm → not in allowlist
nice env nohup rm file	Stacked wrappers unwrapped → rm
echo x | base64 -d | sh	sh not in allowlist
echo x > file.txt	Output redirect detected structurally
echo safe; rm bad	Every sub-command checked
for f in *; do rm $f; done	Loop body checked
Malformed input	Parse errors → gated

Dialog

When a gated tool call is intercepted, a dialog appears showing what the tool wants to do (including full diffs for edits).

Key	Action
y	Accept this tool call
n	Decline this tool call
a	Switch to auto-accept mode
← →	Navigate options
Tab	Attach a message to Yes/No (the LLM sees your feedback)
Enter	Confirm highlighted option
Esc	Decline

Settings

Open with /gatekeeper:

Setting	Values	Description
Mode	ask (default), auto-accept	Whether tool calls require approval
Show detection reasons	off (default), on	Show why a bash command was gated (e.g. "output redirect", "unknown command")

Install

pi install npm:@eigenwert/pi-gatekeeper
# or
pi install git:github.com/noel-debug/pi-gatekeeper

Or manually:

mkdir -p ~/.pi/agent/extensions/gatekeeper
cp index.ts dialog.ts patterns.ts analyzer.ts allowlist.ts package.json ~/.pi/agent/extensions/gatekeeper/
cd ~/.pi/agent/extensions/gatekeeper && npm install

Architecture

┌─────────────────────────────────────────────────────┐
│                Incoming bash command                │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│  tree-sitter-bash AST parse                         │
│  Parse errors → GATE                                │
│  Falls back to regex if WASM unavailable            │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│  AST walk — classify every node                     │
│  • command → resolve name, unwrap wrappers          │
│  • file_redirect → check for >, >>                  │
│  • dynamic constructs → GATE                        │
│  • function_definition → GATE                       │
│  • recurse into compound/control-flow nodes         │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│  Default-deny allowlist check                       │
│  Command in allowlist with safe args → ALLOW        │
│  Unknown command → GATE                             │
└──────────────────────┬──────────────────────────────┘
                       ▼
                 ALLOW or GATE

Try to break it

No static analysis of a Turing-complete language is perfect. Try to sneak a touch /tmp/pwned past the filter. Try to find a read-only command that gets blocked for no reason. The test suite has n cases — see if you can find case n+1.

License

MIT