@gotgenes/pi-permission-system 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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).
 
+## [1.1.0](https://github.com/gotgenes/pi-permission-system/compare/v1.0.0...v1.1.0) (2026-05-03)
+
+
+### Features
+
+* emit deprecation warning for special.tool_call_limit ([#18](https://github.com/gotgenes/pi-permission-system/issues/18)) ([1170d40](https://github.com/gotgenes/pi-permission-system/commit/1170d401d3adc438ad3c69bf96f5264b981ed4d5))
+* notify user of deprecated config fields at startup ([#18](https://github.com/gotgenes/pi-permission-system/issues/18)) ([3408672](https://github.com/gotgenes/pi-permission-system/commit/3408672afb94783f173b579e9e33fe088f0971f3))
+* surface config issues from PermissionManager ([#18](https://github.com/gotgenes/pi-permission-system/issues/18)) ([4c8103b](https://github.com/gotgenes/pi-permission-system/commit/4c8103bed99c3d31813f5450a6f4d1938fd74f25))
+
+
+### Documentation
+
+* plan drop unread special.tool_call_limit from schema ([#18](https://github.com/gotgenes/pi-permission-system/issues/18)) ([c45f6f7](https://github.com/gotgenes/pi-permission-system/commit/c45f6f7e5a504cac4f6156a97f51ff9588639d94))
+* remove tool_call_limit from schema and README ([#18](https://github.com/gotgenes/pi-permission-system/issues/18)) ([780b414](https://github.com/gotgenes/pi-permission-system/commit/780b41431b1ac06ccf11dca00e1c59575386bbd2))
+
 ## [1.0.0](https://github.com/gotgenes/pi-permission-system/compare/v0.8.0...v1.0.0) (2026-05-03)
 
 

package/README.md

@@ -328,7 +328,6 @@ Reserved permission checks:
 | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `doom_loop`          | Controls doom loop detection behavior                                                                                                                                         |
 | `external_directory` | Enforces ask/allow/deny decisions for path-bearing built-in tools (`read`, `write`, `edit`, `find`, `grep`, `ls`) when they target paths outside the active working directory |
-| `tool_call_limit`    | _(schema only, not enforced yet)_                                                                                                                                             |
 
 ```jsonc
 {

package/package.json

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

package/schemas/permissions.schema.json

@@ -53,17 +53,6 @@
         },
         "external_directory": {
           "$ref": "#/$defs/permissionState"
-        },
-        "tool_call_limit": {
-          "oneOf": [
-            {
-              "$ref": "#/$defs/permissionState"
-            },
-            {
-              "type": "integer",
-              "minimum": 0
-            }
-          ]
         }
       }
     }

package/src/index.ts

@@ -1569,6 +1569,13 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     startForwardedPermissionPolling(ctx);
     logResolvedConfigPaths();
 
+    const policyIssues = permissionManager.getConfigIssues(
+      lastKnownActiveAgentName,
+    );
+    for (const issue of policyIssues) {
+      notifyWarning(issue);
+    }
+
     if (event.reason === "reload") {
       writeDebugLog("lifecycle.reload", {
         triggeredBy: "session_start",

package/src/permission-manager.ts

@@ -237,8 +237,18 @@ function getConfiguredMcpServerNamesFromPaths(
   );
 }
 
-function normalizeRawPermission(raw: unknown): AgentPermissions {
+const DEPRECATED_SPECIAL_KEYS: ReadonlySet<string> = new Set([
+  "tool_call_limit",
+]);
+
+export interface NormalizeResult {
+  permissions: AgentPermissions;
+  configIssues: string[];
+}
+
+export function normalizeRawPermission(raw: unknown): NormalizeResult {
   const record = toRecord(raw);
+  const configIssues: string[] = [];
   const normalizedTools = normalizePermissionRecord(record.tools);
 
   const normalized: AgentPermissions = {
@@ -250,6 +260,20 @@ function normalizeRawPermission(raw: unknown): AgentPermissions {
     special: normalizePermissionRecord(record.special),
   };
 
+  // Detect deprecated keys in the raw special sub-object before discarding.
+  const rawSpecial = toRecord(record.special);
+  for (const key of DEPRECATED_SPECIAL_KEYS) {
+    if (key in rawSpecial) {
+      configIssues.push(
+        `special.${key} is deprecated and ignored — remove it from your policy file.`,
+      );
+      // Ensure the key is stripped even if its value was a valid PermissionState.
+      if (normalized.special) {
+        delete normalized.special[key];
+      }
+    }
+  }
+
   for (const [key, value] of Object.entries(record)) {
     if (!isPermissionState(value)) {
       continue;
@@ -265,7 +289,7 @@ function normalizeRawPermission(raw: unknown): AgentPermissions {
     }
   }
 
-  return normalized;
+  return { permissions: normalized, configIssues };
 }
 
 function parseQualifiedMcpToolName(
@@ -522,6 +546,7 @@ export class PermissionManager {
   private configuredMcpServerNamesCache: FileCacheEntry<
     readonly string[]
   > | null = null;
+  private accumulatedConfigIssues: string[] = [];
 
   constructor(
     options: {
@@ -554,6 +579,20 @@ export class PermissionManager {
       : null;
   }
 
+  private accumulateConfigIssues(issues: string[]): void {
+    for (const issue of issues) {
+      if (!this.accumulatedConfigIssues.includes(issue)) {
+        this.accumulatedConfigIssues.push(issue);
+      }
+    }
+  }
+
+  getConfigIssues(agentName?: string): string[] {
+    // Trigger a load/resolve to ensure issues are collected.
+    this.resolvePermissions(agentName);
+    return [...this.accumulatedConfigIssues];
+  }
+
   private loadGlobalConfig(): GlobalPermissionConfig {
     const stamp = getFileStamp(this.globalConfigPath);
     if (this.globalConfigCache?.stamp === stamp) {
@@ -564,7 +603,9 @@ export class PermissionManager {
     try {
       const raw = readFileSync(this.globalConfigPath, "utf-8");
       const parsed = JSON.parse(stripJsonComments(raw)) as unknown;
-      const normalized = normalizeRawPermission(parsed);
+      const { permissions: normalized, configIssues } =
+        normalizeRawPermission(parsed);
+      this.accumulateConfigIssues(configIssues);
 
       value = {
         defaultPolicy: normalizePolicy(normalized.defaultPolicy),
@@ -596,7 +637,9 @@ export class PermissionManager {
     try {
       const raw = readFileSync(this.projectGlobalConfigPath, "utf-8");
       const parsed = JSON.parse(stripJsonComments(raw)) as unknown;
-      value = normalizeRawPermission(parsed);
+      const result = normalizeRawPermission(parsed);
+      value = result.permissions;
+      this.accumulateConfigIssues(result.configIssues);
     } catch {
       value = {};
     }
@@ -629,7 +672,9 @@ export class PermissionManager {
         value = {};
       } else {
         const parsed = parseSimpleYamlMap(frontmatter);
-        value = normalizeRawPermission(parsed.permission);
+        const result = normalizeRawPermission(parsed.permission);
+        value = result.permissions;
+        this.accumulateConfigIssues(result.configIssues);
       }
     } catch {
       value = {};

package/tests/permission-system.test.ts

@@ -32,7 +32,10 @@ import {
   SUBAGENT_ENV_HINT_KEYS,
   SUBAGENT_PARENT_SESSION_ENV_KEY,
 } from "../src/permission-forwarding.js";
-import { PermissionManager } from "../src/permission-manager.js";
+import {
+  normalizeRawPermission,
+  PermissionManager,
+} from "../src/permission-manager.js";
 import {
   findSkillPathMatch,
   parseAllSkillPromptSections,
@@ -44,7 +47,11 @@ import {
   checkRequestedToolRegistration,
   getToolNameFromValue,
 } from "../src/tool-registry.js";
-import type { AgentPermissions, GlobalPermissionConfig } from "../src/types.js";
+import type {
+  AgentPermissions,
+  GlobalPermissionConfig,
+  PermissionState,
+} from "../src/types.js";
 import {
   canResolveAskPermissionRequest,
   shouldAutoApprovePermissionState,
@@ -2357,3 +2364,83 @@ test("getResolvedPolicyPaths returns false for missing files and null for absent
     rmSync(tempDir, { recursive: true, force: true });
   }
 });
+
+// --- tool_call_limit deprecation tests (#18) ---
+
+test("normalizeRawPermission emits deprecation issue for special.tool_call_limit (integer)", () => {
+  const result = normalizeRawPermission({ special: { tool_call_limit: 5 } });
+  assert.equal(result.configIssues.length, 1);
+  assert.ok(result.configIssues[0].includes("tool_call_limit"));
+  assert.equal(result.permissions.special?.tool_call_limit, undefined);
+});
+
+test("normalizeRawPermission emits deprecation issue for special.tool_call_limit (string)", () => {
+  const result = normalizeRawPermission({
+    special: { tool_call_limit: "allow" },
+  });
+  assert.equal(result.configIssues.length, 1);
+  assert.ok(result.configIssues[0].includes("tool_call_limit"));
+  assert.equal(result.permissions.special?.tool_call_limit, undefined);
+});
+
+test("normalizeRawPermission emits no issues for valid special keys", () => {
+  const result = normalizeRawPermission({
+    special: { doom_loop: "deny" },
+  });
+  assert.equal(result.configIssues.length, 0);
+  assert.equal(result.permissions.special?.doom_loop, "deny");
+});
+
+test("normalizeRawPermission emits no issues when special is absent", () => {
+  const result = normalizeRawPermission({ tools: { read: "allow" } });
+  assert.equal(result.configIssues.length, 0);
+});
+
+test("PermissionManager.getConfigIssues returns deprecation for tool_call_limit in global config", () => {
+  const config: GlobalPermissionConfig = {
+    defaultPolicy: {
+      tools: "ask",
+      bash: "ask",
+      mcp: "ask",
+      skills: "ask",
+      special: "ask",
+    },
+    tools: {},
+    bash: {},
+    mcp: {},
+    skills: {},
+    special: { tool_call_limit: "allow" as PermissionState, doom_loop: "deny" },
+  };
+  const { manager, cleanup } = createManager(config);
+  try {
+    const issues = manager.getConfigIssues();
+    assert.equal(issues.length, 1);
+    assert.ok(issues[0].includes("tool_call_limit"));
+  } finally {
+    cleanup();
+  }
+});
+
+test("PermissionManager.getConfigIssues returns empty array for clean config", () => {
+  const config: GlobalPermissionConfig = {
+    defaultPolicy: {
+      tools: "ask",
+      bash: "ask",
+      mcp: "ask",
+      skills: "ask",
+      special: "ask",
+    },
+    tools: {},
+    bash: {},
+    mcp: {},
+    skills: {},
+    special: { doom_loop: "deny" },
+  };
+  const { manager, cleanup } = createManager(config);
+  try {
+    const issues = manager.getConfigIssues();
+    assert.equal(issues.length, 0);
+  } finally {
+    cleanup();
+  }
+});