@gotgenes/pi-permission-system 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.1](https://github.com/gotgenes/pi-permission-system/compare/v3.0.0...v3.0.1) (2026-05-03)
+
+
+### Documentation
+
+* add descriptions to all JSON schema entities ([cb3a7ce](https://github.com/gotgenes/pi-permission-system/commit/cb3a7ce5257111159312ebb95a9f75dd4e4a9527))
+* enrich JSON schema with examples, defaults, and markdown descriptions ([6f38d7e](https://github.com/gotgenes/pi-permission-system/commit/6f38d7edf01b950f20e2fab8604a398bf725a6c4))
+* plan index.ts split into focused modules ([#21](https://github.com/gotgenes/pi-permission-system/issues/21)) ([ccd736a](https://github.com/gotgenes/pi-permission-system/commit/ccd736a83a4af208044eec925c80555ee645e344))
+* **retro:** add retro notes for issue [#10](https://github.com/gotgenes/pi-permission-system/issues/10) ([31e59d6](https://github.com/gotgenes/pi-permission-system/commit/31e59d6172da7b0e9f02894afd2ba66a292de168))
+* **retro:** correct formatting friction attribution ([#10](https://github.com/gotgenes/pi-permission-system/issues/10)) ([2e96b7b](https://github.com/gotgenes/pi-permission-system/commit/2e96b7bc1007a2ef55f95b29c40b8417c2c6c52f))
+* update plan with Phase 2 unit tests using DI and vitest mocks ([#21](https://github.com/gotgenes/pi-permission-system/issues/21)) ([ad7f5fe](https://github.com/gotgenes/pi-permission-system/commit/ad7f5feeb856c84142a2a4258a9e173c8006532d))
+
 ## [3.0.0](https://github.com/gotgenes/pi-permission-system/compare/v2.0.0...v3.0.0) (2026-05-03)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "main": "./index.ts",

package/schemas/permissions.schema.json

@@ -3,70 +3,138 @@
   "$id": "https://raw.githubusercontent.com/gotgenes/pi-permission-system/main/schemas/permissions.schema.json",
   "title": "PI Permission System Configuration",
   "description": "Unified config file combining runtime knobs and permission policy for pi-permission-system.",
+  "markdownDescription": "Unified config file combining runtime knobs and permission policy for [pi-permission-system](https://github.com/gotgenes/pi-permission-system).\n\nPlace at `~/.pi/agent/extensions/pi-permission-system/config.json` (global) or `<project>/.pi/extensions/pi-permission-system/config.json` (project).",
   "type": "object",
   "additionalProperties": false,
   "properties": {
     "$schema": {
+      "description": "JSON Schema URI for editor autocomplete and validation.",
       "type": "string"
     },
     "debugLog": {
       "description": "Write verbose permission-system diagnostics to the extension logs directory.",
+      "markdownDescription": "Write verbose permission-system diagnostics to `logs/pi-permission-system-debug.jsonl` under the extension config directory.",
       "type": "boolean",
       "default": false
     },
     "permissionReviewLog": {
       "description": "Write permission request and decision audit events to the extension logs directory.",
+      "markdownDescription": "Write permission request and decision audit events to `logs/pi-permission-system-permission-review.jsonl` under the extension config directory.",
       "type": "boolean",
       "default": true
     },
     "yoloMode": {
       "description": "Auto-approve ask-state permission checks, including subagent approval forwarding.",
+      "markdownDescription": "Auto-approve `ask`-state permission checks, including subagent approval forwarding.\n\n⚠️ **Use with caution** — this disables all interactive confirmation prompts.",
       "type": "boolean",
       "default": false
     },
     "defaultPolicy": {
+      "description": "Fallback permission state per category when no specific rule matches.",
+      "markdownDescription": "Fallback permission state per category when no specific rule matches.\n\nAll fields default to `\"ask\"` when omitted.",
       "type": "object",
       "additionalProperties": false,
       "properties": {
         "tools": {
-          "$ref": "#/$defs/permissionState"
+          "description": "Default permission for registered tools when no exact-name rule matches in the tools map.",
+          "markdownDescription": "Default permission for registered tools when no exact-name rule matches in the `tools` map.",
+          "$ref": "#/$defs/permissionState",
+          "default": "ask"
         },
         "bash": {
-          "$ref": "#/$defs/permissionState"
+          "description": "Default permission for bash commands when no pattern in the bash map matches.",
+          "markdownDescription": "Default permission for bash commands when no pattern in the `bash` map matches.",
+          "$ref": "#/$defs/permissionState",
+          "default": "ask"
         },
         "mcp": {
-          "$ref": "#/$defs/permissionState"
+          "description": "Default permission for MCP operations when no target pattern in the mcp map matches.",
+          "markdownDescription": "Default permission for MCP operations when no target pattern in the `mcp` map matches.",
+          "$ref": "#/$defs/permissionState",
+          "default": "ask"
         },
         "skills": {
-          "$ref": "#/$defs/permissionState"
+          "description": "Default permission for skill loading when no pattern in the skills map matches.",
+          "markdownDescription": "Default permission for skill loading when no pattern in the `skills` map matches.",
+          "$ref": "#/$defs/permissionState",
+          "default": "ask"
         },
         "special": {
-          "$ref": "#/$defs/permissionState"
+          "description": "Default permission for special checks (doom_loop, external_directory) when no explicit rule matches.",
+          "markdownDescription": "Default permission for special checks (`doom_loop`, `external_directory`) when no explicit rule matches.",
+          "$ref": "#/$defs/permissionState",
+          "default": "ask"
         }
       }
     },
     "tools": {
       "description": "Exact-name permissions for registered tools. Use this map for the canonical Pi built-ins and any extension-provided or third-party tools.",
-      "$ref": "#/$defs/permissionMap"
+      "markdownDescription": "Exact-name permissions for registered tools. Use this map for the canonical Pi built-ins (`read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`) and any extension-provided or third-party tools.\n\nNo wildcards — keys must match the registered tool name exactly.",
+      "$ref": "#/$defs/permissionMap",
+      "examples": [
+        {
+          "read": "allow",
+          "write": "deny",
+          "edit": "ask",
+          "mcp": "allow"
+        }
+      ]
     },
     "bash": {
-      "$ref": "#/$defs/permissionMap"
+      "description": "Wildcard pattern permissions for bash commands. Patterns use * globs matched against the full command string. Last matching rule wins.",
+      "markdownDescription": "Wildcard pattern permissions for bash commands. Patterns use `*` globs matched against the full command string.\n\n**Last matching rule wins** — put broad catch-all rules first and specific overrides after them.",
+      "$ref": "#/$defs/permissionMap",
+      "examples": [
+        {
+          "git status": "allow",
+          "git diff": "allow",
+          "git *": "ask",
+          "rm -rf *": "deny"
+        }
+      ]
     },
     "mcp": {
-      "description": "Pattern-based permissions for targets invoked through a registered `mcp` tool when available.",
-      "$ref": "#/$defs/permissionMap"
+      "description": "Pattern-based permissions for targets invoked through a registered mcp tool when available.",
+      "markdownDescription": "Pattern-based permissions for targets invoked through a registered `mcp` tool when available.\n\nTargets include server names (`myServer`), qualified tool names (`myServer:search`, `myServer_search`), and baseline operations (`mcp_status`, `mcp_list`, `mcp_connect`, `mcp_describe`, `mcp_search`).",
+      "$ref": "#/$defs/permissionMap",
+      "examples": [
+        {
+          "mcp_status": "allow",
+          "mcp_list": "allow",
+          "myServer:*": "ask",
+          "dangerousServer": "deny"
+        }
+      ]
     },
     "skills": {
-      "$ref": "#/$defs/permissionMap"
+      "description": "Wildcard pattern permissions for skill names. Controls which skills can be loaded or read from disk.",
+      "markdownDescription": "Wildcard pattern permissions for skill names. Controls which skills can be loaded or read from disk.\n\nUse `\"*\": \"ask\"` to require confirmation for all skills, or `\"dangerous-*\": \"deny\"` to block a family of skills.",
+      "$ref": "#/$defs/permissionMap",
+      "examples": [
+        {
+          "*": "ask",
+          "dangerous-*": "deny"
+        }
+      ]
     },
     "special": {
+      "description": "Reserved permission checks for special runtime behaviors.",
       "type": "object",
       "additionalProperties": false,
       "properties": {
         "doom_loop": {
+          "description": "Controls doom loop detection behavior.",
           "$ref": "#/$defs/permissionState"
         },
         "external_directory": {
+          "description": "Enforces permission checks for path-bearing file tools (read, write, edit, find, grep, ls) when they target paths outside the active working directory.",
+          "markdownDescription": "Enforces permission checks for path-bearing file tools (`read`, `write`, `edit`, `find`, `grep`, `ls`) when they target paths outside the active working directory.\n\nEvaluated **before** the normal tool permission check — so `tools.read: \"allow\"` can permit ordinary reads while `external_directory: \"ask\"` still requires confirmation for paths outside `cwd`.",
+          "$ref": "#/$defs/permissionState"
+        },
+        "tool_call_limit": {
+          "description": "Deprecated and ignored. This key has no effect and should be removed from your config.",
+          "markdownDescription": "⚠️ **Deprecated and ignored.** This key has no effect and should be removed from your config.",
+          "deprecated": true,
           "$ref": "#/$defs/permissionState"
         }
       }
@@ -74,12 +142,28 @@
   },
   "$defs": {
     "permissionState": {
-      "type": "string",
-      "enum": ["allow", "deny", "ask"]
+      "description": "A permission decision: allow (permit silently), deny (block with error), or ask (prompt the user for confirmation).",
+      "oneOf": [
+        {
+          "const": "allow",
+          "description": "Permit the action silently with no user interaction."
+        },
+        {
+          "const": "deny",
+          "description": "Block the action with an error message. The agent is told not to retry."
+        },
+        {
+          "const": "ask",
+          "description": "Prompt the user for confirmation via the interactive UI before proceeding."
+        }
+      ]
     },
     "permissionMap": {
+      "description": "A map of name or wildcard patterns to permission states. Keys are matched against the relevant target (tool name, bash command, MCP target, or skill name).",
+      "markdownDescription": "A map of name or wildcard patterns to permission states.\n\nKeys are matched against the relevant target. Use `*` for wildcard matching. When multiple patterns match, the **last matching rule wins**.",
       "type": "object",
       "propertyNames": {
+        "description": "A non-empty pattern string. Use * for wildcard matching.",
         "type": "string",
         "minLength": 1
       },

package/src/active-agent.ts

@@ -0,0 +1,58 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Matches the `<active_agent name="...">` tag injected by pi-agent-router
+ * into the system prompt to identify which agent definition is active.
+ */
+export const ACTIVE_AGENT_TAG_REGEX =
+  /<active_agent\s+name=["']([^"']+)["'][^>]*>/i;
+
+export function normalizeAgentName(value: unknown): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+export function getActiveAgentName(ctx: ExtensionContext): string | null {
+  const entries = ctx.sessionManager.getEntries();
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i] as {
+      type: string;
+      customType?: string;
+      data?: unknown;
+    };
+    if (entry.type !== "custom" || entry.customType !== "active_agent") {
+      continue;
+    }
+
+    const data = entry.data as { name?: unknown } | undefined;
+    const normalizedName = normalizeAgentName(data?.name);
+    if (normalizedName) {
+      return normalizedName;
+    }
+
+    if (data?.name === null) {
+      return null;
+    }
+  }
+
+  return null;
+}
+
+export function getActiveAgentNameFromSystemPrompt(
+  systemPrompt: string | undefined,
+): string | null {
+  if (!systemPrompt) {
+    return null;
+  }
+
+  const match = systemPrompt.match(ACTIVE_AGENT_TAG_REGEX);
+  if (!match?.[1]) {
+    return null;
+  }
+
+  return normalizeAgentName(match[1]);
+}

package/src/external-directory.ts

@@ -0,0 +1,113 @@
+import { homedir } from "node:os";
+import { join, normalize, resolve, sep } from "node:path";
+
+import { getNonEmptyString, toRecord } from "./common.js";
+
+export const PATH_BEARING_TOOLS = new Set([
+  "read",
+  "write",
+  "edit",
+  "find",
+  "grep",
+  "ls",
+]);
+
+export function normalizePathForComparison(
+  pathValue: string,
+  cwd: string,
+): string {
+  const trimmed = pathValue.trim().replace(/^['"]|['"]$/g, "");
+  if (!trimmed) {
+    return "";
+  }
+
+  let normalizedPath = trimmed.startsWith("@") ? trimmed.slice(1) : trimmed;
+
+  if (normalizedPath === "~") {
+    normalizedPath = homedir();
+  } else if (
+    normalizedPath.startsWith("~/") ||
+    normalizedPath.startsWith("~\\")
+  ) {
+    normalizedPath = join(homedir(), normalizedPath.slice(2));
+  }
+
+  const absolutePath = resolve(cwd, normalizedPath);
+  const normalizedAbsolutePath = normalize(absolutePath);
+  return process.platform === "win32"
+    ? normalizedAbsolutePath.toLowerCase()
+    : normalizedAbsolutePath;
+}
+
+export function isPathWithinDirectory(
+  pathValue: string,
+  directory: string,
+): boolean {
+  if (!pathValue || !directory) {
+    return false;
+  }
+
+  if (pathValue === directory) {
+    return true;
+  }
+
+  const prefix = directory.endsWith(sep) ? directory : `${directory}${sep}`;
+  return pathValue.startsWith(prefix);
+}
+
+export function getPathBearingToolPath(
+  toolName: string,
+  input: unknown,
+): string | null {
+  if (!PATH_BEARING_TOOLS.has(toolName)) {
+    return null;
+  }
+
+  return getNonEmptyString(toRecord(input).path);
+}
+
+export function isPathOutsideWorkingDirectory(
+  pathValue: string,
+  cwd: string,
+): boolean {
+  const normalizedCwd = normalizePathForComparison(cwd, cwd);
+  const normalizedPath = normalizePathForComparison(pathValue, cwd);
+  return Boolean(
+    normalizedCwd &&
+      normalizedPath &&
+      !isPathWithinDirectory(normalizedPath, normalizedCwd),
+  );
+}
+
+export function formatExternalDirectoryHardStopHint(): string {
+  return "Hard stop: this external directory permission denial is policy-enforced. Do not retry this path, do not attempt a filesystem bypass, and report the block to the user.";
+}
+
+export function formatExternalDirectoryAskPrompt(
+  toolName: string,
+  pathValue: string,
+  cwd: string,
+  agentName?: string,
+): string {
+  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
+  return `${subject} requested tool '${toolName}' for path '${pathValue}' outside working directory '${cwd}'. Allow this external directory access?`;
+}
+
+export function formatExternalDirectoryDenyReason(
+  toolName: string,
+  pathValue: string,
+  cwd: string,
+  agentName?: string,
+): string {
+  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
+  return `${subject} is not permitted to run tool '${toolName}' for path '${pathValue}' outside working directory '${cwd}'. ${formatExternalDirectoryHardStopHint()}`;
+}
+
+export function formatExternalDirectoryUserDeniedReason(
+  toolName: string,
+  pathValue: string,
+  denialReason?: string,
+): string {
+  const reasonSuffix = denialReason ? ` Reason: ${denialReason}.` : "";
+  return `User denied external directory access for tool '${toolName}' path '${pathValue}'.${reasonSuffix} ${formatExternalDirectoryHardStopHint()}`;
+}