pi-protected-paths

Safety net extension for pi. Blocks write/edit/read operations to sensitive files so your coding agent doesn't accidentally corrupt critical project files or leak secrets.

Install

pi install npm:pi-protected-paths

Quick Start

pi -e ./index.ts

What it protects

Secrets & environment: .env, .env.* (except .env.example), .dev.vars

Auth & credentials: .npmrc, .yarnrc.yml, .yarnrc, .netrc, _netrc, service-account.json, credentials.json

SSH & private keys: .ssh/ directory, id_rsa, id_dsa, id_ed25519, id_ecdsa, *.pem, *.key, *.p12, *.pfx

Cloud platform config: .aws/, .docker/, .gnupg/

Secrets management: .sops.yaml, .sops.yml, .vault-token, secrets/

Version control: .git/, .gitconfig, .git-credentials

Dependencies: node_modules/

For the full table, see AGENTS.md.

How it works

Hooks into pi's tool_call event with two layers:

Write/Edit Protection

When a write or edit tool call targets a protected path, it returns { block: true } and shows a warning notification.

Bash Read Protection (NEW)

Agents commonly bypass write/edit restrictions by using shell tools (cat, grep, head, cp, etc.) to read protected files directly. Protected-paths now intercepts every bash tool call and checks whether the command references a protected path as a read target — blocking it before execution.

Detected patterns:

Pattern	Example	Blocked?
Read command + path	cat .env, grep KEY .env	✅
Input redirection	< .env, cat < .env	✅
Shell sourcing	source .env, . ./.env	✅
Copy/move of protected file	cp .env /tmp/, mv .env ../	✅
Command substitution	echo $(cat .env)	✅
Sandbox-prefixed	cat /workspace/typescript/.env	✅
.env.example (template)	cat .env.example	❌ (allowed)

Combining with pi-sandbox-proxy

Use alongside pi-sandbox-proxy for defense-in-depth:

• Protected paths blocks local file reads of secrets via bash
• Proxy gates all network operations (vuln scanning, approval flows)
• Container sandbox isolates filesystem operations in Docker

pi -e ./index.ts -e ../pi-sandbox-proxy/index.ts -e ../pi-container-sandbox/index.ts

Architecture

index.ts                     # Entry — activates protected paths
features/
└── protected-paths.ts       # tool_call hook with filename-aware blocking

Single dependency: @earendil-works/pi-coding-agent.