pi-guardian

Codex-style sandbox-boundary guardian gate for pi-coding-agent.

pi-guardian wraps bash so commands run in the OS sandbox first. When the sandbox blocks an action, pi-guardian asks a locked-down reviewer whether one unsandboxed retry is allowed. It retries at most once only on explicit allow; otherwise it fails closed and instructs the agent not to work around the denial.

Features

• Sandbox-first bash execution on supported platforms.
• Sandbox denial detection for filesystem, network, macOS sandbox, and bubblewrap-style failures.
• Reviewer modes: deny, auto, ask, and allow-for-testing.
• auto reviewer runs in an isolated in-memory SDK session with read-only tools: read, grep, find, ls.
• Optional Codex-style codex-auto-review preference with fallback to reviewer.model or the current pi model.
• Denial circuit breaker for repeated denials.
• Append-only JSONL audit log for review requests, decisions, and breaker trips.

Install

From npm:

pi install npm:@ikuradon/pi-guardian

During development:

npm install
pi -e ./src/index.ts

This package declares a pi extension entry in package.json.

Configuration

Create .pi/guardian.json in your project. Minimal automatic-review configuration:

{
  "reviewer": {
    "mode": "auto",
    "preferCodexAutoReview": true
  }
}

model is optional. If omitted, fallback uses the current pi model. If set, it acts as the reviewer model override and as the fallback after codex-auto-review:

{
  "reviewer": {
    "mode": "auto",
    "preferCodexAutoReview": true,
    "model": "openai-codex/gpt-5.5",
    "thinking": "low",
    "timeoutMs": 20000
  }
}

Fallback order with preferCodexAutoReview: true:

codex-auto-review -> reviewer.model -> current pi model

Fallback order with preferCodexAutoReview: false:

reviewer.model -> current pi model

See .pi/guardian.example.json for a fuller sample.

Reviewer Modes

deny is the default and always fails closed.

auto uses an in-process pi SDK reviewer. The reviewer has no extensions, skills, prompts, or context files, and only read-only tools are enabled.

ask prompts the user for approval before one unsandboxed retry. In non-interactive print mode, pi's confirmation UI returns false, so this mode fails closed.

allow-for-testing is only for local retry-path tests. Do not use it as a security policy.

Sandbox Defaults

Default filesystem policy denies reads from common secret locations and allows writes to the project plus temp directories:

{
  "filesystem": {
    "denyRead": ["~/.ssh", "~/.aws", "~/.gnupg"],
    "allowWrite": [".", "/tmp", "/private/tmp"],
    "denyWrite": [".env", ".env.*", "*.pem", "*.key"]
  }
}

Default network policy allowlists common package and source hosts such as GitHub, npm, and PyPI.

Audit Log

Audit logs are enabled by default and written to .pi/guardian-reviews.jsonl:

{
  "auditLog": {
    "enabled": true,
    "path": ".pi/guardian-reviews.jsonl"
  }
}

Each review records a stable action hash, the sandbox denial request, the reviewer decision, and any denial-breaker trip.

Commands

Show runtime status inside pi:

/guardian

Local validation:

npm run check
npm test
npm run sdk-reviewer:dry-run
npm run sdk-smoke

Smoke-test history and exact manual smoke plans live in docs/smoke-tests.md.

Release Status

Initial release preparation is complete for @ikuradon/pi-guardian. npm publish --dry-run has passed with the expected tarball contents. Remaining step before real publication is final operator confirmation for npm publish --access public.