@gotgenes/pi-permission-system 20.10.0 → 21.0.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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).
 
+## [21.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.10.0...pi-permission-system-v21.0.0) (2026-07-24)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** A session whose project/agent/project-agent config is invalid previously inherited a lower scope's `allow` rules unchanged; those surfaces now resolve to `ask` (prompt) until the invalid config is corrected. Only sessions that already emit a config-validation warning are affected. Fix the reported config issues and reload to restore the intended policy.
+
+### Features
+
+* **pi-permission-system:** add floorAllowsToAsk allow→ask overlay ([#646](https://github.com/gotgenes/pi-packages/issues/646)) ([8dbdcd7](https://github.com/gotgenes/pi-packages/commit/8dbdcd75bd8c6f62528d0466f93cfefa039f3d4b))
+* **pi-permission-system:** mark invalid non-global config scopes ([#646](https://github.com/gotgenes/pi-packages/issues/646)) ([1abd318](https://github.com/gotgenes/pi-packages/commit/1abd3182b7c1b6304d0ef28acfbb59c470508a43))
+
+
+### Bug Fixes
+
+* **pi-permission-system:** fail closed when a higher-precedence config scope is invalid ([#646](https://github.com/gotgenes/pi-packages/issues/646)) ([b3c11c0](https://github.com/gotgenes/pi-packages/commit/b3c11c0984b7d9849349c5d8d0f1de111d1c7a03))
+
+
+### Documentation
+
+* **pi-permission-system:** document cross-scope fail-closed config clamp ([#646](https://github.com/gotgenes/pi-packages/issues/646)) ([7903b4c](https://github.com/gotgenes/pi-packages/commit/7903b4cc15710618a6f0ed5cc302687af18db4be))
+
 ## [20.10.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.9.1...pi-permission-system-v20.10.0) (2026-07-21)
 
 

package/README.md

@@ -129,17 +129,17 @@ If you relied on the old permissive behavior for bash, set an explicit permissiv
 
 ## Documentation
 
-| Document                                                                                                                       | Contents                                                                                |
-| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
-| [docs/configuration.md](docs/configuration.md)                                                                                 | Full policy reference, runtime knobs, per-agent overrides, recipes                      |
-| [docs/session-approvals.md](docs/session-approvals.md)                                                                         | Session-scoped rules, pattern suggestions, bash arity table                             |
-| [docs/cross-extension-api.md](docs/cross-extension-api.md)                                                                     | Cross-extension service accessor, event bus integration, prompt and decision broadcasts |
-| [docs/subagent-integration.md](docs/subagent-integration.md)                                                                   | Permission forwarding, coexistence with subagent extensions                             |
-| [docs/guides/permission-frontmatter-for-subagent-extensions.md](docs/guides/permission-frontmatter-for-subagent-extensions.md) | Convention guide for subagent extension authors                                         |
-| [docs/opencode-compatibility.md](docs/opencode-compatibility.md)                                                               | OpenCode compatibility — shared concepts, divergences, porting guide                    |
-| [docs/troubleshooting.md](docs/troubleshooting.md)                                                                             | Common issues, diagnostic logging, threat model                                         |
-| [docs/migration/legacy-to-flat.md](docs/migration/legacy-to-flat.md)                                                           | Migration from pre-v2 config layout                                                     |
-| [docs/migration/strict-config-validation.md](docs/migration/strict-config-validation.md)                                       | Strict config validation (breaking) — reading and fixing rejected configs               |
+| Document                                                                                                                       | Contents                                                                                      |
+| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| [docs/configuration.md](docs/configuration.md)                                                                                 | Full policy reference, runtime knobs, per-agent overrides, recipes                            |
+| [docs/session-approvals.md](docs/session-approvals.md)                                                                         | Session-scoped rules, pattern suggestions, bash arity table                                   |
+| [docs/cross-extension-api.md](docs/cross-extension-api.md)                                                                     | Cross-extension service accessor, event bus integration, prompt and decision broadcasts       |
+| [docs/subagent-integration.md](docs/subagent-integration.md)                                                                   | Permission forwarding, coexistence with subagent extensions                                   |
+| [docs/guides/permission-frontmatter-for-subagent-extensions.md](docs/guides/permission-frontmatter-for-subagent-extensions.md) | Convention guide for subagent extension authors                                               |
+| [docs/opencode-compatibility.md](docs/opencode-compatibility.md)                                                               | OpenCode compatibility — shared concepts, divergences, porting guide                          |
+| [docs/troubleshooting.md](docs/troubleshooting.md)                                                                             | Common issues, diagnostic logging, threat model                                               |
+| [docs/migration/legacy-to-flat.md](docs/migration/legacy-to-flat.md)                                                           | Migration from pre-v2 config layout                                                           |
+| [docs/migration/strict-config-validation.md](docs/migration/strict-config-validation.md)                                       | Strict config validation (breaking) — rejected configs, and the cross-scope fail-closed clamp |
 
 ## Development
 

package/dist/public.d.ts

@@ -86,9 +86,11 @@ type PermissionState = z.infer<typeof permissionStateSchema>;
  * Synthesized:   "builtin" (universal default / evaluate() fallback),
  *                "baseline" (conditional MCP metadata auto-allow).
  * Runtime:       "session" (session approvals).
- * Rewrite:       "yolo" (composition-stage ask→allow rewrite under yolo mode).
+ * Rewrite:       "yolo" (composition-stage ask→allow rewrite under yolo mode),
+ *                "fail-closed" (composition-stage allow→ask floor when an
+ *                invalid non-global config scope is detected).
  */
-type RuleOrigin = "global" | "project" | "agent" | "project-agent" | "builtin" | "baseline" | "session" | "yolo";
+type RuleOrigin = "global" | "project" | "agent" | "project-agent" | "builtin" | "baseline" | "session" | "yolo" | "fail-closed";
 
 /**
  * Execution context of a bash command nested inside a substitution or subshell.

package/docs/configuration.md

@@ -32,6 +32,14 @@ Project config overrides global config; per-agent frontmatter overrides both.
 The `permission` object uses deep-shallow merge: string-vs-string replaces; both-object shallow-merges pattern maps; string-vs-object the override wins entirely.
 Scalar fields (`debugLog`, `permissionReviewLog`, `yoloMode`, `doublePressToConfirm`) use simple replacement.
 
+**Invalid higher-precedence scope fails closed.**
+If a non-global scope (project config, global agent frontmatter, or project agent frontmatter) is present but fails to load or validate, it no longer contributes an empty scope that silently inherits the lower scope's rules.
+Instead the effective policy is floored so nothing resolves more permissively than `ask`: every `allow` (including one inherited from a lower scope) is clamped to `ask`, while `deny` and `ask` are unchanged.
+So a global `bash: allow` cannot remain effective behind a project scope that was meant to deny bash but contains a typo — bash prompts until the invalid config is fixed.
+A validation warning plus a distinct fail-closed notice are emitted, and a fix + reload restores the intended policy.
+An invalid **global** scope does not trigger the clamp — it is the lowest precedence, so nothing more permissive is inherited when it fails.
+This clamp is deny-preserving and, like `yoloMode`, applied at composition; when `yoloMode` is on it re-permits the floored `ask` back to `allow`, since yolo is an explicit full-permissive opt-in.
+
 ## Full Example
 
 ```jsonc

package/docs/migration/strict-config-validation.md

@@ -11,11 +11,25 @@ For example, a config with `"debugLog": "yes"` (a string, not a boolean) simply
 The loader is now **strict and fail-closed**:
 
 - A config file with **any** invalid field is rejected as a whole scope (global or project).
-- The rejected scope contributes **no** permission rules, so its surfaces fall back to the safe universal `ask` default — never `allow`.
+- The rejected scope contributes **no** permission rules.
 - Each problem is reported as a clear, path-qualified issue in the permission review log (and the debug log when `debugLog` is on).
 
 Nothing about the config **format** changed — a config that was already valid keeps working unchanged.
 
+## Cross-scope hardening (fail closed on an invalid higher scope)
+
+Rejecting a scope's rules is only half the story.
+Because a higher-precedence scope that contributes no rules leaves the **lower** scope's rules in place, an invalid *higher* scope used to silently inherit the lower scope's policy — including a permissive `allow`.
+For example, a global `bash: allow` remained effective even when a project config meant to deny bash but contained a typo.
+
+The loader now fails closed across scopes as well: when a **non-global** scope (project config, global agent frontmatter, or project agent frontmatter) is present but invalid, the effective policy is floored so nothing resolves more permissively than `ask`.
+Every `allow` — including one inherited from a lower scope — is clamped to `ask`; `deny` and `ask` are unchanged.
+Alongside the per-problem validation issues, a distinct notice is reported: `Invalid <scope> configuration detected — failing closed: 'allow' rules are clamped to 'ask' …`.
+
+An invalid **global** scope does not trigger the cross-scope clamp — it is the lowest precedence, so nothing more permissive is inherited when it fails.
+The clamp is deny-preserving, and (like `yoloMode`) applied at composition; when `yoloMode` is on it re-permits the floored `ask` back to `allow`.
+Fix the reported problems and reload to restore the intended policy.
+
 ## What you need to do
 
 If your config was valid, nothing.

package/package.json

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

package/src/permission-manager.ts

@@ -21,6 +21,7 @@ import {
   evaluate,
   evaluateAnyValue,
   evaluateFirst,
+  floorAllowsToAsk,
   pathMatchOptions,
   rewriteAsksToYolo,
 } from "./rule";
@@ -61,6 +62,12 @@ type ResolvedPermissions = {
    * Session rules are appended at call-time inside check().
    */
   composedRules: Ruleset;
+  /**
+   * 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}.
+   */
+  failClosedScopes: RuleOrigin[];
 };
 
 /**
@@ -159,8 +166,16 @@ export class PermissionManager implements ScopedPermissionManager {
 
   getConfigIssues(agentName?: string): string[] {
     // Trigger a load/resolve to ensure issues are collected.
-    this.resolvePermissions(agentName);
-    return [...this.loader.getConfigIssues()];
+    const { failClosedScopes } = this.resolvePermissions(agentName);
+    const issues = [...this.loader.getConfigIssues()];
+    if (failClosedScopes.length > 0) {
+      issues.push(
+        `Invalid ${failClosedScopes.join(", ")} configuration detected — ` +
+          `failing closed: 'allow' rules are clamped to 'ask' for this session ` +
+          `until the configuration is corrected.`,
+      );
+    }
+    return issues;
   }
 
   getResolvedPolicyPaths(): ResolvedPolicyPaths {
@@ -222,7 +237,25 @@ export class PermissionManager implements ScopedPermissionManager {
       configRules,
     );
 
-    const value: ResolvedPermissions = { composedRules };
+    // Fail closed when a non-global scope's config is invalid: floor every
+    // `allow` (including one inherited from a lower scope) to `ask` so a
+    // higher scope meant to tighten policy cannot silently fail open (#646).
+    // Global is excluded — nothing more permissive is inherited when it fails.
+    const failClosedScopes: RuleOrigin[] = [];
+    if (projectConfig.invalid === true) failClosedScopes.push("project");
+    if (agentConfig.invalid === true) failClosedScopes.push("agent");
+    if (projectAgentConfig.invalid === true)
+      failClosedScopes.push("project-agent");
+
+    const effectiveRules =
+      failClosedScopes.length > 0
+        ? floorAllowsToAsk(composedRules)
+        : composedRules;
+
+    const value: ResolvedPermissions = {
+      composedRules: effectiveRules,
+      failClosedScopes,
+    };
     this.resolvedPermissionsCache.set(cacheKey, { stamp, value });
     return value;
   }

package/src/policy-loader.ts

@@ -232,8 +232,11 @@ 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.
     const value: ScopeConfig = {
       permission: config.permission,
+      ...(issues.length > 0 ? { invalid: true } : {}),
     };
 
     this.projectGlobalConfigCache = { stamp, value };
@@ -256,6 +259,14 @@ export class FilePolicyLoader implements PolicyLoader {
       return cached.value;
     }
 
+    // An absent file (stat failed) is a legitimately-empty scope, not invalid;
+    // only a present-but-unreadable file fails closed.
+    if (stamp === "missing") {
+      const value: ScopeConfig = {};
+      cache.set(agentName, { stamp, value });
+      return value;
+    }
+
     let value: ScopeConfig;
     try {
       const markdown = readFileSync(filePath, "utf-8");
@@ -273,7 +284,9 @@ export class FilePolicyLoader implements PolicyLoader {
         };
       }
     } catch {
-      value = {};
+      // The file exists (stat succeeded above) but could not be read or
+      // parsed — fail closed for this scope (#646).
+      value = { invalid: true };
     }
 
     cache.set(agentName, { stamp, value });

package/src/rule.ts

@@ -11,7 +11,9 @@ import { type WildcardMatchOptions, wildcardMatch } from "./wildcard-matcher";
  * Synthesized:   "builtin" (universal default / evaluate() fallback),
  *                "baseline" (conditional MCP metadata auto-allow).
  * Runtime:       "session" (session approvals).
- * Rewrite:       "yolo" (composition-stage ask→allow rewrite under yolo mode).
+ * Rewrite:       "yolo" (composition-stage ask→allow rewrite under yolo mode),
+ *                "fail-closed" (composition-stage allow→ask floor when an
+ *                invalid non-global config scope is detected).
  */
 export type RuleOrigin =
   | "global"
@@ -21,7 +23,8 @@ export type RuleOrigin =
   | "builtin"
   | "baseline"
   | "session"
-  | "yolo";
+  | "yolo"
+  | "fail-closed";
 
 /** A single permission rule — the atomic unit of policy. */
 export interface Rule {
@@ -63,6 +66,28 @@ export function rewriteAsksToYolo(rules: Ruleset): Ruleset {
   );
 }
 
+/**
+ * Floor every `allow` rule to `ask`, tagged `origin: "fail-closed"`.
+ *
+ * The mirror image of {@link rewriteAsksToYolo}: the composition-stage
+ * expression of the fail-closed clamp applied when an invalid non-global config
+ * scope is detected. A permissive `allow` inherited from a lower-precedence
+ * scope becomes an `ask` prompt rather than a silent grant, while `deny` and
+ * existing `ask` rules pass through untouched — so the clamp removes only
+ * permissive inheritance and never weakens a hard deny.
+ *
+ * Pure and non-mutating — `surface`, `pattern`, and `layer` are preserved so
+ * downstream `matchedPattern` / source derivation is unaffected; only `action`
+ * and `origin` change.
+ */
+export function floorAllowsToAsk(rules: Ruleset): Ruleset {
+  return rules.map((rule) =>
+    rule.action === "allow"
+      ? { ...rule, action: "ask", origin: "fail-closed" }
+      : rule,
+  );
+}
+
 /**
  * Pure permission evaluation.
  *

package/src/types.ts

@@ -34,6 +34,13 @@ export type PathRuleTokenMatcher = (token: string) => boolean;
  */
 export interface ScopeConfig {
   permission?: FlatPermissionConfig;
+  /**
+   * True when the scope's config file was present but failed to load or
+   * validate (JSON parse error or schema rejection). Absent and valid files
+   * leave this unset. Drives the fail-closed allow→ask clamp for non-global
+   * scopes (#646).
+   */
+  invalid?: boolean;
 }
 
 /**