@fgladisch/pi-bash-approval

Guards Pi bash tool calls behind an interactive allow-list. Every bash tool call is intercepted; commands matching configured patterns run silently, anything else prompts the user. In non-interactive contexts (pi -p, no UI), unknown commands are blocked with a reason pointing at the config files.

Install

pi install npm:@fgladisch/pi-bash-approval

Config

The extension reads two files:

1. Global settings: ~/.pi/agent/settings.json
2. Allow-list rules: ~/.pi/agent/.bash-approval

Global settings (settings.json)

splitChains and notifyHerdr live under bashApproval:

{
  "bashApproval": {
    "splitChains": true,
    "notifyHerdr": false
  }
}

If missing or malformed, splitChains defaults to true and notifyHerdr defaults to false.

Allow-list rules (.bash-approval)

One rule per line:

# bash approval allow-list
ls
ls:*
git status:*
npm test:*

Blank lines and # comment lines are ignored.

Pattern syntax (.bash-approval lines)

Pattern	Matches
ls	exact: ls only
ls:*	ls exactly, ls <anything> (space-separated)
git status:*	git status exactly, git status <anything>
git*	trailing-* glob: any command starting with raw git

The :* form is recommended: it requires an exact prefix plus trailing space, so git status:* does not match git statusfoo. Bare * is a raw prefix match and should be used sparingly.

splitChains

Default true: split incoming commands on shell separators (&&, ||, ;, |, &, newline) and require every segment to match the allow-list. Example: cd foo && git log only runs unprompted when both segments are allow-listed. Set false to match the entire command string as one unit.

notifyHerdr

Default false. Set true to emit a herdr:blocked event ({ active: true, label }) while an interactive approval prompt is open, so a co-installed herdr agent-state extension reports the pane as blocked, and a matching { active: false } when the prompt resolves. The event is a no-op when herdr is not installed.

Shell control filtering

When splitChains is true, shell control/declaration segments are ignored so approval checks focus on actual commands:

• ignored heads include if, then, elif, else, for, do, done, fi, while, until, case, esac, function
• grouping parentheses around subshells are treated as shell syntax, so (pnpm dev & echo $!) evaluates the inner pnpm dev and echo commands
• condition tests ([ ... ], [[ ... ]], test ...) are ignored
• assignment-only segments like FOO=bar are ignored
• redirection-only segments like > /tmp/out after shell groups are ignored
• separators inside command substitutions like $(git ls-files | sort) are not treated as outer command-chain separators
• assignment prefixes before commands are stripped, e.g. FOO=bar npm test evaluates as npm test
• command substitutions inside assignment tokens are evaluated by their inner command, e.g. tmp=$(mktemp -d /tmp/foo-XXXXXX) evaluates as mktemp -d /tmp/foo-XXXXXX

Prompt behavior

Unknown interactive commands show options:

• Allow once: allow this command without changing config.
• Allow always (exact): <command>: append the full trimmed command.
• Allow always: <prefix>:*: append the suggested parameter-aware prefix rule. The suggestion uses the first two tokens when present (git status:*, npm install:*, mkdir -p:*), otherwise the first token (ls:*). The suggestion is derived from the first failing chain segment, not the command head.
• Allow always (command): <command>:*: append command-only prefix rule for the first token of the failing segment (mkdir:*, git:*, npm:*). Hidden when it duplicates the parameter-aware suggestion.
• Deny: block with reason Blocked by user.

Selecting nothing (cancel) is treated as deny. "Allow always" choices persist immediately to ~/.pi/agent/.bash-approval.

Slash commands

Command	Action
/bash-approval-reload	Re-read ~/.pi/agent/.bash-approval and ~/.pi/agent/settings.json from disk.
/bash-approval-list	Show currently allowed bash patterns.

Inter-extension events

The extension emits lifecycle events on pi.events so another extension can mirror approvals remotely while the local TUI remains active. For manual approval requests the first valid local or remote answer wins; when a remote answer wins, the open local prompt is dismissed. Late remote responses return { accepted: false, reason: "already_resolved" }. Listener failures are ignored so normal bash approval behavior remains the fallback.

Event	When it fires
pi-bash-approval:config_loaded	After startup config load.
pi-bash-approval:reloaded	After /bash-approval-reload.
pi-bash-approval:evaluated	After allow-list evaluation, including auto-allow.
pi-bash-approval:request	Before opening the local approval prompt.
pi-bash-approval:resolved	After local or remote approval decision wins.
pi-bash-approval:rule_persisted	After an Allow always rule write attempt.
pi-bash-approval:allowed	When a command is allowed by allow-list or user choice.
pi-bash-approval:blocked	When a command is blocked.
pi-bash-approval:closed	When a manual approval request can no longer answer.
herdr:blocked	Toggled active around an open prompt (notifyHerdr).

pi-bash-approval:request includes stable option IDs and a respond(response) callback. Remote responders can submit { source: "remote", action: "allow_once" }, { source: "remote", action: "allow_always", optionId, rule }, or { source: "remote", action: "deny", reason? }.