# pi-cc-permission

Plan mode + permission modes for the [pi coding agent](https://pi.dev). · [English](README.md) · [中文](README-CN.md)

## What it does

| Command | Effect |
|---|---|
| `/plan` | Toggle read-only **plan mode** (disables `edit`/`write`, restricts `bash` to a safe allowlist) |
| `/permission manual` | Ask before **every** command and change |
| `/permission auto` | Ask only for **risky** commands |
| `/permission bypass` | Auto-approve **everything** (no prompts) |
| `/permission` | Show the current mode |

Footer shows the active mode: `⏸ plan` · `🛡 manual` · `⚡ auto` · `🟢 bypass`. The mode persists across `/reload`, resume, and branch switches.

## Mode matrix

| Mode | bash | edit / write |
|---|---|---|
| `manual` | ask every time | ask every time |
| `auto` | ask only risky | auto-approve |
| `bypass` | auto-approve | auto-approve |

> Risky commands: `rm -rf`, `sudo`, `git push`, `git reset --hard`, `npm install`, etc. (see `RISKY_BASH` in `index.ts`).

## Install

```bash
# from this repo
pi install git:github.com/sowyer666/pi-cc-permission

# from npm
pi install npm:pi-cc-permission
```

Run `/reload` (or restart pi) after installing.

## Configuration (optional)

Startup defaults live in `~/.pi/agent/permission-modes.json`:

```json
{
  "defaultMode": "manual",
  "startInPlan": false,
  "askForAllBashInManual": true
}
```

- `defaultMode`: `manual` | `auto` | `bypass`
- `startInPlan`: start in plan mode
- `askForAllBashInManual`: `true` = manual mode asks even for read-only bash; `false` = ask only for mutating commands

CLI override: `pi --plan --permission-mode auto`.

## Notes

- Requires pi `^0.84` (Node `>=22.19`)
- Read-only tools (`read` / `grep` / `find` / `ls`) are never gated
- In non-interactive runs (`pi -p` / JSON mode) anything that would prompt is **blocked** (fail-closed), except in `bypass` mode
- To adjust the safe/risky command lists edit `SAFE_BASH` / `RISKY_BASH` in `index.ts`, then `/reload`

## License

MIT