pi-permission-system 0.4.8 → 0.4.9

package/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.9] - 2026-05-05
+
+### Changed
+- Permission-system config parsing now accepts JSONC comments and trailing commas across both policy files and the extension config, and invalid config warnings are emitted once per session as a compact single-line message with explicit fallback behavior.
+
+### Fixed
+- Stopped repeating identical invalid-config warnings in the TUI when the same broken permission policy is re-evaluated during the same session or reload cycle (thanks to @jviel-beta for issue #20).
+
 ## [0.4.8] - 2026-05-04
 
 ### Added

package/README.md

@@ -246,7 +246,7 @@ The policy file is a JSON object with these sections:
 | `skills`        | Skill name pattern permissions                      |
 | `special`       | Reserved permission checks such as external directory access |
 
-> **Note:** Trailing commas are **not** supported. If parsing fails, the extension falls back to `ask` for all categories.
+> **Note:** JSONC comments and trailing commas are supported. If parsing still fails, the extension falls back to `ask` for all categories and shows a warning in the TUI when available.
 
 ### Global Per-Agent Overrides
 
@@ -637,7 +637,7 @@ npx --yes ajv-cli@5 validate \
 
 | Problem | Cause | Solution |
 |---------|-------|----------|
-| Config not applied (everything asks) | File not found or parse error | Verify the global Pi policy file (default: `~/.pi/agent/pi-permissions.jsonc`, respects `PI_CODING_AGENT_DIR`); check for trailing commas |
+| Config not applied (everything asks) | File not found or parse error | Verify the global Pi policy file (default: `~/.pi/agent/pi-permissions.jsonc`, respects `PI_CODING_AGENT_DIR`); check the TUI warning for the parse location/message |
 | Per-agent override not applied | Frontmatter parsing issue | Ensure `---` delimiters at file top; keep YAML simple; restart session |
 | Tool blocked as unregistered | Unknown tool name | Use a registered `mcp` tool for server tools: `{ "tool": "server:tool" }` |
 | `/skill:<name>` blocked | Deny policy or confirmation unavailable | Check merged `skills` policy (global/project/agent layers). Active agent context is optional in the main session; `ask` still requires UI or forwarded confirmation. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-permission-system",
-  "version": "0.4.8",
+  "version": "0.4.9",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "main": "./index.ts",
@@ -64,5 +64,8 @@
     "@mariozechner/pi-coding-agent": "^0.72.0",
     "@mariozechner/pi-tui": "^0.72.0",
     "@sinclair/typebox": "^0.34.49"
+  },
+  "dependencies": {
+    "jsonc-parser": "^3.3.1"
   }
 }

package/src/extension-config.ts

@@ -3,6 +3,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { toRecord } from "./common.js";
+import { formatJsoncConfigLoadWarning, parseJsoncConfig } from "./jsonc-config.js";
 
 export const EXTENSION_ID = "pi-permission-system";
 
@@ -107,7 +108,7 @@ export function loadPermissionSystemConfig(configPath = getPermissionSystemConfi
 
   try {
     const raw = readFileSync(configPath, "utf-8");
-    const parsed = JSON.parse(raw) as unknown;
+    const parsed = parseJsoncConfig(raw, configPath, "permission-system config");
     const config = normalizePermissionSystemConfig(parsed);
     return {
       config,
@@ -115,11 +116,12 @@ export function loadPermissionSystemConfig(configPath = getPermissionSystemConfi
       warning: ensureResult.warning,
     };
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
     return {
       config: cloneDefaultConfig(),
       created: ensureResult.created,
-      warning: ensureResult.warning ?? `Failed to read permission-system config at '${configPath}': ${message}`,
+      warning: ensureResult.warning
+        ?? formatJsoncConfigLoadWarning(configPath, error, "permission-system config", "using default extension config")
+        ?? undefined,
     };
   }
 }

package/src/index.ts

@@ -1014,20 +1014,23 @@ function derivePiProjectPaths(cwd: string | undefined | null): {
   };
 }
 
-function createPermissionManagerForCwd(cwd: string | undefined | null): PermissionManager {
+function createPermissionManagerForCwd(
+  cwd: string | undefined | null,
+  onWarning?: (message: string) => void,
+): PermissionManager {
   const projectPaths = derivePiProjectPaths(cwd);
   if (!projectPaths) {
-    return new PermissionManager();
+    return new PermissionManager({ onWarning });
   }
 
   return new PermissionManager({
     projectGlobalConfigPath: projectPaths.projectGlobalConfigPath,
     projectAgentsDir: projectPaths.projectAgentsDir,
+    onWarning,
   });
 }
 
 export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
-  let permissionManager = new PermissionManager();
   let activeSkillEntries: SkillPromptEntry[] = [];
   let lastKnownActiveAgentName: string | null = null;
   let lastActiveToolsCacheKey: string | null = null;
@@ -1037,6 +1040,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   let isProcessingForwardedRequests = false;
   let runtimeContext: ExtensionContext | null = null;
   let lastConfigWarning: string | null = null;
+  const shownWarnings = new Set<string>();
 
   const invalidateAgentStartCache = (): void => {
     activeSkillEntries = [];
@@ -1044,14 +1048,21 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     lastPromptStateCacheKey = null;
   };
 
+  const resetShownWarnings = (): void => {
+    shownWarnings.clear();
+  };
+
   const notifyWarning = (message: string): void => {
-    if (!runtimeContext?.hasUI) {
+    if (!runtimeContext?.hasUI || shownWarnings.has(message)) {
       return;
     }
 
+    shownWarnings.add(message);
     runtimeContext.ui.notify(message, "warning");
   };
 
+  let permissionManager = createPermissionManagerForCwd(undefined, notifyWarning);
+
   const refreshExtensionConfig = (ctx?: ExtensionContext): void => {
     if (ctx) {
       runtimeContext = ctx;
@@ -1366,8 +1377,9 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
 
   const refreshSessionRuntimeState = (ctx: ExtensionContext): void => {
     runtimeContext = ctx;
+    resetShownWarnings();
     refreshExtensionConfig(ctx);
-    permissionManager = createPermissionManagerForCwd(ctx.cwd);
+    permissionManager = createPermissionManagerForCwd(ctx.cwd, notifyWarning);
     invalidateAgentStartCache();
     lastKnownActiveAgentName = getActiveAgentName(ctx);
     startForwardedPermissionPolling(ctx);
@@ -1387,7 +1399,10 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
 
   pi.on("resources_discover", async (event, _ctx) => {
     if (event.reason === "reload") {
-      permissionManager = runtimeContext ? createPermissionManagerForCwd(runtimeContext.cwd) : new PermissionManager();
+      resetShownWarnings();
+      permissionManager = runtimeContext
+        ? createPermissionManagerForCwd(runtimeContext.cwd, notifyWarning)
+        : createPermissionManagerForCwd(undefined, notifyWarning);
       invalidateAgentStartCache();
       writeDebugLog("lifecycle.reload", {
         triggeredBy: "resources_discover",
@@ -1400,6 +1415,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
 
   pi.on("session_shutdown", async () => {
     runtimeContext?.ui.setStatus(PERMISSION_SYSTEM_STATUS_KEY, undefined);
+    resetShownWarnings();
     runtimeContext = null;
     unregisterPiPermissionSystemRuntimeApi(runtimeApi ?? undefined);
     runtimeApi = null;

package/src/jsonc-config.ts

@@ -0,0 +1,52 @@
+import { type ParseError as JsoncParseError, parse as parseJsonc, printParseErrorCode } from "jsonc-parser";
+
+function isNodeErrorWithCode(error: unknown, code: string): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+
+function formatJsoncParseSummary(input: string, errors: readonly JsoncParseError[]): string {
+  const firstError = errors[0];
+  if (!firstError) {
+    return "unknown parse error";
+  }
+
+  const beforeOffset = input.slice(0, firstError.offset).split("\n");
+  const line = beforeOffset.length;
+  const column = (beforeOffset.at(-1)?.length ?? 0) + 1;
+  const summary = `${printParseErrorCode(firstError.error)} at line ${line}, column ${column}`;
+  const additionalErrorCount = errors.length - 1;
+
+  if (additionalErrorCount <= 0) {
+    return summary;
+  }
+
+  return `${summary}; ${additionalErrorCount} more parse error${additionalErrorCount === 1 ? "" : "s"}`;
+}
+
+export function parseJsoncConfig(input: string, filePath: string, subject = "config"): unknown {
+  const errors: JsoncParseError[] = [];
+  const parsed = parseJsonc(input, errors, { allowTrailingComma: true });
+
+  if (errors.length > 0) {
+    throw new Error(`Failed to parse ${subject} at '${filePath}' (${formatJsoncParseSummary(input, errors)})`);
+  }
+
+  return parsed as unknown;
+}
+
+export function formatJsoncConfigLoadWarning(
+  filePath: string,
+  error: unknown,
+  subject = "config",
+  fallbackMessage?: string,
+): string | null {
+  if (isNodeErrorWithCode(error, "ENOENT")) {
+    return null;
+  }
+
+  const baseMessage = error instanceof Error
+    ? error.message
+    : `Failed to load ${subject} at '${filePath}': ${String(error)}`;
+
+  return fallbackMessage ? `${baseMessage}; ${fallbackMessage}.` : baseMessage;
+}

package/src/permission-manager.ts

@@ -3,6 +3,7 @@ import { readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 
 import { extractFrontmatter, getNonEmptyString, isPermissionState, parseSimpleYamlMap, toRecord } from "./common.js";
+import { formatJsoncConfigLoadWarning, parseJsoncConfig } from "./jsonc-config.js";
 import type {
   AgentPermissions,
   BashPermissions,
@@ -50,78 +51,6 @@ const EMPTY_GLOBAL_CONFIG: GlobalPermissionConfig = {
   special: {},
 };
 
-function stripJsonComments(input: string): string {
-  let output = "";
-  let inString = false;
-  let stringQuote: '"' | "'" | "" = "";
-  let escaping = false;
-  let inLineComment = false;
-  let inBlockComment = false;
-
-  for (let i = 0; i < input.length; i++) {
-    const char = input[i];
-    const next = input[i + 1] || "";
-
-    if (inLineComment) {
-      if (char === "\n") {
-        inLineComment = false;
-        output += char;
-      }
-      continue;
-    }
-
-    if (inBlockComment) {
-      if (char === "*" && next === "/") {
-        inBlockComment = false;
-        i++;
-      }
-      continue;
-    }
-
-    if (!inString && char === "/" && next === "/") {
-      inLineComment = true;
-      i++;
-      continue;
-    }
-
-    if (!inString && char === "/" && next === "*") {
-      inBlockComment = true;
-      i++;
-      continue;
-    }
-
-    output += char;
-
-    if (!inString && (char === '"' || char === "'")) {
-      inString = true;
-      stringQuote = char;
-      escaping = false;
-      continue;
-    }
-
-    if (!inString) {
-      continue;
-    }
-
-    if (escaping) {
-      escaping = false;
-      continue;
-    }
-
-    if (char === "\\") {
-      escaping = true;
-      continue;
-    }
-
-    if (char === stringQuote) {
-      inString = false;
-      stringQuote = "";
-    }
-  }
-
-  return output;
-}
-
 function normalizePolicy(value: unknown): PermissionDefaultPolicy {
   const record = toRecord(value);
   return {
@@ -174,7 +103,7 @@ function normalizePermissionRecord(value: unknown): Record<string, PermissionSta
 function readConfiguredMcpServerNamesFromConfigPath(configPath: string): string[] {
   try {
     const raw = readFileSync(configPath, "utf-8");
-    const parsed = JSON.parse(stripJsonComments(raw)) as unknown;
+    const parsed = parseJsoncConfig(raw, configPath, "permission config");
     const root = toRecord(parsed);
     const serverRecord = toRecord(root.mcpServers ?? root["mcp-servers"]);
 
@@ -585,6 +514,7 @@ export class PermissionManager {
   private readonly projectAgentConfigCache = new Map<string, FileCacheEntry<AgentPermissions>>();
   private readonly resolvedPermissionsCache = new Map<string, FileCacheEntry<ResolvedPermissions>>();
   private configuredMcpServerNamesCache: FileCacheEntry<readonly string[]> | null = null;
+  private readonly onWarning: ((message: string) => void) | null;
 
   constructor(
     options: {
@@ -595,6 +525,7 @@ export class PermissionManager {
       legacyGlobalSettingsPath?: string;
       globalMcpConfigPath?: string;
       mcpServerNames?: readonly string[];
+      onWarning?: (message: string) => void;
     } = {},
   ) {
     this.globalConfigPath = options.globalConfigPath || defaultGlobalConfigPath();
@@ -606,6 +537,11 @@ export class PermissionManager {
     this.configuredMcpServerNamesOverride = options.mcpServerNames
       ? [...new Set(options.mcpServerNames.map((name) => name.trim()).filter((name) => name.length > 0))]
       : null;
+    this.onWarning = options.onWarning || null;
+  }
+
+  private notifyWarning(message: string): void {
+    this.onWarning?.(message);
   }
 
   private loadGlobalConfig(): GlobalPermissionConfig {
@@ -617,7 +553,7 @@ export class PermissionManager {
     let value: GlobalPermissionConfig;
     try {
       const raw = readFileSync(this.globalConfigPath, "utf-8");
-      const parsed = JSON.parse(stripJsonComments(raw)) as unknown;
+      const parsed = parseJsoncConfig(raw, this.globalConfigPath, "permission config");
       const normalized = normalizeRawPermission(parsed);
 
       value = {
@@ -628,7 +564,16 @@ export class PermissionManager {
         skills: normalized.skills || {},
         special: normalized.special || {},
       };
-    } catch {
+    } catch (error) {
+      const warning = formatJsoncConfigLoadWarning(
+        this.globalConfigPath,
+        error,
+        "permission config",
+        "using ask fallback",
+      );
+      if (warning) {
+        this.notifyWarning(warning);
+      }
       value = EMPTY_GLOBAL_CONFIG;
     }
 
@@ -649,9 +594,18 @@ export class PermissionManager {
     let value: AgentPermissions;
     try {
       const raw = readFileSync(this.projectGlobalConfigPath, "utf-8");
-      const parsed = JSON.parse(stripJsonComments(raw)) as unknown;
+      const parsed = parseJsoncConfig(raw, this.projectGlobalConfigPath, "permission config");
       value = normalizeRawPermission(parsed);
-    } catch {
+    } catch (error) {
+      const warning = formatJsoncConfigLoadWarning(
+        this.projectGlobalConfigPath,
+        error,
+        "permission config",
+        "ignoring project permission overrides",
+      );
+      if (warning) {
+        this.notifyWarning(warning);
+      }
       value = {};
     }
 

package/tests/permission-system.test.ts

@@ -111,6 +111,7 @@ type ExtensionHarnessOptions = {
   selectResponse?: string;
   inputResponse?: string;
   statusUpdates?: Array<{ key: string; value: string | undefined }>;
+  notifications?: Array<{ message: string; level: string }>;
 };
 
 const INHERITED_SUBAGENT_ENV_KEYS = [
@@ -223,7 +224,9 @@ function createMockContext(
       getSessionDir: (): string => cwd,
     },
     ui: {
-      notify: (): void => {},
+      notify: (message: string, level: string): void => {
+        options.notifications?.push({ message, level });
+      },
       setStatus: (key: string, value: string | undefined): void => {
         options.statusUpdates?.push({ key, value });
       },
@@ -297,6 +300,41 @@ await runAsyncTest("Extension exposes a runtime YOLO API for other extensions",
   assert.equal((globalThis as GlobalWithPermissionSystem).__piPermissionSystem, undefined);
 });
 
+await runAsyncTest("Extension dedupes identical permission parse warnings across lifecycle re-entry", async () => {
+  const notifications: Array<{ message: string; level: string }> = [];
+  const harness = createToolCallHarness(
+    { defaultPolicy: { tools: "allow", bash: "allow", mcp: "allow", skills: "allow", special: "allow" } },
+    ["read", "write"],
+    { hasUI: true, notifications },
+  );
+
+  try {
+    mkdirSync(join(harness.cwd, ".pi", "agent"), { recursive: true });
+    writeFileSync(
+      join(harness.cwd, ".pi", "agent", "pi-permissions.jsonc"),
+      `{
+  "tools": {
+    "read": "allow",,
+  }
+}
+`,
+      "utf8",
+    );
+
+    const ctx = createMockContext(harness.cwd, harness.prompts, { hasUI: true, notifications });
+    await Promise.resolve(harness.handlers.session_start?.({ reason: "startup" }, ctx));
+    await Promise.resolve(harness.handlers.before_agent_start?.({ systemPrompt: "" }, ctx));
+    await Promise.resolve(harness.handlers.before_agent_start?.({ systemPrompt: "" }, ctx));
+
+    const warnings = notifications.filter((entry) => entry.level === "warning");
+    assert.equal(warnings.length, 1);
+    assert.match(warnings[0]?.message || "", /Failed to parse permission config at/);
+    assert.equal((warnings[0]?.message || "").includes("\n"), false);
+  } finally {
+    await harness.cleanup();
+  }
+});
+
 runTest("Permission-system extension config defaults debug off, review log on, and yolo mode off", () => {
   const baseDir = mkdtempSync(join(tmpdir(), "pi-permission-system-config-"));
   const configPath = join(baseDir, "config.json");
@@ -345,6 +383,63 @@ runTest("Permission-system extension config loads yolo mode when explicitly enab
   }
 });
 
+runTest("Permission-system extension config accepts JSONC comments and trailing commas", () => {
+  const baseDir = mkdtempSync(join(tmpdir(), "pi-permission-system-config-jsonc-"));
+  const configPath = join(baseDir, "config.json");
+
+  try {
+    writeFileSync(
+      configPath,
+      `{
+  // Local extension toggles
+  "debugLog": true,
+  "permissionReviewLog": false,
+  "yoloMode": true,
+}
+`,
+      "utf8",
+    );
+
+    const result = loadPermissionSystemConfig(configPath);
+    assert.equal(result.created, false);
+    assert.equal(result.warning, undefined);
+    assert.deepEqual(result.config, {
+      debugLog: true,
+      permissionReviewLog: false,
+      yoloMode: true,
+    });
+  } finally {
+    rmSync(baseDir, { recursive: true, force: true });
+  }
+});
+
+runTest("Permission-system extension config reports one-line JSONC parse warnings", () => {
+  const baseDir = mkdtempSync(join(tmpdir(), "pi-permission-system-config-parse-"));
+  const configPath = join(baseDir, "config.json");
+
+  try {
+    writeFileSync(
+      configPath,
+      `{
+  "debugLog": true,,
+  "permissionReviewLog": false
+}
+`,
+      "utf8",
+    );
+
+    const result = loadPermissionSystemConfig(configPath);
+    assert.equal(result.created, false);
+    assert.deepEqual(result.config, DEFAULT_EXTENSION_CONFIG);
+    assert.match(result.warning || "", /Failed to parse permission-system config at/);
+    assert.match(result.warning || "", /line 2, column 20/);
+    assert.match(result.warning || "", /using default extension config\./);
+    assert.equal((result.warning || "").includes("\n"), false);
+  } finally {
+    rmSync(baseDir, { recursive: true, force: true });
+  }
+});
+
 runTest("Permission-system extension config normalizes invalid persisted values back to defaults", () => {
   const baseDir = mkdtempSync(join(tmpdir(), "pi-permission-system-config-invalid-"));
   const configPath = join(baseDir, "config.json");
@@ -1799,6 +1894,100 @@ runTest("PermissionManager reads config from PI_CODING_AGENT_DIR when set", () =
   }
 });
 
+runTest("PermissionManager accepts JSONC comments and trailing commas in policy files", () => {
+  const baseDir = mkdtempSync(join(tmpdir(), "pi-permission-system-jsonc-"));
+  const agentsDir = join(baseDir, "agents");
+  const projectRoot = join(baseDir, "project");
+  const projectGlobalConfigPath = join(projectRoot, "pi-permissions.jsonc");
+  const projectAgentsDir = join(projectRoot, "agents");
+
+  mkdirSync(agentsDir, { recursive: true });
+  mkdirSync(projectAgentsDir, { recursive: true });
+
+  writeFileSync(
+    join(baseDir, "pi-permissions.jsonc"),
+    `{
+  // Global defaults still apply.
+  "defaultPolicy": {
+    "tools": "deny",
+    "bash": "deny",
+    "mcp": "deny",
+    "skills": "deny",
+    "special": "deny",
+  },
+  "tools": {
+    "read": "allow",
+  },
+}
+`,
+    "utf8",
+  );
+  writeFileSync(
+    projectGlobalConfigPath,
+    `{
+  "tools": {
+    "write": "allow",
+  },
+}
+`,
+    "utf8",
+  );
+
+  try {
+    const manager = new PermissionManager({
+      globalConfigPath: join(baseDir, "pi-permissions.jsonc"),
+      agentsDir,
+      projectGlobalConfigPath,
+      projectAgentsDir,
+    });
+
+    assert.equal(manager.checkPermission("read", {}).state, "allow");
+    assert.equal(manager.checkPermission("write", {}).state, "allow");
+    assert.equal(manager.checkPermission("ls", {}).state, "deny");
+  } finally {
+    rmSync(baseDir, { recursive: true, force: true });
+  }
+});
+
+runTest("PermissionManager warns once with a one-line fallback warning when a policy file has invalid JSONC", () => {
+  const baseDir = mkdtempSync(join(tmpdir(), "pi-permission-system-invalid-jsonc-"));
+  const agentsDir = join(baseDir, "agents");
+  const globalConfigPath = join(baseDir, "pi-permissions.jsonc");
+  const warnings: string[] = [];
+
+  mkdirSync(agentsDir, { recursive: true });
+  writeFileSync(
+    globalConfigPath,
+    `{
+  "tools": {
+    "read": "allow",,
+  }
+}
+`,
+    "utf8",
+  );
+
+  try {
+    const manager = new PermissionManager({
+      globalConfigPath,
+      agentsDir,
+      onWarning: (message) => {
+        warnings.push(message);
+      },
+    });
+
+    assert.equal(manager.checkPermission("read", {}).state, "ask");
+    assert.equal(manager.checkPermission("read", {}).state, "ask");
+    assert.equal(warnings.length, 1);
+    assert.match(warnings[0] || "", /Failed to parse permission config at/);
+    assert.match(warnings[0] || "", /line 3, column \d+/);
+    assert.match(warnings[0] || "", /using ask fallback\./);
+    assert.equal((warnings[0] || "").includes("\n"), false);
+  } finally {
+    rmSync(baseDir, { recursive: true, force: true });
+  }
+});
+
 // ---------------------------------------------------------------------------
 // Skill prompt sanitization - multi-block regression tests
 // ---------------------------------------------------------------------------