pi-edit-approval

Pi coding-agent extension that asks before the agent modifies files.

• Reads stay free — read / grep / find / ls are never prompted
• Writes need approval — built-in write / edit, plus common mutator tool names (e.g. MCP replace)
• Profiles — strict / workspace / review / off presets
• Diff preview — approval UI shows a compact unified-style diff for edits
• Persistent memory — always allow/deny a file or directory across sessions
• Protected paths — hard-deny for .env, keys, etc.
• Workspace-aware — separate policies inside vs outside the git root (or cwd)

Keywords: pi-package, pi, pi-extension, pi-coding-agent.

Pi has no built-in “confirm before edit” switch. This package adds that gate via the extension tool_call hook.

Install

Requires Pi (@earendil-works/pi-coding-agent).

You can install from npm or GitHub.

From npm (recommended)

pi install npm:pi-edit-approval

Pin a version:

pi install npm:[email protected]

From GitHub

pi install git:github.com/ShawnMa123/pi-edit-approval

pi install https://github.com/ShawnMa123/pi-edit-approval
pi install git:github.com/ShawnMa123/[email protected]

Try once without installing

pi -e npm:pi-edit-approval
pi -e git:github.com/ShawnMa123/pi-edit-approval

Local path (development)

pi install /path/to/pi-edit-approval
pi -e ./extensions/edit-approval.ts

Project-local install

pi install -l npm:pi-edit-approval
pi install -l git:github.com/ShawnMa123/pi-edit-approval

After install, start a new session or run /reload.

If you previously copied edit-approval.ts into ~/.pi/agent/extensions/, remove that copy to avoid loading the extension twice.

Profiles

| Profile | Inside workspace | Outside workspace | Notes | |---------|------------------|-------------------|--------| | strict (default) | ask | ask | Safest everyday default | | workspace | allow | ask | Codex-style workspace-write | | review | ask | ask | Larger diff preview (diffMaxLines: 80) | | off | allow | allow | Disables write gating |

Switch live (persists to config):

/edit-approval profile workspace
/edit-approval profile strict

Default behavior

| Tool / path | Default (strict) | |-------------|--------------------| | read, grep, find, ls | Always allow | | write / edit inside workspace | Ask (+ diff preview) | | write / edit outside workspace | Ask (labeled OUTSIDE workspace) | | Paths matching protectedPaths | Deny (no prompt) | | Paths in persistent allow memory | Allow | | Paths in persistent deny memory | Deny | | bash | Not gated (see gateBash) | | Non-interactive (-p / no UI) when policy is ask | Block |

Workspace root = git rev-parse --show-toplevel when available, otherwise the session cwd.

Prompt choices

• Yes — this call only
• Yes, this file this session
• Yes, all workspace writes this session (if enabled)
• Yes, all outside writes this session (if enabled)
• Yes, always allow this file — persists to memory
• Yes, always allow this directory — persists prefix allow
• No
• No, this file this session
• No, always deny this file — persists to memory

Configuration

Optional file:

~/.pi/agent/edit-approval.json

Copy the example from the package:

# from a clone / install tree
cp edit-approval.example.json ~/.pi/agent/edit-approval.json

Copy-Item edit-approval.example.json $env:USERPROFILE\.pi\agent\edit-approval.json

Example: strict (default)

{
  "profile": "strict",
  "persistentMemory": true,
  "diffMaxLines": 40,
  "protectedPaths": [".env", ".env.", "id_rsa", "id_ed25519", ".npmrc", "credentials"],
  "gateBash": false,
  "extraMutatingTools": []
}

Example: Codex-style workspace-write

{
  "profile": "workspace"
}

Or:

{
  "profile": "strict",
  "workspaceWrites": "allow",
  "outsideWrites": "ask"
}

Explicit workspaceWrites / outsideWrites override the profile baseline when set in the JSON file.
/edit-approval profile <name> rewrites those fields to match the preset.

Options

| Key | Type | Default | Meaning | |-----|------|---------|---------| | profile | strict | workspace | review | off | strict | Named preset | | workspaceWrites | allow | ask | deny | from profile | Inside workspace | | outsideWrites | allow | ask | deny | from profile | Outside workspace | | allowSessionBypassInWorkspace | boolean | true | Offer session-wide workspace allow | | allowSessionBypassOutside | boolean | false | Offer session-wide outside allow | | persistentMemory | boolean | true | Offer always-allow / always-deny | | diffMaxLines | number | 40 | Diff/preview size in the prompt | | protectedPaths | string[] | see example | Substring / *.ext hard-deny | | gateBash | boolean | false | Confirm every bash (noisy) | | extraMutatingTools | string[] | [] | Extra tool names to gate |

Reload without restarting Pi:

/edit-approval reload

Persistent memory

File:

~/.pi/agent/edit-approval-memory.json

{
  "allowPaths": [],
  "allowPrefixes": [],
  "denyPaths": [],
  "denyPrefixes": []
}

Managed from the approval UI or:

/edit-approval allow path/to/file
/edit-approval deny path/to/file
/edit-approval forget path/to/file
/edit-approval memory

Order of checks (first match wins where applicable):

1. Session deny
2. Protected paths → deny
3. Memory deny → deny
4. Memory allow → allow
5. Session allow / session workspace|outside bypass → allow
6. Policy allow / ask / deny

Commands

| Command | Action | |---------|--------| | /edit-approval | Status (profile, policies, session, memory counts) | | /edit-approval reset | Clear session allow/deny bypasses | | /edit-approval reload | Re-read config + memory files | | /edit-approval profile <name> | Set profile and persist | | /edit-approval allow <path> | Persist allow path | | /edit-approval deny <path> | Persist deny path | | /edit-approval forget <path> | Remove path from memory | | /edit-approval memory | Dump memory entries |

What gets gated

Always treated as mutators:

• Built-in write, edit

Also matched by name (case-insensitive), including MCP-style names:

• replace, create_file, delete_file, apply_patch, str_replace
• Patterns like fastctx_replace, mcp_foo_write, …

Path fields inspected:
path, file_path, filePath, filepath, target, target_path, filename, paths[]

Edit preview also understands oldText / newText and old_string / new_string.

Limitations

1. bash can bypass file gates unless gateBash is true. Redirects are not parsed by default.
2. Not an OS sandbox — only Pi tool calls this extension sees.
3. Diff preview is a compact summary, not a full side-by-side reviewer (pi-show-diffs is complementary).
4. In print / headless modes without UI, ask becomes a hard block.

For stronger isolation, use containers or a sandbox package; see Pi security docs.

Package layout

pi-edit-approval/
├── package.json
├── extensions/edit-approval.ts
├── edit-approval.example.json
├── CHANGELOG.md
├── LICENSE
└── README.md

{
  "keywords": ["pi-package", "pi", "pi-extension", "pi-coding-agent"],
  "pi": { "extensions": ["./extensions"] }
}

The pi-package keyword is used by the Pi package gallery.

Development

git clone https://github.com/ShawnMa123/pi-edit-approval.git
cd pi-edit-approval
pi -e ./extensions/edit-approval.ts
# or
pi install .

No build step: Pi loads the TypeScript extension directly.

Uninstall

pi remove npm:pi-edit-approval
pi remove git:github.com/ShawnMa123/pi-edit-approval

Optional cleanup:

rm ~/.pi/agent/edit-approval.json
rm ~/.pi/agent/edit-approval-memory.json

License

GPL-3.0-only

Related

• Pi packages documentation
• Pi extensions documentation
• Upstream examples: permission-gate.ts, protected-paths.ts
• Complementary: pi-show-diffs (full diff UI)
• Heavier alternatives: various pi-permission-* packages