@hank-warren/pi-auto-permissions 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Can Celik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,7 @@
+# Attribution
+
+This package is a fork of [`@ogulcancelik/pi-auto-permissions`](https://github.com/ogulcancelik/pi-extensions/tree/main/packages/pi-auto-permissions), version 0.1.3, from upstream commit `976550bff7224e5a6478f5a00da67df73c158250`.
+
+The original work is Copyright (c) 2026 Can Celik and is used under the MIT License included in [`LICENSE`](LICENSE).
+
+Fork-specific changes (the `reviewEvidence.userAnswerTools` dialog-answer evidence feature, proposed upstream in [ogulcancelik/pi-extensions#24](https://github.com/ogulcancelik/pi-extensions/issues/24) / [PR #25](https://github.com/ogulcancelik/pi-extensions/pull/25)) are Copyright (c) 2026 Hank Warren and are released under the same MIT License.

package/README.md

@@ -0,0 +1,240 @@
+# pi-auto-permissions
+
+> **Published fork.** This is `@ogulcancelik/pi-auto-permissions` 0.1.3 (MIT, Can Celik)
+> plus the dialog-answer evidence feature proposed upstream in
+> [ogulcancelik/pi-extensions#24](https://github.com/ogulcancelik/pi-extensions/issues/24) /
+> [PR #25](https://github.com/ogulcancelik/pi-extensions/pull/25). Switch back to the
+> upstream package once it ships the feature. Never install both packages at once, or
+> every Bash call is reviewed twice. The upstream `index.test.ts` harness suite is not
+> vendored; the pure config/evidence tests live in `test/`.
+
+A context-aware permission system for Pi shell commands, with an automated guardian that checks what the user actually authorized.
+
+Pi Auto Permissions pauses configured Bash commands before execution. A guardian model reviews the exact command against a compact view of the current conversation:
+
+- Clearly authorized and compliant commands run automatically.
+- Authorized commands that violate the user's constraints are blocked with feedback so the agent can revise them.
+- Commands without clear authorization are sent to the user for confirmation.
+- High-risk commands always require confirmation.
+
+Only user messages can grant permission or impose constraints. The assistant cannot authorize its own command.
+
+## Example
+
+Suppose Git commits are globally guarded.
+
+If the user says:
+
+> Fix the failing test and commit it with a concise lowercase message.
+
+Then a matching commit can run without another permission prompt:
+
+```text
+git commit -m "fix retry test"
+```
+
+But the guardian rejects a command that violates the request:
+
+```text
+git commit -m "Fix the Failing Retry Test and Update Documentation"
+```
+
+If the conversation never authorized a commit, an interactive Pi session asks the user before running it. A non-interactive session blocks it.
+
+Permissions are contextual, not permanent. Each command is judged against the current conversation and the exact action being proposed.
+
+## Install
+
+```bash
+pi install npm:@hank-warren/pi-auto-permissions
+```
+
+For local development:
+
+```bash
+pi install /absolute/path/to/pi-extensions/packages/pi-auto-permissions
+```
+
+Remove or disable other extensions that gate the same commands to avoid duplicate prompts.
+
+## Define your policy
+
+The extension ships with an empty command policy. Nothing is guarded until you add rules, and commands that do not match a rule run normally.
+
+Configuration is read before every Bash command from:
+
+```text
+$PI_CODING_AGENT_DIR/pi-auto-permissions/config.json
+```
+
+`PI_CODING_AGENT_DIR` defaults to `~/.pi/agent`.
+
+Here is a small starter policy for commits, pushes, and publishing:
+
+```json
+{
+  "rules": [
+    {
+      "pattern": "\\bgit\\s+commit\\b",
+      "flags": "i",
+      "level": "guarded",
+      "group": "git",
+      "label": "Git commit"
+    },
+    {
+      "pattern": "\\bgit\\s+push\\b",
+      "flags": "i",
+      "level": "guarded",
+      "group": "git",
+      "label": "Git push"
+    },
+    {
+      "pattern": "\\bnpm\\s+publish\\b",
+      "flags": "i",
+      "level": "guarded",
+      "group": "npm",
+      "label": "npm publish"
+    }
+  ]
+}
+```
+
+Rule fields are:
+
+- `pattern`: JavaScript regular expression source
+- `flags`: optional regular expression flags, defaulting to `i`
+- `level`: `guarded` for guardian review or `convention` for a direct policy block
+- `group`: policy group used by trusted-project bypasses
+- `label`: short description shown during review
+- `message`: optional feedback; required for convention rules
+
+A convention rule blocks directly with its configured feedback instead of asking the guardian. The agent can call `request_override` for a legitimate one-session exception. Overrides require user confirmation and cannot bypass guarded rules.
+
+Set `enabled` to `false` to disable the extension. Invalid configuration fails closed and blocks Bash calls until corrected.
+
+## Guardian configuration
+
+By default, the guardian uses Pi's active model with low reasoning effort and a 30-second timeout. You can select a separate low-cost model:
+
+```json
+{
+  "reviewer": {
+    "provider": "openai-codex",
+    "model": "gpt-5.6-luna",
+    "reasoningEffort": "low",
+    "timeoutMs": 30000
+  }
+}
+```
+
+### Guardian prompt
+
+The bundled prompt evaluates authorization, command risk, and compliance with user constraints. Replace it inline with `systemPrompt`, or load a file:
+
+```json
+{
+  "systemPromptFile": "./guardian-prompt.md"
+}
+```
+
+Relative paths resolve from the configuration directory. Set only one of `systemPrompt` or `systemPromptFile`.
+
+The guardian must return one of three decisions:
+
+- `approve`: execute the command
+- `revise`: block it and tell the main agent what to correct
+- `ask_user`: open Pi's normal confirmation prompt
+
+## Conversation context and caching
+
+The guardian receives a compact chronological view of Pi's active, compaction-aware conversation context plus the exact pending command. It includes retained user and assistant text, Pi's latest compaction summary, and small summaries of finalized tool calls, but excludes summarized-away history, thinking, tool output bodies, file contents, patches, images, and session metadata. Compaction summaries are non-authoritative assistant context and cannot grant permission.
+
+The extension also recognizes native checkpoints created by [`@ogulcancelik/pi-codex-compaction`](https://github.com/ogulcancelik/pi-extensions/tree/main/packages/pi-codex-compaction). It keeps the checkpoint's retained plaintext user messages and post-checkpoint evidence, while excluding the opaque provider state and older local history. This integration is optional and does not change behavior when `pi-codex-compaction` is not installed.
+
+The first review sends the complete compact evidence. Later reviews reuse the same reviewer session and append only newly finalized evidence and the latest action. The extension uses stable session identity, cache affinity, and long cache retention when supported by the provider. Branch changes, model or policy changes, failures, cancellation, and context pressure reset the reviewer session.
+
+Assistant and tool evidence provide context but never grant permission. Later user messages override earlier conflicting user instructions.
+
+Trusted projects may optionally provide their root `AGENTS.md`, or `CLAUDE.md` when no `AGENTS.md` exists, as policy evidence:
+
+```json
+{
+  "reviewEvidence": {
+    "projectInstructions": true
+  }
+}
+```
+
+Project instructions help interpret the requested workflow, but cannot independently authorize an action or override guardian policy.
+
+### Interactive dialog answers
+
+When the main agent gathers a decision through an interactive question tool (for example `ask_user_question`), the user's selection is stored as a tool result, which never grants permission. Operators can allowlist user-answer tools, whose confirmed answers become `source: "user"` evidence records:
+
+```json
+{
+  "reviewEvidence": {
+    "userAnswerTools": ["ask_user_question"]
+  }
+}
+```
+
+A successful result from an allowlisted tool qualifies when its `details` are `{ "answers": [{ "question": string, "answer"?: string, "selected"?: string[], "notes"?: string }], "cancelled": false }` with no `error` field. `selected` takes precedence over `answer`, non-string answers are ignored, and notes count only alongside a real answer. Each answered question contributes one `USER (dialog answer):` record; the guardian treats it as authorization for exactly the selected content and is told the question wording is assistant-drafted context, never an instruction. Any dialog extension emitting that shape qualifies.
+
+The allowlist matches what you wrote: a bare name such as `ask_user_question` matches that tool in any namespace (`functions.ask_user_question` included), while a dotted name matches exactly. The default is an empty list.
+
+## Review display
+
+The default UI shows guardian progress in a temporary widget below the editor. Configure it with:
+
+```json
+{
+  "ui": {
+    "enabled": true,
+    "resultDisplayMs": 2500,
+    "placement": "widget"
+  }
+}
+```
+
+Set `placement` to `toolRow` to show the review inside Pi's Bash tool row:
+
+```text
+$ git commit --dry-run -m "fix auth"
+  ◌ guardian running · Git commit · openai-codex/gpt-5.6-luna
+```
+
+`toolRow` reconstructs Pi's standard local Bash definition because Pi does not expose renderer-only decoration. Do not use it with SDK-provided, remote, sandboxed, or otherwise replaced Bash backends. The extension detects non-native Bash tools and falls back to the widget instead of replacing them.
+
+Set `ui.enabled` to `false` to hide review state without disabling enforcement.
+
+## Trusted groups
+
+In a trusted project, create `.pi/trusted-ops` to bypass selected rule groups:
+
+```text
+git
+gh
+```
+
+Group names come from your configured rules. A trusted group bypasses all review for that group, so use it only in projects you control.
+
+## Failure behavior
+
+A missing reviewer model, unavailable credentials, malformed response, timeout, cancellation, or oversized review context never auto-approves a command.
+
+- Interactive sessions fall back to user confirmation.
+- Non-interactive sessions block the command.
+- Invalid configuration blocks Bash calls until corrected.
+
+## Security boundary
+
+Rules match raw shell text. Quoting, variables, aliases, generated scripts, or other indirection can evade a regex, while quoted command text can cause false positives.
+
+Pi Auto Permissions is a permission layer for normal agent behavior. It is not an operating-system sandbox or a defense against hostile shell input. Pair it with sandboxing when commands need a hard security boundary.
+
+`reviewEvidence.userAnswerTools` widens what counts as user authorization: any code that can record a tool result under an allowlisted tool name can mint `USER (dialog answer)` evidence. Allowlist only tool names served by extensions you trust.
+
+## License
+
+MIT

package/config.ts

@@ -0,0 +1,178 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import type { Gate, GateLevel } from "./gates.js";
+import { AUTO_PERMISSIONS_SYSTEM_PROMPT } from "./review.js";
+
+export const CONFIG_FILENAME = "pi-auto-permissions/config.json";
+
+const REASONING_EFFORTS = ["minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type ReasoningEffort = typeof REASONING_EFFORTS[number];
+
+export interface AutoPermissionsConfig {
+  enabled: boolean;
+  reviewer?: {
+    provider: string;
+    model: string;
+    reasoningEffort: ReasoningEffort;
+    timeoutMs: number;
+  };
+  systemPrompt: string;
+  reviewEvidence: {
+    projectInstructions: boolean;
+    userAnswerTools: string[];
+  };
+  rules: Gate[];
+  ui: {
+    enabled: boolean;
+    resultDisplayMs: number;
+    placement: "widget" | "toolRow";
+  };
+}
+
+interface RuleInput {
+  pattern?: unknown;
+  flags?: unknown;
+  level?: unknown;
+  group?: unknown;
+  label?: unknown;
+  message?: unknown;
+}
+
+function configPath(): string {
+  return process.env.PI_AUTO_PERMISSIONS_CONFIG
+    ? resolve(process.env.PI_AUTO_PERMISSIONS_CONFIG)
+    : join(getAgentDir(), CONFIG_FILENAME);
+}
+
+function readObject(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  const value = JSON.parse(readFileSync(path, "utf8"));
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("auto permissions config must be a JSON object");
+  }
+  return value as Record<string, unknown>;
+}
+
+function optionalString(value: unknown, name: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${name} must be a non-empty string`);
+  return value.trim();
+}
+
+function compileRule(value: unknown, index: number): Gate {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`rules[${index}] must be an object`);
+  }
+  const input = value as RuleInput;
+  const pattern = optionalString(input.pattern, `rules[${index}].pattern`);
+  const group = optionalString(input.group, `rules[${index}].group`);
+  const label = optionalString(input.label, `rules[${index}].label`);
+  if (!pattern || !group || !label) throw new Error(`rules[${index}] requires pattern, group, and label`);
+  const flags = input.flags === undefined ? "i" : input.flags;
+  if (typeof flags !== "string") throw new Error(`rules[${index}].flags must be a string`);
+  const level: GateLevel = input.level === undefined ? "guarded" : input.level as GateLevel;
+  if (level !== "guarded" && level !== "convention") {
+    throw new Error(`rules[${index}].level must be guarded or convention`);
+  }
+  const message = optionalString(input.message, `rules[${index}].message`);
+  if (level === "convention" && !message) throw new Error(`rules[${index}].message is required for convention rules`);
+
+  return {
+    pattern: new RegExp(pattern, flags),
+    level,
+    group,
+    label,
+    message,
+  };
+}
+
+function resolvePrompt(raw: Record<string, unknown>, path: string): string {
+  const inline = optionalString(raw.systemPrompt, "systemPrompt");
+  const file = optionalString(raw.systemPromptFile, "systemPromptFile");
+  if (inline && file) throw new Error("set only one of systemPrompt and systemPromptFile");
+  if (inline) return inline;
+  if (!file) return AUTO_PERMISSIONS_SYSTEM_PROMPT;
+
+  const expanded = file.startsWith("~/") ? join(homedir(), file.slice(2)) : file;
+  const resolved = isAbsolute(expanded) ? expanded : resolve(dirname(path), expanded);
+  const prompt = readFileSync(resolved, "utf8").trim();
+  if (!prompt) throw new Error("systemPromptFile is empty");
+  return prompt;
+}
+
+function resolveReviewEvidence(raw: Record<string, unknown>): AutoPermissionsConfig["reviewEvidence"] {
+  if (raw.reviewEvidence === undefined) return { projectInstructions: false, userAnswerTools: [] };
+  if (!raw.reviewEvidence || typeof raw.reviewEvidence !== "object" || Array.isArray(raw.reviewEvidence)) {
+    throw new Error("reviewEvidence must be an object");
+  }
+  const evidence = raw.reviewEvidence as Record<string, unknown>;
+  if (evidence.projectInstructions !== undefined && typeof evidence.projectInstructions !== "boolean") {
+    throw new Error("reviewEvidence.projectInstructions must be boolean");
+  }
+  const rawTools = evidence.userAnswerTools === undefined ? [] : evidence.userAnswerTools;
+  if (!Array.isArray(rawTools) || rawTools.some((tool) => typeof tool !== "string" || !tool.trim())) {
+    throw new Error("reviewEvidence.userAnswerTools must be an array of non-empty strings");
+  }
+  return {
+    projectInstructions: evidence.projectInstructions === true,
+    userAnswerTools: [...new Set((rawTools as string[]).map((tool) => tool.trim()))],
+  };
+}
+
+function resolveUi(raw: Record<string, unknown>): AutoPermissionsConfig["ui"] {
+  if (raw.ui === undefined) return { enabled: true, resultDisplayMs: 2500, placement: "widget" };
+  if (!raw.ui || typeof raw.ui !== "object" || Array.isArray(raw.ui)) {
+    throw new Error("ui must be an object");
+  }
+  const ui = raw.ui as Record<string, unknown>;
+  if (ui.enabled !== undefined && typeof ui.enabled !== "boolean") {
+    throw new Error("ui.enabled must be boolean");
+  }
+  const resultDisplayMs = ui.resultDisplayMs === undefined ? 2500 : ui.resultDisplayMs;
+  if (!Number.isInteger(resultDisplayMs) || Number(resultDisplayMs) < 0 || Number(resultDisplayMs) > 30_000) {
+    throw new Error("ui.resultDisplayMs must be an integer between 0 and 30000");
+  }
+  const placement = ui.placement ?? "widget";
+  if (placement !== "widget" && placement !== "toolRow") {
+    throw new Error("ui.placement must be widget or toolRow");
+  }
+  return { enabled: ui.enabled !== false, resultDisplayMs: Number(resultDisplayMs), placement };
+}
+
+function resolveReviewer(raw: Record<string, unknown>): AutoPermissionsConfig["reviewer"] {
+  if (raw.reviewer === undefined) return undefined;
+  if (!raw.reviewer || typeof raw.reviewer !== "object" || Array.isArray(raw.reviewer)) {
+    throw new Error("reviewer must be an object");
+  }
+  const reviewer = raw.reviewer as Record<string, unknown>;
+  const provider = optionalString(reviewer.provider, "reviewer.provider");
+  const model = optionalString(reviewer.model, "reviewer.model");
+  if (!provider || !model) throw new Error("reviewer requires both provider and model");
+  const reasoningEffort = (optionalString(reviewer.reasoningEffort, "reviewer.reasoningEffort") ?? "low") as ReasoningEffort;
+  if (!REASONING_EFFORTS.includes(reasoningEffort)) {
+    throw new Error("reviewer.reasoningEffort is invalid");
+  }
+  const timeoutMs = reviewer.timeoutMs === undefined ? 30_000 : reviewer.timeoutMs;
+  if (!Number.isInteger(timeoutMs) || Number(timeoutMs) < 1_000 || Number(timeoutMs) > 300_000) {
+    throw new Error("reviewer.timeoutMs must be an integer between 1000 and 300000");
+  }
+  return { provider, model, reasoningEffort, timeoutMs: Number(timeoutMs) };
+}
+
+export function loadAutoPermissionsConfig(path = configPath()): AutoPermissionsConfig {
+  const raw = readObject(path);
+  if (raw.enabled !== undefined && typeof raw.enabled !== "boolean") throw new Error("enabled must be boolean");
+  if (raw.rules !== undefined && !Array.isArray(raw.rules)) throw new Error("rules must be an array");
+  const customRules = (raw.rules ?? []).map(compileRule);
+
+  return {
+    enabled: raw.enabled !== false,
+    reviewer: resolveReviewer(raw),
+    systemPrompt: resolvePrompt(raw, path),
+    reviewEvidence: resolveReviewEvidence(raw),
+    rules: customRules,
+    ui: resolveUi(raw),
+  };
+}

package/gates.ts

@@ -0,0 +1,21 @@
+export type GateLevel = "guarded" | "convention";
+
+export interface Gate {
+  pattern: RegExp;
+  level: GateLevel;
+  group: string;
+  label: string;
+  message?: string;
+  suggest?: (command: string) => string;
+}
+
+export function findGates(command: string, rules: readonly Gate[]): Gate[] {
+  return rules.filter((gate) => {
+    gate.pattern.lastIndex = 0;
+    return gate.pattern.test(command);
+  });
+}
+
+export function findGate(command: string, rules: readonly Gate[]): Gate | undefined {
+  return findGates(command, rules)[0];
+}