permission-gate

A small pi extension that prompts for confirmation before running potentially dangerous bash or PowerShell commands or writing to protected paths.

This started from the original permission-gate.ts example in earendil-works/pi and adds conservative shell and path hardening.

What it checks

• rm -rf
• PowerShell Remove-Item -Recurse -Force and its standard aliases, including module-qualified, interpolated, splatted, and backtick-escaped forms
• sudo
• chmod / chown with 777
• direct write / edit calls touching normalized protected paths:
  • exact .git path segments
  • exact node_modules path segments
  • secret-bearing .env files such as .env and .env.production

Safe .env templates/examples such as .env.example and .env.production.template are allowed.

If pi is running without an interactive UI, it blocks matching commands and protected path writes by default.

For Pi's built-in local Windows PowerShell tool, commands that pass the fast lexical checks are also parsed with the same PowerShell installation's AST parser before execution. Malformed input, parser failures, Remove-Item parameter splatting, command-resolution changes (aliases/modules/providers/direct function or filter definitions), known script/process/job/member invocation wrappers, computed member calls, and analyzer inputs above 16,000 UTF-8 bytes are treated conservatively and require confirmation (or are blocked when no UI is available). Computed targets passed to provider-capable mutation commands also require confirmation because the target could resolve to Alias: or Function:. Literal quoted/commented examples, including literal here-strings, stay benign. Definitely enabled -WhatIf removals (-WhatIf, -WhatIf:$true, or -WhatIf:1) remain non-destructive and are allowed; computed switch values require confirmation.

Non-Windows and custom/remote powershell tools receive the conservative lexical checks, but only Pi's built-in local Windows tool can be verified with its actual parser. Pi extensions are trusted code: tool overrides, remote operations, spawn hooks, and mutations made by handlers loaded after this gate are outside its boundary and must enforce their own final-input policy.

This is a targeted confirmation guard for the command classes listed above, not a shell sandbox or a proof that every unlisted executable/API is harmless.

Pi 0.99 dispatch boundary

The policy is deliberately named-tool-only: it checks bash, powershell, write, and edit tool_call events. Pi 0.99 routes ctx.executeTool() calls (including calls made by codemode) through the same preflight tool-call pipeline and supplies parentToolCallId; the named checks therefore apply to nested calls too. Executed calls (including execution errors and isError results) reach the tool-result hook. Preflight-blocked, invalid, and unknown-tool calls instead produce Pi's host error result and, for nested calls, a bounded nested-call record without an after-execution tool_result event. Confirmation cancellation, UI failure, and missing UI fail closed.

MCP calls also pass through Pi's host pipeline, but arbitrary mcp__<server>__<tool> names are outside this extension's existing guarantee. This extension does not authorize arbitrary MCP tools, infer policy from readOnlyHint/destructiveHint annotations, or provide a universal MCP security sandbox. Any annotation-based or broader MCP policy requires separate human approval. Custom tools, remote/overridden implementations, and later handlers must enforce their own final-input policy.

Install

Standalone npm package

pi install npm:@diegopetrucci/pi-permission-gate

Collection package

pi install npm:@diegopetrucci/pi-extensions

GitHub package

pi install git:github.com/diegopetrucci/pi-extensions

Then reload pi:

/reload

Notes

• Hooks the tool_call event.
• Inspects bash, powershell, write, and edit tool calls.
• Validates shell timeouts as well as command strings and fails closed on malformed calls.
• Normalizes relative/absolute paths before matching so traversal tricks do not bypass the guard.
• Prompts with a simple Yes / No selector before allowing dangerous commands or protected path writes.