Policy Engine

Purpose

This package provides a policy plugin for Pi. It combines host-specific prechecks, deterministic rules, a JSONL decision cache, and an LLM reviewer. Decisions are allow, deny, or ask.

Layout

• src/core/ — shared Bash parsing, glob resolution, deterministic checks, pipeline, reviewer, llama.cpp provider, cache, audit, normalization, and configuration.
• src/pi/ — Pi extension, static permissions, UI, and session Bash overrides.
• test/core/, test/pi/ — unit and extension tests.

The package root and ./pi export the Pi extension. src/index.ts re-exports ./pi/index for Pi extension loading.

Your general goal is to keep this code simple. Don't add things you're not asked for. If given a choice, do less.

Policy flow

Pi evaluates session Bash overrides and static permissions before deterministic rules. Pi and raw core calls share structured Bash parsing and async evaluation. Unsupported Bash does not receive a deterministic allow and falls back to full-input LLM review. Commands are checked independently without tracking shell state across commands. Path checks and metadata-only glob expansion use the request's working directory; git -C is local to its command. Cached Bash allows are not reused or written.

The shared pipeline evaluates deterministic rules, then the cache, then the LLM reviewer. Pi's /pe-skip-permissions command is local to the loaded extension instance. In that mode static permissions, deterministic rules, and cached decisions still apply; it skips LLM review and allows uncached requests.

MCP tools bypass the Pi adapter policy boundary.

Testing

Test only policy decisions: static permissions, deterministic rules, and LLM decisions. Do not add tests for pipeline behavior, cache reads or writes, audit records or sources, normalization, configuration, providers, or other plumbing. A request to change plumbing is not a request to test it; add a plumbing test only when the user explicitly asks for that test.

Rules

src/core/deterministic.ts contains allowed commands and applies policy to structured Bash. src/core/review.ts contains the LLM policy prompt. src/core/normalize.ts contains POLICY_VERSION.

When changing deterministic patterns or matching behavior:

• Keep hard-allow rules anchored and strict.
• Keep config-allow rules protected from shell control syntax.
• Add or update tests.
• Bump POLICY_VERSION in src/core/normalize.ts only immediately before committing rule changes, to invalidate cached LLM decisions.

Commands

bun test
bun prettier -w .
bunx eslint src test
bunx tsc --noEmit

Tests use temporary configuration and state paths. Do not read or commit credentials, cache files, or audit logs.