pi-trust-policy

Bash command allowlist system for pi. Group trusted commands into policies, toggle them on/off, and get prompted for anything not covered.

Install

pi install git:github.com/biratkk/pi-trust-policy

Or for a quick test:

pi -e git:github.com/biratkk/pi-trust-policy

Getting Started

After installing, open pi and run:

/trust-policy

That's it. Type to search, Enter to cycle activation states.

Usage

1. Write a policy YAML file

Create ~/.pi/agent/trust-policy/my-dev-tools.yaml:

name: my-dev-tools
description: Development commands for my project

includes:
  - unix-read

commands:
  - glob: "npm run *"
    description: "Run package scripts"
    pipe: true
  - glob: "docker build {*,*/**}"
    description: "Build Docker images"
    redirect: append

2. Activate it

Run /trust-policy in pi to open the TUI manager. Type to fuzzy-search, Enter/Space to cycle through activation states:

| State | Meaning | |-------|--------| | inactive | Not active anywhere | | local | Active in project .pi/trust-policy/ only | | global | Active in ~/.pi/agent/trust-policy/ (all projects) | | global & local | Active in both scopes |

Or manually create ~/.pi/agent/trust-policy/policy.json:

{
  "active": ["unix-read"]
}

3. Work normally

Trusted commands run without interruption. Untrusted commands prompt you with options to allow once, deny, or persist to a group.

Commands

| Command | Description | |---------|-------------| | /trust-policy | Open TUI manager — toggle policies active/inactive |

Policy Format

name: my-policy
description: What this policy covers

includes:                    # optional: inherit from other groups
  - grep-read
  - cat-read

commands:
  - glob: "docker build *"
    description: "Build images"  # optional
    pipe: false                  # allow in pipelines (default: false)
    embedded: false              # allow in $() substitutions (default: false)
    redirect: none               # none | append | overwrite | both (default: none)

Redirect Modes

| Value | Allows | |-------|--------| | none | No redirects — command must run without > or >> | | append | >> only | | overwrite | > only | | both | Both > and >> |

Starters

Built-in starter policies are organized by risk level and can be activated from the TUI:

| Policy | Category | Includes | |--------|----------|----------| | unix-read | Safe | grep, cat, ls, head, tail, wc, find, cut, sort | | unix-write | Modifying | sed, awk, tee, cp, curl -o, sort -o | | unix-dangerous | Destructive | rm, shred, truncate, mv |

Each aggregate policy composes per-tool policies (e.g., unix-read includes grep-read, cat-read, etc.). Per-tool policies live in subdirectories under ~/.pi/agent/trust-policy/policies/ and can also be activated individually for granular control.

On first session start, starters are migrated to ~/.pi/agent/trust-policy/policies/. You own the copies and can freely edit them.

How It Works

1. At session start, migrates bundled starter policies to ~/.pi/agent/trust-policy/policies/ (only new files, preserves edits)
2. Loads policy.json from global (~/.pi/agent/trust-policy/) and local (.pi/trust-policy/) directories
3. Resolves all active groups and their includes recursively (with cycle detection)
4. Intercepts every bash tool call and validates against the merged allowlist
5. Recursively parses compound commands (pipelines, &&/||/;, $(), bash -c) using unbash
6. Validates redirect operators (>, >>) against each entry's redirect permission
7. Commands with env vars, eval, or unparseable elements always prompt

Security Model

• Pure allowlist — only explicitly permitted commands run without confirmation
• Fail-safe defaults — pipe: false, embedded: false, redirect: none
• Redirect enforcement — > and >> require explicit redirect permission on the matching entry
• Env vars always prompt — VAR=val cmd and export trigger confirmation
• Recursive validation — every segment of a compound command is checked independently

File Structure

~/.pi/agent/trust-policy/              # global
├── policy.json                        # {"active": ["unix-read", "unix-write"]}
├── policies/                          # migrated starters (source of truth)
│   ├── unix-read.yaml                 # aggregate: includes per-tool policies
│   ├── unix-write.yaml
│   ├── unix-dangerous.yaml
│   ├── grep/
│   │   └── grep-read.yaml             # per-tool policy
│   ├── sed/
│   │   └── sed-write.yaml
│   └── rm/
│       └── rm-destructive.yaml
└── my-custom-policy.yaml              # user-created policies

<project>/.pi/trust-policy/            # local (project-scoped)
├── policy.json
└── project-scripts.yaml

Both scopes merge additively. Local policies apply only within that project tree.

License

MIT