![banner](https://assets.aliou.me/github/aliou/pi-guardrails/banner.png)

# Guardrails

> Editable copy of [`@aliou/pi-guardrails`](https://github.com/aliou/pi-guardrails)
> 0.15.0. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for provenance.

Guardrails adds safety checks to Pi so agents are less likely to read secrets, write protected files, access paths outside the workspace, or run dangerous shell commands by accident.

This package installs four Pi extensions:

- **guardrails** for file protection policies, settings, onboarding, and examples.
- **path-access** for controlling access outside the current workspace.
- **permission-gate** for confirming or blocking risky shell commands.
- **workspace-roots** (local addition, not in upstream) for declaring extra
  directories the agent both knows about and is allowed to access.

This distribution also diverges from upstream defaults:

- The built-in `home-ssh` policy (blocks access to `~/.ssh` keys) ships
  **enabled**. Toggle it off per scope through `/guardrails:settings`
  (Policies → home-ssh) if you need to.
- Policy rules support `allowSourcing: true` (set on the built-in
  `secret-files` rule): the file may be loaded with the shell `source` / `.`
  builtin — its values become environment variables without the contents
  entering the agent's context — while every other access (`cat`, `cp`,
  redirects, other args in the same command line) stays blocked. To close the
  loop, the permission gate flags env printing (`env`, `printenv`, bare `set`)
  in the same command line as a `source`.
- Additional built-in policy rules, all enabled: `pi-config` (readOnly on Pi
  and Guardrails settings files, so the agent cannot rewrite its own rules),
  `pi-credentials` (noAccess on `~/.pi/agent/auth.json`), `git-hooks`
  (readOnly on `.git/hooks/**`), and `shell-rc` (readOnly on shell startup
  files) — the last three close persistence vectors.
- Additional permission-gate structural matchers: git safety (`push --force`
  but not `--force-with-lease`, `reset --hard`, `clean -f`, `filter-branch`,
  `branch -D`, `checkout` except `-b`, `restore` except `--staged`,
  forced `switch`, `stash drop/clear`), persistence (`crontab` except `-l`,
  `launchctl load`, `systemctl enable`), supply chain (`npx --yes`,
  `pip install <url>`, `uv add`, `curl | sh`), and exfiltration
  (`curl` uploads, `scp`, remote `rsync`, `gh gist create`, S3 uploads).
- The `search_workspaces` / `search_workspace_files` tools filter out files
  protected by noAccess policies, so protected contents cannot enter the
  agent's context through them.
- An audit log (`audit.enabled`, default on) appends every blocked, prompted,
  and detected-risk event as JSONL to `~/.pi/agent/guardrails-audit.jsonl`.

## Install

```bash
pi install npm:@yassimba/pi-guardrails
```

## First run

After installing, run the onboarding command to choose a starting setup:

```text
/guardrails:onboarding
```

[![Guardrails onboarding walkthrough](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/onboarding.gif)](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/onboarding.mp4)

You can change everything later with:

```text
/guardrails:settings
```

## Included extensions

### guardrails

The `guardrails` extension owns file protection policies and the user-facing commands.

Use it to protect files like `.env`, private keys, local credentials, generated logs, database dumps, or any project-specific path you do not want Pi to read or modify without clear intent.

[![Guardrails policies and settings walkthrough](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/policies.gif)](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/policies.mp4)

Useful commands:

```text
/guardrails:settings
/guardrails:onboarding
/guardrails:examples
/yolo
```

### YOLO mode

Run `/yolo` to disable all Guardrails blocking, confirmation prompts, path restrictions, and protected-result filtering for the current session. A persistent `⚠ YOLO` status appears in the footer while it is active. Subagent supervisors can snapshot this state with `PI_GUARDRAILS_YOLO=1|0`; only those exact values are accepted, and unset or malformed values remain guarded.

```text
/yolo          # enable for this session
/yolo off      # restore Guardrails protections
/yolo status   # show the current mode
```

The choice is stored only in the Pi session, survives reloads and resuming that session, and is never written to Guardrails configuration. New and forked sessions start with protections enabled.

### path-access

The `path-access` extension checks tool calls that target paths outside the current working directory.

It can allow, block, or ask before Pi accesses files elsewhere on your machine. In ask mode, you can allow one file or a directory once, for the session, or always. The operating system's temporary directory—and `/tmp` on Unix—is allowed by default so tools and subagents can use temporary files without prompting.

Granted paths are stored in `pathAccess.allowedPaths` as explicit `{ kind, path }` entries: `file` matches the exact path, `directory` matches the directory and its descendants. Edit them through `/guardrails:settings` (Path Access → Allowed paths, Tab toggles file/directory) or directly in the settings file. Paths support `~/` for home.

[![Guardrails path access prompt walkthrough](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/path-access.gif)](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/path-access.mp4)

### permission-gate

The `permission-gate` extension detects dangerous bash commands before they run.

It catches built-in risky patterns like recursive deletes, privileged commands, disk formatting, broad permission changes, and configured custom patterns. You can allow once, allow for the session, deny, decline and stop (which also aborts the current turn), or configure auto-deny rules. In a headless process, a supervisor may register the versioned `guardrails:approval-broker:register:v1`, `guardrails:approval:request:v1`, and `guardrails:approval:reply:v1` event contract. Without a working broker and timely reply, the command is denied.

[![Guardrails permission gate walkthrough](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/permission-gate.gif)](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/permission-gate.mp4)

### workspace-roots

The `workspace-roots` extension (a local addition to this distribution) declares
extra directories as part of the agent's workspace. Each root is announced in
the system prompt **and** allowed by `path-access`, from a single source of
truth — so with `pathAccess` in `ask` or `block` mode, the agent can work
across your declared roots while everything else outside cwd still prompts or
blocks.

Use `/add-dir` (with autocomplete directory browsing) to add a root; it asks
whether the root is for this session only or should be saved to the project
config. `/add-dir` without arguments lists the current roots. `/remove-dir`
lists every allowed directory outside cwd — session and persisted workspace
roots plus persisted path-access directory grants — and revokes the one you
pick (or pass a path to remove it directly). Session path-access grants are
not listed; they expire with the session.

Configured roots live in `guardrails.json`:

```json
{
  "workspaceRoots": {
    "roots": [
      { "path": "~/Documents/projects/shared" },
      { "path": "../backend", "alias": "backend" }
    ]
  }
}
```

The extension also registers the `search_workspaces` (ripgrep across roots)
and `search_workspace_files` (find by name) tools, and `$$` autocomplete for
expanding a root path in the prompt. It requires `rg` and `find`.

## Configuration

Most configuration should happen through the interactive settings UI:

```text
/guardrails:settings
```

Advanced users can edit the settings file directly:

- Global: `~/.pi/agent/extensions/guardrails.json`
- Project: `.pi/extensions/guardrails.json`

Guardrails writes a `$schema` field to saved settings files, so modern editors provide autocomplete and validation. The generated schema is committed at [`schema.json`](schema.json).

## Examples

Use the examples command to add common policy and command presets without replacing your existing config:

```text
/guardrails:examples
```

[![Guardrails examples command walkthrough](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/examples.gif)](https://assets.aliou.me/github/aliou/pi-guardrails/v0.12.0/examples.mp4)

The available presets live in [`extensions/guardrails/commands/settings/examples.ts`](extensions/guardrails/commands/settings/examples.ts).

## Development

From `plugins/guardrails`:

```bash
npm test
npm run typecheck
npm run lint
npm run gen:schema
npm run check:schema
```