@gotgenes/pi-permission-system 0.8.0 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ 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)
+
+
+### ⚠ BREAKING CHANGES
+
+* The bundled temperature-stripping shim for OpenAI Responses-style APIs (openai-codex-responses, openai-responses, azure-openai-responses) has been removed. This module monkey-patched the provider stack at the process level and had no connection to permission enforcement. Users who need the shim can extract it into a standalone extension.
+
+### Features
+
+* remove out-of-scope model-option-compatibility provider shim ([#17](https://github.com/gotgenes/pi-permission-system/issues/17)) ([b390896](https://github.com/gotgenes/pi-permission-system/commit/b39089611fe565f81dacf7fa0bff3af36d50f7ce))
+
+
+### Documentation
+
+* plan removal of out-of-scope model-option-compatibility shim ([#17](https://github.com/gotgenes/pi-permission-system/issues/17)) ([a48f2ef](https://github.com/gotgenes/pi-permission-system/commit/a48f2ef025cbe970d21071b94552fcb9a4f7de89))
+* **retro:** add retro notes for issue [#16](https://github.com/gotgenes/pi-permission-system/issues/16) ([ee710cb](https://github.com/gotgenes/pi-permission-system/commit/ee710cba9b1fe92a39016c61348d2a0eb2895d1f))
+
 ## [0.8.0](https://github.com/gotgenes/pi-permission-system/compare/v0.7.0...v0.8.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": "0.8.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

@@ -35,7 +35,6 @@ import {
   savePermissionSystemConfig,
 } from "./extension-config.js";
 import { createPermissionSystemLogger, safeJsonStringify } from "./logging.js";
-import { registerModelOptionCompatibilityGuard } from "./model-option-compatibility.js";
 import {
   isPermissionDecisionState,
   type PermissionPromptDecision,
@@ -1338,8 +1337,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
 
   setLoggingWarningReporter(notifyWarning);
   refreshExtensionConfig();
-  registerModelOptionCompatibilityGuard(pi);
-
   registerPermissionSystemCommand(pi, {
     getConfig: () => extensionConfig,
     setConfig: saveExtensionConfig,
@@ -1572,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();
+  }
+});

package/src/model-option-compatibility.ts

@@ -1,182 +0,0 @@
-import {
-  type Api,
-  type AssistantMessageEventStream,
-  getApiProvider,
-  type Context as LlmContext,
-  type Model,
-  type SimpleStreamOptions,
-} from "@mariozechner/pi-ai";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-
-const GUARDED_TEMPERATURE_APIS = [
-  "openai-codex-responses",
-  "openai-responses",
-  "azure-openai-responses",
-] as const satisfies readonly Api[];
-const OPENAI_RESPONSES_APIS = new Set<Api>([
-  "openai-responses",
-  "azure-openai-responses",
-]);
-const TEMPERATURE_UNSUPPORTED_APIS = new Set<Api>(["openai-codex-responses"]);
-const TEMPERATURE_UNSUPPORTED_PROVIDERS = new Set<string>(["openai-codex"]);
-
-export type ApiStreamSimpleDelegate = (
-  model: Model<Api>,
-  context: LlmContext,
-  options?: SimpleStreamOptions,
-) => AssistantMessageEventStream;
-
-type GlobalWithPermissionSystemProviderGuard = typeof globalThis & {
-  __piPermissionSystemModelOptionBaseStreams?: Map<
-    string,
-    ApiStreamSimpleDelegate
-  >;
-  __piPermissionSystemModelOptionGuardedApis?: Set<string>;
-};
-
-function getBaseApiStreams(): Map<string, ApiStreamSimpleDelegate> {
-  const globalScope = globalThis as GlobalWithPermissionSystemProviderGuard;
-  if (!globalScope.__piPermissionSystemModelOptionBaseStreams) {
-    globalScope.__piPermissionSystemModelOptionBaseStreams = new Map<
-      string,
-      ApiStreamSimpleDelegate
-    >();
-  }
-  return globalScope.__piPermissionSystemModelOptionBaseStreams;
-}
-
-function getGuardedApis(): Set<string> {
-  const globalScope = globalThis as GlobalWithPermissionSystemProviderGuard;
-  if (!globalScope.__piPermissionSystemModelOptionGuardedApis) {
-    globalScope.__piPermissionSystemModelOptionGuardedApis = new Set<string>();
-  }
-  return globalScope.__piPermissionSystemModelOptionGuardedApis;
-}
-
-function normalizeIdentifier(value: string | undefined): string {
-  return (value ?? "").trim().toLowerCase();
-}
-
-function hasModelToken(modelId: string, token: string): boolean {
-  return normalizeIdentifier(modelId)
-    .split(/[^a-z0-9]+/)
-    .includes(token);
-}
-
-export function getUnsupportedTemperatureReason(
-  model: Pick<Model<Api>, "api" | "id" | "provider" | "reasoning">,
-): string | undefined {
-  if (TEMPERATURE_UNSUPPORTED_APIS.has(model.api)) {
-    return `api '${model.api}' does not support temperature`;
-  }
-
-  const provider = normalizeIdentifier(model.provider);
-  if (TEMPERATURE_UNSUPPORTED_PROVIDERS.has(provider)) {
-    return `provider '${model.provider}' does not support temperature`;
-  }
-
-  if (
-    OPENAI_RESPONSES_APIS.has(model.api) &&
-    hasModelToken(model.id, "codex")
-  ) {
-    return `model '${model.id}' does not support temperature`;
-  }
-
-  if (OPENAI_RESPONSES_APIS.has(model.api) && model.reasoning) {
-    return `reasoning model '${model.id}' accepts only the provider default temperature`;
-  }
-
-  return undefined;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-export function stripUnsupportedTemperatureFromPayload(
-  payload: unknown,
-): unknown {
-  if (!isRecord(payload) || !("temperature" in payload)) {
-    return payload;
-  }
-
-  const { temperature: _temperature, ...rest } = payload;
-  return rest;
-}
-
-function composeTemperatureSanitizer(
-  options: SimpleStreamOptions | undefined,
-  model: Model<Api>,
-): SimpleStreamOptions | undefined {
-  const reason = getUnsupportedTemperatureReason(model);
-  if (!reason && options?.temperature === undefined) {
-    return options;
-  }
-
-  if (!reason) {
-    return options;
-  }
-
-  const existingOnPayload = options?.onPayload;
-  const nextOptions: SimpleStreamOptions = options
-    ? { ...options, temperature: undefined }
-    : {};
-
-  nextOptions.onPayload = async (payload, payloadModel) => {
-    const transformedPayload = existingOnPayload
-      ? await existingOnPayload(payload, payloadModel)
-      : undefined;
-    return stripUnsupportedTemperatureFromPayload(
-      transformedPayload ?? payload,
-    );
-  };
-
-  return nextOptions;
-}
-
-function ensureModelOptionGuardForApi(pi: ExtensionAPI, api: Api): boolean {
-  const guardedApis = getGuardedApis();
-  if (guardedApis.has(api)) {
-    return true;
-  }
-
-  const baseStreams = getBaseApiStreams();
-  let baseStream = baseStreams.get(api);
-  if (!baseStream) {
-    const currentProvider = getApiProvider(api);
-    if (!currentProvider) {
-      return false;
-    }
-    baseStream = currentProvider.streamSimple as ApiStreamSimpleDelegate;
-    baseStreams.set(api, baseStream);
-  }
-
-  const providerName = `pi-permission-system-model-option-compatibility-${api.replace(/[^a-z0-9]+/gi, "-").toLowerCase()}`;
-  pi.registerProvider(providerName, {
-    api,
-    streamSimple: (model, context, options) => {
-      const typedModel = model as Model<Api>;
-      const delegate = baseStreams.get(typedModel.api);
-      if (!delegate) {
-        throw new Error(
-          `No base stream provider available for api '${typedModel.api}'.`,
-        );
-      }
-
-      return delegate(
-        typedModel,
-        context,
-        composeTemperatureSanitizer(options, typedModel),
-      );
-    },
-  });
-
-  guardedApis.add(api);
-  return true;
-}
-
-export function registerModelOptionCompatibilityGuard(pi: ExtensionAPI): void {
-  for (const api of GUARDED_TEMPERATURE_APIS) {
-    ensureModelOptionGuardForApi(pi, api);
-  }
-}