@gotgenes/pi-permission-system 39.0.3 → 39.0.4

package/CHANGELOG.md

@@ -5,6 +5,14 @@ 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).
 
+## [39.0.4](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v39.0.3...pi-permission-system-v39.0.4) (2026-10-05)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** show a broken config file's error once, not twice, at session start ([67ddf4f](https://github.com/gotgenes/pi-packages/commit/67ddf4f637bd6f4e15246093dc3d1c459552c7f2)), closes [#953](https://github.com/gotgenes/pi-packages/issues/953)
+* **pi-permission-system:** report a policy file that fails closed mid-session ([100a0d3](https://github.com/gotgenes/pi-packages/commit/100a0d3e1b49c92454163b270df52df7cc78ca1f)), closes [#953](https://github.com/gotgenes/pi-packages/issues/953)
+
 ## [39.0.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v39.0.2...pi-permission-system-v39.0.3) (2026-10-03)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "39.0.3",
+  "version": "39.0.4",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/src/config/config-store.ts

@@ -101,7 +101,7 @@ export class ConfigStore
    *
    * This store answers; `ConfigIssueReporter` decides whether the operator has
    * heard it yet (#933). Not to be confused with
-   * `PermissionResolver.getConfigIssues(agentName?)`, which answers for the
+   * `PermissionResolver.getPolicyIssues(agentName?)`, which answers for the
    * *policy* files rather than the extension config.
    */
   getConfigIssues(): readonly string[] {

package/src/config/policy-issue-reporter.ts

@@ -0,0 +1,55 @@
+/**
+ * policy-issue-reporter.ts — Tell the operator what composing their policy
+ * revealed, once per notice, for as long as it holds.
+ *
+ * The policy side answers only what it alone knows: the fail-closed notice for
+ * a rejected non-global scope (its `allow` rules are clamped to `ask`) and the
+ * port notice for relocated MCP tool keys. A config file's own schema errors
+ * are `ConfigIssueReporter`'s; both reporters reading them showed the operator
+ * each one twice (#953).
+ *
+ * Policy is re-read from file mtimes whenever it is consulted, so a file broken
+ * mid-session is clamped mid-session. Reporting only at `session_start` left
+ * that clamp unexplained; this is driven there and on every
+ * `before_agent_start`, so the operator hears about it on the next turn.
+ *
+ * The notices are agent-scoped, so the agent name is an argument rather than
+ * something this reads for itself: `AgentPrepHandler` resolves it from the
+ * `<active_agent>` prompt tag — the only name a pi-subagents child has — after
+ * turn prep runs, and hands it here.
+ *
+ * The latch is `ConfigIssueReporter`'s: per notice, delivered as one joined
+ * message per report, and *replaced* each report rather than added to — so a
+ * file fixed and broken again, or an agent switched away from and back into
+ * with a broken scope, is announced again.
+ */
+
+import type { ConfigIssueWarner } from "./config-issue-reporter";
+
+/** The policy seam this reads (ISP): the notices composing an agent's policy produced. */
+export interface PolicyIssueSource {
+  getPolicyIssues(agentName?: string): readonly string[];
+}
+
+/** The seam the session-start and agent-prep handlers drive. */
+export interface PolicyIssueReporting {
+  report(agentName: string | undefined): void;
+}
+
+export class PolicyIssueReporter implements PolicyIssueReporting {
+  private reported: ReadonlySet<string> = new Set();
+
+  constructor(
+    private readonly source: PolicyIssueSource,
+    private readonly log: ConfigIssueWarner,
+  ) {}
+
+  report(agentName: string | undefined): void {
+    const current = this.source.getPolicyIssues(agentName);
+    const unreported = current.filter((issue) => !this.reported.has(issue));
+    if (unreported.length > 0) {
+      this.log.warn(unreported.join("\n"));
+    }
+    this.reported = new Set(current);
+  }
+}

package/src/config/policy-loader.ts

@@ -81,8 +81,8 @@ export interface ResolvedPolicyPaths {
 
 /**
  * Abstraction over file I/O for loading permission policy from disk.
- * Implementations handle caching, path resolution, and config-issue
- * accumulation.  `PermissionManager` depends on this interface so that
+ * Implementations handle caching, path resolution, and marking a rejected
+ * scope `invalid`.  `PermissionManager` depends on this interface so that
  * merge + evaluation logic can be tested with an in-memory stub.
  */
 export interface PolicyLoader {
@@ -93,8 +93,6 @@ export interface PolicyLoader {
   getConfiguredMcpServerNames(): readonly string[];
   /** Combined mtime stamp for cache invalidation. */
   getCacheStamp(agentName?: string): string;
-  /** Accumulated config-parse issues across all loads. */
-  getConfigIssues(): string[];
   /** Resolved paths for the /permission-system show command. */
   getResolvedPolicyPaths(): ResolvedPolicyPaths;
 }
@@ -172,7 +170,6 @@ export class FilePolicyLoader implements PolicyLoader {
   private configuredMcpServerNamesCache: FileCacheEntry<
     readonly string[]
   > | null = null;
-  private accumulatedConfigIssues: string[] = [];
 
   constructor(options: PolicyLoaderOptions = {}) {
     this.globalConfigPath =
@@ -194,21 +191,11 @@ export class FilePolicyLoader implements PolicyLoader {
       : null;
   }
 
-  // ── Config issue accumulation ────────────────────────────────────────
-
-  private accumulateConfigIssues(issues: string[]): void {
-    for (const issue of issues) {
-      if (!this.accumulatedConfigIssues.includes(issue)) {
-        this.accumulatedConfigIssues.push(issue);
-      }
-    }
-  }
-
-  getConfigIssues(): string[] {
-    return [...this.accumulatedConfigIssues];
-  }
-
   // ── Scope loaders ────────────────────────────────────────────────────
+  //
+  // A config file's schema errors are not kept here: `ConfigStore` loads the
+  // same files through the same `loadUnifiedConfig` and reports them, so this
+  // loader reads them only to decide whether a scope fails closed (#953).
 
   loadGlobalConfig(): ScopeConfig {
     const stamp = getFileStamp(this.globalConfigPath);
@@ -216,8 +203,7 @@ export class FilePolicyLoader implements PolicyLoader {
       return this.globalConfigCache.value;
     }
 
-    const { config, issues } = loadUnifiedConfig(this.globalConfigPath);
-    this.accumulateConfigIssues(issues);
+    const { config } = loadUnifiedConfig(this.globalConfigPath);
 
     const value: ScopeConfig = {
       permission: config.permission,
@@ -238,7 +224,6 @@ export class FilePolicyLoader implements PolicyLoader {
     }
 
     const { config, issues } = loadUnifiedConfig(this.projectGlobalConfigPath);
-    this.accumulateConfigIssues(issues);
 
     // A present-but-rejected file yields issues (parse error or schema
     // rejection); an absent file yields none. Fail closed on the former.

package/src/handlers/before-agent-start.ts

@@ -4,6 +4,7 @@ import type {
   NormalizedBuildSystemPromptOptions,
 } from "@earendil-works/pi-coding-agent";
 import type { SubagentDetector } from "#src/authority/subagent-detection";
+import type { PolicyIssueReporting } from "#src/config/policy-issue-reporter";
 import {
   visibleSkillPromptEntries,
   withoutDeniedSkills,
@@ -78,6 +79,10 @@ export function shouldExposeTool(
  * - `logger` — records each change to the effective tool surface
  * - `detector` — tells a subagent child from a root, which decides whether a
  *   custom prompt gets this node's tool surface
+ * - `policyIssues` — reports what composing policy revealed for the agent the
+ *   prompt names; driven here rather than in turn prep because the
+ *   `<active_agent>` tag, the only name a pi-subagents child has, is read here
+ *   (#953)
  *
  * The active set is recomputed from the session's pre-filter tool surface
  * every turn, so relaxing a rule restores the tool it had withheld (#873).
@@ -90,6 +95,7 @@ export class AgentPrepHandler {
     private readonly toolRegistry: ToolRegistry,
     private readonly logger: DebugLogger,
     private readonly detector: SubagentDetector,
+    private readonly policyIssues: PolicyIssueReporting,
   ) {}
 
   // eslint-disable-next-line @typescript-eslint/require-await
@@ -105,6 +111,9 @@ export class AgentPrepHandler {
         ? event.systemPrompt
         : event.systemPrompt.join("\n");
     const agentName = this.session.resolveAgentName(ctx, systemPrompt);
+    // Policy is re-read by mtime, so this turn may compose a clamp the file
+    // just caused; say so for the agent this turn runs as.
+    this.policyIssues.report(agentName ?? undefined);
     const registered = readRegisteredTools(this.toolRegistry.getAll());
     const surface = this.session.resolveExposedTools(
       this.observeToolSurface(registered),

package/src/handlers/lifecycle.ts

@@ -1,10 +1,10 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AskDialogRelease } from "#src/authority/ask-dialog-queue";
 import type { ConfigIssueReporting } from "#src/config/config-issue-reporter";
+import type { PolicyIssueReporting } from "#src/config/policy-issue-reporter";
 import { PERMISSION_SYSTEM_STATUS_KEY } from "#src/config/status";
 import type { DecisionSummaryWriter } from "#src/logging/decision-audit";
 import type { SessionLogger } from "#src/logging/session-logger";
-import type { PermissionResolver } from "#src/policy/permission-resolver";
 import type { ServiceLifecycle } from "#src/service/service-lifecycle";
 import type { PermissionSession } from "#src/session/permission-session";
 
@@ -41,7 +41,9 @@ export const UNTRUSTED_PROJECT_MESSAGE =
  *
  * Constructor deps:
  * - `session` — encapsulates all mutable session state and lifecycle operations
- * - `resolver` — owns permission-query surface: `getConfigIssues`
+ * - `policyIssues` — reports what composing policy revealed (a fail-closed clamp,
+ *   a port notice) for the agent the session names, latched per notice; driven
+ *   here and on every turn, so a clamp caused mid-session is explained (#953)
  * - `serviceLifecycle` — owns the process-global service publication;
  *   `activate` publishes (skipped for registered subagent children) and emits
  *   the ready event; `teardown` unsubscribes all session listeners and unpublishes
@@ -56,7 +58,7 @@ export const UNTRUSTED_PROJECT_MESSAGE =
 export class SessionLifecycleHandler {
   constructor(
     private readonly session: PermissionSession,
-    private readonly resolver: PermissionResolver,
+    private readonly policyIssues: PolicyIssueReporting,
     private readonly serviceLifecycle: ServiceLifecycle,
     private readonly logger: SessionLogger,
     private readonly audit: DecisionSummaryWriter,
@@ -84,10 +86,7 @@ export class SessionLifecycleHandler {
     }
 
     const agentName = this.session.resolveAgentName(ctx);
-    const policyIssues = this.resolver.getConfigIssues(agentName ?? undefined);
-    for (const issue of policyIssues) {
-      this.logger.warn(issue);
-    }
+    this.policyIssues.report(agentName ?? undefined);
 
     if (event.reason === "reload") {
       this.logger.debug("lifecycle.reload", {

package/src/index.ts

@@ -41,6 +41,7 @@ import { ConfigStore } from "#src/config/config-store";
 import { resolveDialogKeys } from "#src/config/dialog-keys";
 import { isYoloModeEnabled } from "#src/config/extension-config";
 import { computeExtensionPaths } from "#src/config/extension-paths";
+import { PolicyIssueReporter } from "#src/config/policy-issue-reporter";
 import { GateRunner } from "#src/handlers/gates/runner";
 import { SkillInputGatePipeline } from "#src/handlers/gates/skill-input-gate-pipeline";
 import { ToolCallGatePipeline } from "#src/handlers/gates/tool-call-gate-pipeline";
@@ -322,9 +323,12 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   // was recorded as delivered and never shown (#933). Driven at session_start
   // and on every turn; the latch keeps an unchanged issue quiet.
   const configIssueReporter = new ConfigIssueReporter(configStore, logger);
+  // What composing policy revealed (a fail-closed clamp, a port notice) is
+  // agent-scoped, so each driver hands over the agent name it resolved (#953).
+  const policyIssueReporter = new PolicyIssueReporter(resolver, logger);
   const lifecycle = new SessionLifecycleHandler(
     session,
-    resolver,
+    policyIssueReporter,
     serviceLifecycle,
     logger,
     audit,
@@ -346,6 +350,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     toolRegistry,
     logger,
     subagentDetection,
+    policyIssueReporter,
   );
 
   const gateRunner = new GateRunner(

package/src/policy/permission-manager.ts

@@ -62,12 +62,12 @@ type ResolvedPermissions = {
   /**
    * Non-global scopes whose config file failed to load or validate. When
    * non-empty the composed ruleset has been floored allow→ask (#646); the
-   * names also drive the fail-closed notice in {@link getConfigIssues}.
+   * names also drive the fail-closed notice in {@link getPolicyIssues}.
    */
   failClosedScopes: RuleOrigin[];
   /**
    * Top-level permission keys naming Pi MCP tools, relocated onto the `mcp`
-   * surface; they drive the port notice in {@link getConfigIssues}.
+   * surface; they drive the port notice in {@link getPolicyIssues}.
    */
   legacyMcpToolKeys: string[];
 };
@@ -92,7 +92,7 @@ export interface ScopedPermissionManager {
   ): PermissionCheckResult;
   getToolPermission(toolName: string, agentName?: string): PermissionState;
   isToolFullyDenied(toolName: string, agentName?: string): boolean;
-  getConfigIssues(agentName?: string): string[];
+  getPolicyIssues(agentName?: string): string[];
 }
 
 export interface PermissionManagerOptions extends PolicyLoaderOptions {
@@ -158,11 +158,20 @@ export class PermissionManager implements ScopedPermissionManager {
     this.resolvedPermissionsCache.clear();
   }
 
-  getConfigIssues(agentName?: string): string[] {
-    // Trigger a load/resolve to ensure issues are collected.
+  /**
+   * What composing `agentName`'s policy revealed: the fail-closed notice for
+   * a rejected non-global scope and the port notice for relocated MCP tool
+   * keys. Recomputed on every resolve, so a notice disappears once its cause is
+   * fixed.
+   *
+   * A config file's own schema errors are not here: `ConfigStore` loads the
+   * same files through the same `loadUnifiedConfig` and owns reporting them,
+   * so listing them here too showed the operator each one twice (#953).
+   */
+  getPolicyIssues(agentName?: string): string[] {
     const { failClosedScopes, legacyMcpToolKeys } =
       this.resolvePermissions(agentName);
-    const issues = [...this.loader.getConfigIssues()];
+    const issues: string[] = [];
     if (failClosedScopes.length > 0) {
       issues.push(
         `Invalid ${failClosedScopes.join(", ")} configuration detected — ` +

package/src/policy/permission-resolver.ts

@@ -4,6 +4,7 @@ import type {
   ResolvedAccessIntent,
 } from "#src/access-intent/access-intent";
 import { surfaceFamilyMembers } from "#src/access-intent/path-surfaces";
+import type { PolicyIssueSource } from "#src/config/policy-issue-reporter";
 import type { SkillPermissionChecker } from "#src/exposure/skill-prompt-sanitizer";
 import type { SessionRules } from "#src/session/session-rules";
 import type { PermissionCheckResult, PermissionState } from "#src/types";
@@ -64,7 +65,7 @@ function toResolvedIntent(
  * - `sessionRules` — narrowed to `getRuleset` (ISP: the resolver only reads, never records)
  */
 export class PermissionResolver
-  implements ScopedPermissionResolver, SkillPermissionChecker
+  implements ScopedPermissionResolver, SkillPermissionChecker, PolicyIssueSource
 {
   constructor(
     private readonly permissionManager: ScopedPermissionManager,
@@ -139,7 +140,7 @@ export class PermissionResolver
     return this.permissionManager.isToolFullyDenied(toolName, agentName);
   }
 
-  getConfigIssues(agentName?: string): string[] {
-    return this.permissionManager.getConfigIssues(agentName);
+  getPolicyIssues(agentName?: string): string[] {
+    return this.permissionManager.getPolicyIssues(agentName);
   }
 }