@davisliu2006/pi-permission-system 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davis Liu
+
+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/README.md

@@ -1,3 +1,129 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# pi-permission-system
+
+Permissions management for the `pi` coding agent.
+
+Roughly based on [MasuRii/pi-permission-system](https://github.com/MasuRii/pi-permission-system).
+
+
+## Permissions Overview
+
+A permission can be one of the following:
+
+```jsonc
+"allow"  // allows the action
+"ask"  // asks the user for permission
+"deny"  // automatically denies the action
+```
+
+Ask states the purpose of the request and gives the following options:
+
+```
+Allow Once
+Allow Always
+Reject
+```
+
+"Reject" stops the current agent task and asks the user what to do next.
+
+"Allow always" is persisted for the session only. It uses an AI-generated command wildcard for `bash` and an exact match for other tools.
+
+## Configuration
+
+The supported top-level keys are: `default`, `tools`, `bash`, and `external_directory`.
+
+`bash` body matching supports wildcard:
+- `*` matches any sequence and `?` matches one character
+- `\*` and `\?` are match literal `*` and `?`
+
+`tools` matches exact tool names.
+
+The builtin path tools in pi are: `read`, `write`, `edit`, `find`, `grep`, `ls`. `external_directory` overrides the settings for these path tools. The primary use is to override `write` and `edit` to a stronger policy for external directories.
+
+### Rule Precedence
+
+More specific rules override less specific rules:
+
+- `tools.*` overrides `default`
+- `bash.*` overrides `tools.bash`
+- Within `bash`, the last match wins
+
+### Global Configuration
+
+Located in `~/.pi/agent/pi-permissions.jsonc`.
+
+Example:
+
+```jsonc
+{
+    "default": "ask",
+    "tools": {
+        "read": "allow",
+        "write": "allow",
+        "edit": "allow",
+        "find": "allow",
+        "grep": "allow",
+        "ls": "allow",
+        "bash": "ask",
+
+        // add any non builtin tools
+        "mcp": "ask"
+    },
+    "bash": {
+        "git status*": "allow",
+        "git log*": "allow",
+        "git diff*": "allow",
+        "git branch*": "allow",
+        "git show*": "allow",
+
+        "ls*": "allow",
+        "pwd": "allow",
+        "find*": "allow",
+        "tree*": "allow",
+        "cat*": "allow",
+        "head*": "allow",
+        "tail*": "allow",
+        "wc*": "allow",
+        "echo*": "allow",
+        "sed*": "allow",
+
+        "grep*": "allow",
+        "rg*": "allow"
+    },
+    "external_directory": {
+        "write": "ask"
+    }
+}
+```
+
+### Local Configuration
+
+Located in the local Pi config folder:
+
+`<project-root>/.pi/pi-permissions.jsonc`
+
+Local configuration overrides global configuration, including `deny` rules.
+
+## "Allow Always" Matching
+
+Matching is done as `(tool, body)`.
+
+Body content:
+
+- For built-in path tools, it is the path
+- For bash, it is the command
+- For other tools, it is a stable JSON serialization of the full input
+
+Body matching rules:
+
+- For non-bash, it is exact match
+- Bash supports wildcard matching
+
+## Bash Matching Safeguards
+
+Bash matching safeguards against unsafe shell syntax.
+
+Simple sequences separated only by `;`, `&&`, `||`, or newlines are split and each segment is matched against `bash` rules. The strictest result wins (`deny` > `ask` > `allow`).
+
+If a command contains other chaining or control syntax (`|`, `&`, command substitution, process substitution, or parentheses), `bash` pattern rules are skipped and the `tools.bash` policy is used instead, falling back to `default`.
+
+"Allow always" for complex or multi-command sequences saves the exact command, not a wildcard.

package/index.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerPermissionSystem } from "./src/extension.ts";
+
+export default function piPermissionSystem(pi: ExtensionAPI): void {
+  registerPermissionSystem(pi);
+}

package/package.json

@@ -1,6 +1,52 @@
-{
-  "name": "@davisliu2006/pi-permission-system",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@davisliu2006/pi-permission-system",
+  "version": "0.2.0",
+  "description": "Permission enforcement extension for the Pi coding agent.",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test tests/*.test.ts",
+    "check": "npm run typecheck && npm test"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "permissions"
+  ],
+  "author": "davisliu2006",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/davisliu2006/pi-permission-system.git"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.78.0",
+    "@earendil-works/pi-coding-agent": ">=0.78.0",
+    "@earendil-works/pi-tui": ">=0.78.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-tui": "^0.78.1",
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3"
+  }
+}

package/src/ai-gen.ts

@@ -0,0 +1,79 @@
+import { complete, type Message } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export interface CompleteTextOptions {
+  systemPrompt: string;
+  userText: string;
+  maxTokens: number;
+  timeoutMs: number;
+  /** How to join multiple text blocks. Defaults to a single space. */
+  joinWith?: string;
+}
+
+/**
+ * Signal sent ot the model to abort if the request takes too long.
+ */
+function timeoutSignal(signal: AbortSignal | undefined, timeoutMs: number): AbortSignal {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  if (!signal) {return timeout;}
+  if (typeof AbortSignal.any === "function") {
+    return AbortSignal.any([signal, timeout]);
+  }
+  return timeout;
+}
+
+/**
+ * Runs a single-turn text completion against the extension model.
+ * Returns undefined when the model/auth is unavailable, the call aborts, or no text is returned.
+ */
+export async function completeText(
+  ctx: ExtensionContext,
+  options: CompleteTextOptions
+): Promise<string | undefined> {
+  if (!ctx.model) {return undefined;}
+
+  try {
+    const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
+    if (!auth.ok || !auth.apiKey) {return undefined;}
+
+    // prompt
+    const message: Message = {
+      role: "user",
+      timestamp: Date.now(),
+      content: [
+        {
+          type: "text",
+          text: options.userText,
+        },
+      ],
+    };
+
+    // call model
+    const response = await complete(
+      ctx.model,
+      {
+        systemPrompt: options.systemPrompt,
+        messages: [message],
+      },
+      {
+        apiKey: auth.apiKey,
+        headers: auth.headers,
+        maxTokens: options.maxTokens,
+        signal: timeoutSignal(ctx.signal, options.timeoutMs),
+      }
+    );
+
+    if (response.stopReason === "aborted") {return undefined;}
+
+    // extract text
+    const text = response.content
+      .filter((content): content is { type: "text"; text: string } => content.type === "text")
+      .map((content) => content.text)
+      .join(options.joinWith ?? " ")
+      .trim();
+
+    return text || undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/ai-purpose.ts

@@ -0,0 +1,68 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { completeText } from "./ai-gen.ts";
+import { buildPurposeInstructions, PURPOSE_SYSTEM_PROMPT } from "./prompts.ts";
+import type { PermissionRequest } from "./types.ts";
+
+const PURPOSE_TIMEOUT_MS = 5000;
+const MAX_PURPOSE_LENGTH = 200;
+const MAX_PURPOSE_TOKENS = 120;
+
+const purposeCache = new Map<string, string>();
+
+function cacheKey(request: PermissionRequest): string {
+  return `${request.toolName}\u0000${request.body}`;
+}
+
+/**
+ * Sanitizes against:
+ * - ANSI terminal escapes
+ * - Code blocks, markdown formatting characters, quotes
+ * - Consecutive whitespace
+ */
+function sanitizePurpose(value: string): string | undefined {
+  const normalized = value
+    .replace(/\u001b\[[0-9;]*m/g, "")
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/[`*_#>]/g, "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/^["'“”‘’]+|["'“”‘’]+$/g, "")
+    .trim();
+
+  if (!normalized) {return undefined;}
+  return normalized.length > MAX_PURPOSE_LENGTH
+    ? `${normalized.slice(0, MAX_PURPOSE_LENGTH)}...`
+    : normalized;
+}
+
+/**
+ * Generates a request purpose, using the cached version if it exists.
+ */
+export async function generateRequestPurpose(
+  ctx: ExtensionContext,
+  request: PermissionRequest,
+  context: string
+): Promise<string | undefined> {
+  const key = cacheKey(request);
+  const cached = purposeCache.get(key);
+  if (cached) {return cached;}
+
+  const text = await completeText(ctx, {
+    systemPrompt: PURPOSE_SYSTEM_PROMPT,
+    userText: buildPurposeInstructions(context),
+    maxTokens: MAX_PURPOSE_TOKENS,
+    timeoutMs: PURPOSE_TIMEOUT_MS,
+  });
+  if (!text) {return undefined;}
+
+  const purpose = sanitizePurpose(text);
+  if (purpose) {purposeCache.set(key, purpose);}
+  return purpose;
+}
+
+/**
+ * Clears the generated purpose cache.
+ */
+export function clearPurposeCache(): void {
+  purposeCache.clear();
+}

package/src/ai-wildcard.ts

@@ -0,0 +1,88 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { completeText } from "./ai-gen.ts";
+import {
+  buildWildcardInstructions,
+  buildWildcardListInstructions,
+  WILDCARD_LIST_SYSTEM_PROMPT,
+  WILDCARD_SYSTEM_PROMPT,
+} from "./prompts.ts";
+import {
+  validateWildcardSuggestion,
+  validateWildcardSuggestionList,
+} from "./wildcard-validation.ts";
+
+const WILDCARD_TIMEOUT_MS = 8000;
+const MAX_WILDCARD_TOKENS = 120;
+const MAX_WILDCARD_LIST_TOKENS = 240;
+
+/**
+ * Sanitizes against:
+ * - ANSI terminal escapes
+ * - Code blocks, quotes, backticks
+ * - Consecutive whitespace
+ */
+function sanitizeWildcard(value: string): string | undefined {
+  const normalized = value
+    .replace(/\u001b\[[0-9;]*m/g, "")
+    .replace(/```(?:\w*\n)?([\s\S]*?)```/g, "$1")
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/^["'`]+|["'`]+$/g, "")
+    .trim();
+
+  if (!normalized) {return undefined;}
+  return normalized;
+}
+
+/**
+ * Generates one bash wildcard recommendation.
+ */
+export async function generateBashWildcard(
+  ctx: ExtensionContext,
+  command: string
+): Promise<string | undefined> {
+  const text = await completeText(ctx, {
+    systemPrompt: WILDCARD_SYSTEM_PROMPT,
+    userText: buildWildcardInstructions(command),
+    maxTokens: MAX_WILDCARD_TOKENS,
+    timeoutMs: WILDCARD_TIMEOUT_MS,
+    joinWith: "\n",
+  });
+  if (!text) {return undefined;}
+
+  const pattern = sanitizeWildcard(text);
+  if (!pattern) {return undefined;}
+
+  const validation = validateWildcardSuggestion(pattern, command);
+  if (!validation.valid) {return undefined;}
+
+  return pattern;
+}
+
+/**
+ * Generates a list of bash wildcards.
+ * Expects semicolon-separated patterns back.
+ */
+export async function generateBashWildcards(
+  ctx: ExtensionContext,
+  commands: readonly string[]
+): Promise<string[] | undefined> {
+  if (commands.length === 0) {return undefined;}
+
+  const text = await completeText(ctx, {
+    systemPrompt: WILDCARD_LIST_SYSTEM_PROMPT,
+    userText: buildWildcardListInstructions(commands),
+    maxTokens: MAX_WILDCARD_LIST_TOKENS,
+    timeoutMs: WILDCARD_TIMEOUT_MS,
+    joinWith: "\n",
+  });
+  if (!text) {return undefined;}
+
+  const sanitized = sanitizeWildcard(text);
+  if (!sanitized) {return undefined;}
+
+  const validation = validateWildcardSuggestionList(sanitized, commands);
+  if (!validation.valid) {return undefined;}
+
+  return validation.patterns;
+}

package/src/config.ts

@@ -0,0 +1,187 @@
+import { readFile } from "node:fs/promises";
+import { ASK } from "./constants.ts";
+import { parseJsonc } from "./jsonc.ts";
+import {
+  createDefaultPermissionConfig,
+  toPermissionState,
+  toRecord,
+  type ConfigWarning,
+  type PermissionConfig,
+  type PermissionSection,
+  type PermissionState,
+} from "./types.ts";
+import {
+  CONFIG_MUST_BE_OBJECT,
+  formatConfigParseFailure,
+  formatConfigReadFailure,
+  formatIgnoredSectionEntryWarning,
+  formatIgnoredSectionWarning,
+  IGNORED_DEFAULT_WARNING,
+} from "./warning-strings.ts";
+
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+/**
+ * Helper used by normalizeConfig.
+ * Ensures section is a valid PermissionSection.
+ */
+function normalizeSection(
+  raw: unknown,
+  sectionName: string,
+  configPath: string | undefined,
+  warnings: ConfigWarning[]
+): PermissionSection {
+  if (raw === undefined) {return {};}
+  const record = toRecord(raw);
+  if (!record) {
+    warnings.push({
+      path: configPath,
+      message: formatIgnoredSectionWarning(sectionName),
+    });
+    return {};
+  }
+
+  const result: PermissionSection = {};
+  for (const [key, entry] of Object.entries(record)) {
+    if (UNSAFE_KEYS.has(key)) {continue;}
+    const state = toPermissionState(entry);
+    if (state !== undefined) {
+      result[key] = state;
+    } else {
+      warnings.push({
+        path: configPath,
+        message: formatIgnoredSectionEntryWarning(sectionName, key),
+      });
+    }
+  }
+  return result;
+}
+
+/**
+ * Convert the raw config to a PermissionConfig.
+ * Ensures the config is valid.
+ */
+function normalizeConfig(
+  rawConfig: unknown,
+  configPath: string | undefined,
+  warnings: ConfigWarning[]
+): PermissionConfig {
+  const config = toRecord(rawConfig);
+  if (!config) {
+    warnings.push({
+      path: configPath,
+      message: CONFIG_MUST_BE_OBJECT,
+    });
+    return createDefaultPermissionConfig();
+  }
+
+  const parsedDefault = toPermissionState(config.default);
+  if (config.default !== undefined && parsedDefault === undefined) {
+    warnings.push({
+      path: configPath,
+      message: IGNORED_DEFAULT_WARNING,
+    });
+  }
+  const defaultState = parsedDefault ?? ASK;
+
+  return {
+    default: defaultState,
+    tools: normalizeSection(config.tools, "tools", configPath, warnings),
+    bash: normalizeSection(config.bash, "bash", configPath, warnings),
+    external_directory: normalizeSection(
+      config.external_directory,
+      "external_directory",
+      configPath,
+      warnings
+    ),
+  };
+}
+
+/**
+ * Loads the config file and appends to the list of warnings.
+ */
+async function loadConfigFile(
+  path: string,
+  warnings: ConfigWarning[]
+): Promise<PermissionConfig | undefined> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") {return undefined;} // file does not exist
+    warnings.push({
+      path,
+      message: formatConfigReadFailure(error),
+    });
+    return undefined;
+  }
+
+  try {
+    return normalizeConfig(parseJsonc(raw), path, warnings);
+  } catch (error) {
+    warnings.push({
+      path,
+      message: formatConfigParseFailure(error),
+    });
+    return undefined;
+  }
+}
+
+/**
+ * Local overrides global, preserves order.
+ */
+function mergeBashSections(
+  globalSection: PermissionSection,
+  localSection: PermissionSection
+): PermissionSection {
+  const merged = new Map<string, PermissionState>();
+  for (const [pattern, state] of Object.entries(globalSection)) {
+    merged.set(pattern, state);
+  }
+  for (const [pattern, state] of Object.entries(localSection)) {
+    merged.delete(pattern);
+    merged.set(pattern, state);
+  }
+  return Object.fromEntries(merged);
+}
+
+/**
+ * Merges configs such that local config overrides global config.
+ */
+export function mergeConfigs(
+  globalConfig: PermissionConfig | undefined,
+  localConfig: PermissionConfig | undefined
+): PermissionConfig {
+  if (!globalConfig && !localConfig) {
+    return createDefaultPermissionConfig();
+  }
+
+  globalConfig = globalConfig ?? createDefaultPermissionConfig();
+
+  return {
+    default: localConfig?.default ?? globalConfig.default,
+    tools: { ...globalConfig.tools, ...(localConfig?.tools ?? {}) },
+    bash: mergeBashSections(globalConfig.bash, localConfig?.bash ?? {}),
+    external_directory: {
+      ...globalConfig.external_directory,
+      ...(localConfig?.external_directory ?? {}),
+    },
+  };
+}
+
+/**
+ * Loads merged config where local overrides global.
+ */
+export async function loadMergedConfig(
+  globalPath: string,
+  localPath: string
+): Promise<{ config: PermissionConfig; warnings: ConfigWarning[] }> {
+  const warnings: ConfigWarning[] = [];
+  const globalConfig = await loadConfigFile(globalPath, warnings);
+  const localConfig = await loadConfigFile(localPath, warnings);
+  return {
+    config: mergeConfigs(globalConfig, localConfig),
+    warnings,
+  };
+}

package/src/constants.ts

@@ -0,0 +1,18 @@
+export const EXTENSION_NAME = "pi-permission-system";
+export const STATUS_KEY = EXTENSION_NAME;
+export const MAX_CONFIG_WARNINGS = 5;
+
+export const CONFIG_FILENAME = "pi-permissions.jsonc";
+/** Local config directory under the cwd. */
+export const LOCAL_CONFIG_DIR_SEGMENTS = [".pi"] as const;
+
+export const ALLOW = "allow";
+export const ASK = "ask";
+export const DENY = "deny";
+export const PERMISSION_STATES = [ALLOW, ASK, DENY] as const;
+export const PERMISSION_STATES_DESCRIPTION = "allow, ask, or deny";
+
+export const ALLOW_ONCE = "Allow Once";
+export const ALLOW_ALWAYS_EXACT = "Allow Always (exact match)";
+export const ALLOW_ALWAYS_WILDCARD = "Allow Always (generate wildcard)";
+export const REJECT = "Reject";