@gotgenes/pi-permission-system 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.2.0](https://github.com/gotgenes/pi-permission-system/compare/v1.1.0...v1.2.0) (2026-05-03)
+
+
+### Features
+
+* drop legacy settings.json fallback for MCP server names ([#19](https://github.com/gotgenes/pi-permission-system/issues/19)) ([3978f94](https://github.com/gotgenes/pi-permission-system/commit/3978f94acfe01b32e6e37c4fa0f5ca3b22881208))
+
+
+### Documentation
+
+* plan drop legacy settings.json MCP fallback ([#19](https://github.com/gotgenes/pi-permission-system/issues/19)) ([fd88aac](https://github.com/gotgenes/pi-permission-system/commit/fd88aac8e52c0b617b5ce2582c700bbb86b9bf84))
+* **retro:** add retro notes for issue [#18](https://github.com/gotgenes/pi-permission-system/issues/18) ([1bb9cc5](https://github.com/gotgenes/pi-permission-system/commit/1bb9cc52abe159d77b8ab29960bafdb2740c9c98))
+
+## [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.2.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

@@ -31,9 +31,6 @@ function defaultGlobalConfigPath(): string {
 function defaultAgentsDir(): string {
   return join(getAgentDir(), "agents");
 }
-function defaultLegacyGlobalSettingsPath(): string {
-  return join(getAgentDir(), "settings.json");
-}
 function defaultGlobalMcpConfigPath(): string {
   return join(getAgentDir(), "mcp.json");
 }
@@ -237,8 +234,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 +257,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 +286,7 @@ function normalizeRawPermission(raw: unknown): AgentPermissions {
     }
   }
 
-  return normalized;
+  return { permissions: normalized, configIssues };
 }
 
 function parseQualifiedMcpToolName(
@@ -500,7 +521,6 @@ export class PermissionManager {
   private readonly agentsDir: string;
   private readonly projectGlobalConfigPath: string | null;
   private readonly projectAgentsDir: string | null;
-  private readonly legacyGlobalSettingsPath: string;
   private readonly globalMcpConfigPath: string;
   private readonly configuredMcpServerNamesOverride: readonly string[] | null;
   private globalConfigCache: FileCacheEntry<GlobalPermissionConfig> | null =
@@ -522,6 +542,7 @@ export class PermissionManager {
   private configuredMcpServerNamesCache: FileCacheEntry<
     readonly string[]
   > | null = null;
+  private accumulatedConfigIssues: string[] = [];
 
   constructor(
     options: {
@@ -529,7 +550,6 @@ export class PermissionManager {
       agentsDir?: string;
       projectGlobalConfigPath?: string;
       projectAgentsDir?: string;
-      legacyGlobalSettingsPath?: string;
       globalMcpConfigPath?: string;
       mcpServerNames?: readonly string[];
     } = {},
@@ -539,8 +559,6 @@ export class PermissionManager {
     this.agentsDir = options.agentsDir || defaultAgentsDir();
     this.projectGlobalConfigPath = options.projectGlobalConfigPath || null;
     this.projectAgentsDir = options.projectAgentsDir || null;
-    this.legacyGlobalSettingsPath =
-      options.legacyGlobalSettingsPath || defaultLegacyGlobalSettingsPath();
     this.globalMcpConfigPath =
       options.globalMcpConfigPath || defaultGlobalMcpConfigPath();
     this.configuredMcpServerNamesOverride = options.mcpServerNames
@@ -554,6 +572,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 +596,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 +630,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 +665,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 = {};
@@ -795,7 +833,7 @@ export class PermissionManager {
       return this.configuredMcpServerNamesOverride;
     }
 
-    const paths = [this.globalMcpConfigPath, this.legacyGlobalSettingsPath];
+    const paths = [this.globalMcpConfigPath];
     const stamp = paths
       .map((path) => `${path}:${getFileStamp(path)}`)
       .join("|");

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,
@@ -904,6 +911,67 @@ test("MCP proxy tool infers server-prefixed aliases from configured server names
   }
 });
 
+test("MCP server names in settings.json are not used — only mcp.json is consulted", () => {
+  const baseDir = mkdtempSync(join(tmpdir(), "pi-permission-system-test-"));
+  const globalConfigPath = join(baseDir, "pi-permissions.jsonc");
+  const mcpConfigPath = join(baseDir, "mcp.json");
+  const settingsJsonPath = join(baseDir, "settings.json");
+  const agentsDir = join(baseDir, "agents");
+  mkdirSync(agentsDir, { recursive: true });
+
+  // Policy: allow any target prefixed with legacy-server, default mcp is ask.
+  // If legacy-server were known as a configured server name, a tool named
+  // "some_tool_legacy-server" would derive "legacy-server_some_tool_legacy-server"
+  // which matches this rule and returns "allow".
+  // After the fix, settings.json is ignored, so no server name is derived and the
+  // result falls through to the default mcp policy ("ask").
+  const config: GlobalPermissionConfig = {
+    defaultPolicy: {
+      tools: "ask",
+      bash: "ask",
+      mcp: "ask",
+      skills: "ask",
+      special: "ask",
+    },
+    tools: {},
+    bash: {},
+    mcp: { "legacy-server_*": "allow" },
+    skills: {},
+    special: {},
+  };
+
+  writeFileSync(
+    globalConfigPath,
+    `${JSON.stringify(config, null, 2)}\n`,
+    "utf8",
+  );
+  // mcp.json does not know about legacy-server.
+  writeFileSync(mcpConfigPath, JSON.stringify({ mcpServers: {} }), "utf8");
+  // settings.json has legacy-server — the legacy source that must now be ignored.
+  writeFileSync(
+    settingsJsonPath,
+    JSON.stringify({ mcpServers: { "legacy-server": {} } }),
+    "utf8",
+  );
+
+  const manager = new PermissionManager({
+    globalConfigPath,
+    agentsDir,
+    globalMcpConfigPath: mcpConfigPath,
+  });
+
+  try {
+    // "legacy-server" must not be derived from settings.json.
+    // The bare tool name falls through to the default mcp policy → "ask".
+    const result = manager.checkPermission("mcp", {
+      tool: "some_tool_legacy-server",
+    });
+    assert.equal(result.state, "ask");
+  } finally {
+    rmSync(baseDir, { recursive: true, force: true });
+  }
+});
+
 test("MCP describe mode normalizes qualified tool names without duplicating server prefixes", () => {
   const { manager, cleanup } = createManager(
     {
@@ -2357,3 +2425,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();
+  }
+});