my-pi/pi-permission-auto-review/README.md

@mzwing/pi-permission-auto-review

A Pi extension that adds Codex-style automatic permission reviews to @gotgenes/pi-permission-system.

my-pi maintenance note: This directory was imported from the upstream source tag @mzwing/pi-permission-auto-review@0.2.0 at commit 8d196e4ef0884cac8326c366191dad3f585d470a. It is loaded from source and maintained directly by my-pi, like pi-rtk-optimizer; npm dist output is not used. The local compatibility baseline is Node.js 22.19+, Pi 0.84.x, and @gotgenes/pi-permission-system 26.2.x.

Differences between @gotgenes/pi-permission-model-judge

@gotgenes/pi-permission-model-judge is a general-purpose model-based authorizer that can be used to evaluate any permission request.

Ours is mostly specialized for OpenAI's codex-auto-review model, which is trained to evaluate permission requests in the context of a coding assistant. Our extension aims at providing Codex-style automatic permission reviews for Pi's coding agent.

The bundled baseline is a Pi-specific adaptation of OpenAI Codex Guardian's policy_template.md and policy.md at revision c4f42d161ae44a8d696ee9fb595709661979d187. It is bundled at build time; the extension never fetches policy text while reviewing an action.

Install

The my-pi root package loads pi-permission-auto-review/index.ts directly and installs its runtime dependencies. Do not install the upstream npm package separately, or the same authorizer may be registered twice.

For isolated source development, install this directory's development dependencies and run it through the local entry point:

npm install
pi -e ./index.ts

This maintained source variant uses Pi's current ModelRegistry.getProvider() API directly and does not depend on @mzwing/pi-polyfill.

Enable

Add "auto-review" to pi-permission-system's config:

{
  "authorizerChain": ["auto-review"]
}

The config is normally located at ~/.pi/agent/extensions/pi-permission-system/config.json.

Extension config can be omitted. The defaults are:

{
  "provider": "openai-codex",
  "model": "codex-auto-review",
  "reasoning": "low",
  "timeoutMs": 90000,
  "includeBaselinePolicy": true
}

codex-auto-review is an official hidden model. The extension derives it from Pi's openai-codex provider and reuses the existing Codex login.

Configuration

Scope	Path
Global	~/.pi/agent/extensions/pi-permission-auto-review/config.json
Project	<cwd>/.pi/extensions/pi-permission-auto-review/config.json

Project fields override global fields. PI_CODING_AGENT_DIR replaces ~/.pi/agent when set.

Field	Default	Description
provider	openai-codex	Pi model-registry provider id
model	codex-auto-review	Model id within the selected provider
reasoning	low	Reasoning level for reviewer calls
timeoutMs	90000	Total budget across all retry attempts
includeBaselinePolicy	true	Include the built-in Codex-style risk policy
additionalPolicy	omitted	Trusted operator policy appended to it

See the example config and bundled JSON Schema. Unknown or invalid fields disable automatic decisions and fall through to the normal prompt.

Use /permission-auto-review in Pi's interactive TUI to edit and apply global or project config without reloading the session. Available subcommands:

/permission-auto-review show
/permission-auto-review path
/permission-auto-review reset [global|project]
/permission-auto-review help

Custom providers and models must be defined in Pi's ~/.pi/agent/models.json, then selected with this extension's provider and model fields. To replace the built-in risk policy completely, set includeBaselinePolicy to false and provide a non-empty additionalPolicy.

Behavior and Limits

Authorization evidence

The reviewer reads the current session's complete active branch with SessionManager.getBranch(), rather than only the post-compaction model context. This keeps original user authorization available after compaction without mixing in abandoned branches.

Only these transcript records can establish authorization:

• Pi session user-role messages (source: "user");
• completed, non-cancelled responses to recognized ask_user_question and plan_mode_question calls (source: "user_interaction").

Pi does not persist the original input event source on user-role messages, so source: "user" is a trust boundary provided by the Pi runtime rather than cryptographic proof of keyboard input. Trusted extensions can intentionally create such messages with sendUserMessage(); as with the rest of Pi's extension model, only trusted extension code should be installed.

Structured question responses are accepted only when the non-error result matches a preceding recognized tool call and are rebuilt from details.answers data. Free-form tool-result text is never promoted to user evidence. Assistant messages, ordinary tool calls/results, custom messages, and compaction/branch summaries remain untrusted even if their text claims to be user content.

Transcript rendering uses separate 10k-token message and tool budgets with per-entry truncation. The first and latest trusted records are retained first, then other trusted records from newest to oldest. The 40-entry recency cap applies only to assistant/tool evidence, so later tool activity cannot evict an already selected user authorization. Truncation indicates missing information; it does not itself raise intrinsic action risk.

Permission boundaries

• Model, authentication, timeout, provider, or response-format failures defer to the normal human prompt.
• Unexpected internal review failures also defer to the human prompt instead of escaping into the permission gate.
• Three consecutive denials, or ten denials in the latest fifty reviews, open a circuit breaker until the next Pi turn.
• my-pi's maintained pi-permission-system keeps every path request inside the delegation envelope. For external_directory, built-in read-only path tools (read, find, grep, ls) may accept an auto-review allow; write, edit, bash, unknown tools, and undetermined surfaces are downgraded to the normal human prompt.

Diagnostics

Each auto_review.decision emitted after transcript construction adds content-free context diagnostics (configuration failures that defer before a review do not have transcript diagnostics):

• policyRevision
• contextSource (active-branch)
• transcriptEntriesRetained
• transcriptEntriesOmitted
• transcriptEntriesTruncated
• directUserEntriesRetained / directUserEntriesOmitted / directUserEntriesTruncated
• userInteractionEntriesRetained / userInteractionEntriesOmitted / userInteractionEntriesTruncated
• latestTrustedEntryRetained

These fields distinguish missing or truncated authorization evidence from a model decision made after receiving trusted evidence. Transcript text and model rationale are not persisted. The records are written through pi-permission-system's existing permission-review log when that log is enabled.

License

MIT