@gotgenes/pi-permission-system 20.9.1 → 21.0.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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)
+
+
+### Features
+
+* **pi-permission-system:** thread a review-log seam into the authorizer chain ([b086474](https://github.com/gotgenes/pi-packages/commit/b086474e91c79b02632ee76bbaa3e72e39f29e40))
+
 ## [20.9.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.9.0...pi-permission-system-v20.9.1) (2026-07-20)
 
 

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.
@@ -217,10 +219,12 @@ type AuthorizerVerdict = {
  * decide it or defer to the next link (ADR 0007). The chain injects a narrow,
  * session-scoped {@link PermissionQuery} at `authorize` time (§3), so a link
  * queries the deterministic engine at gate parity rather than reaching for the
- * cross-extension service via `Symbol.for()`.
+ * cross-extension service via `Symbol.for()`. It also injects an
+ * {@link AuthorizerLog} so a link can record its decision trail to the shared
+ * permission review log (same §3 injection pattern).
  */
 interface Authorizer {
-    authorize(details: PromptPermissionDetails, query: PermissionQuery): Promise<AuthorizerVerdict>;
+    authorize(details: PromptPermissionDetails, query: PermissionQuery, log: AuthorizerLog): Promise<AuthorizerVerdict>;
 }
 
 /**
@@ -257,6 +261,22 @@ type ToolInputFormatter = (input: Record<string, unknown>) => string | undefined
  * reference — this ensures resilience across `/reload` and load-order edge cases.
  */
 
+/**
+ * The narrow review-log seam handed to a chain link at `authorize` time
+ * (ADR 0007 §3, same injection pattern as {@link PermissionQuery}).
+ *
+ * A link uses it to record a positive decision trail to the permission review
+ * log — `review` for the durable, default-on audit entry (one per handled
+ * ask), `debug` for verbose or short-circuit detail gated behind the
+ * `debugLog` toggle. The session's own logger is passed straight through, so a
+ * link's entries land in the same `pi-permission-system-permission-review.jsonl`
+ * as the gate decisions, keying to a gate entry by `requestId`.
+ */
+interface AuthorizerLog {
+    review(event: string, details?: Record<string, unknown>): void;
+    debug(event: string, details?: Record<string, unknown>): void;
+}
+
 /**
  * The narrow, read-only projection of {@link PermissionsService}: answer a
  * policy query for a surface, and report a tool-level state. This is the
@@ -348,7 +368,10 @@ interface PermissionsService extends PermissionQuery {
      * throws. The returned disposer unregisters the link.
      *
      * @param name      - Operator-facing link name referenced from `authorizerChain`.
-     * @param authorize - The link's decision callback (`(details, query) => verdict`).
+     * @param authorize - The link's decision callback
+     *                    (`(details, query, log) => verdict`); `log` is an
+     *                    {@link AuthorizerLog} for recording a decision trail to
+     *                    the shared permission review log.
      */
     registerAuthorizer(name: string, authorize: Authorizer["authorize"]): () => void;
 }
@@ -383,4 +406,4 @@ declare function getPermissionsService(): PermissionsService | undefined;
 declare function unpublishPermissionsService(service: PermissionsService): void;
 
 export { PERMISSIONS_DECISION_CHANNEL, PERMISSIONS_READY_CHANNEL, PERMISSIONS_UI_PROMPT_CHANNEL, getPermissionsService, publishPermissionsService, unpublishPermissionsService };
-export type { Authorizer, AuthorizerVerdict, ForwardedPromptContext, PermissionCheckResult, PermissionDecisionEvent, PermissionQuery, PermissionState, PermissionUiPromptEvent, PermissionUiPromptSource, PermissionsReadyEvent, PermissionsService, PromptPermissionDetails, ToolInputFormatter };
+export type { Authorizer, AuthorizerLog, AuthorizerVerdict, ForwardedPromptContext, PermissionCheckResult, PermissionDecisionEvent, PermissionQuery, PermissionState, PermissionUiPromptEvent, PermissionUiPromptSource, PermissionsReadyEvent, PermissionsService, PromptPermissionDetails, ToolInputFormatter };

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.9.1",
+  "version": "21.0.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/src/authority/authorizer-chain.ts

@@ -1,4 +1,4 @@
-import type { PermissionQuery } from "#src/service";
+import type { AuthorizerLog, PermissionQuery } from "#src/service";
 import type {
   Authorizer,
   AuthorizerVerdict,
@@ -16,16 +16,18 @@ import { createDeniedPermissionDecision } from "./permission-dialog";
  * (returns a full decision), so a deferring link cannot occupy the terminal
  * slot.
  *
- * Each link is handed the session-scoped `query` at `authorize` time (ADR 0007
- * §3) so it queries the deterministic engine at gate parity; the terminal never
- * queries. With zero links the composed chain **is** the terminal instance
- * (identity), so behavior is byte-identical to the pre-chain spine — the
- * empty-links case that ships until a link registers.
+ * Each link is handed the session-scoped `query` and the review-log `log` at
+ * `authorize` time (ADR 0007 §3) so it queries the deterministic engine at gate
+ * parity and records its decision trail; the terminal receives neither. With
+ * zero links the composed chain **is** the terminal instance (identity), so
+ * behavior is byte-identical to the pre-chain spine — the empty-links case that
+ * ships until a link registers.
  */
 export function composeAuthorizerChain(
   links: readonly Authorizer[],
   terminal: TerminalAuthorizer,
   query: PermissionQuery,
+  log: AuthorizerLog,
 ): TerminalAuthorizer {
   if (links.length === 0) {
     return terminal;
@@ -33,7 +35,7 @@ export function composeAuthorizerChain(
   return {
     async authorize(details) {
       for (const link of links) {
-        const verdict = await link.authorize(details, query);
+        const verdict = await link.authorize(details, query, log);
         const decision = decideFromVerdict(verdict);
         if (decision) {
           return decision;

package/src/authority/authorizer-selection.ts

@@ -126,6 +126,7 @@ export class AuthorizerSelection
       this.resolveConfiguredLinks(),
       this.terminal,
       this.deps.getPermissionQuery(),
+      this.deps.logger,
     );
     return this.deps.prompter.prompt(chain, details);
   }

package/src/authority/authorizer.ts

@@ -6,7 +6,7 @@ import type {
 } from "#src/authority/permission-prompt-component";
 import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
 import type { PermissionEventBus } from "#src/permission-events";
-import type { PermissionQuery } from "#src/service";
+import type { AuthorizerLog, PermissionQuery } from "#src/service";
 import type { DebugReviewLogger } from "#src/session-logger";
 import { ParentAuthorizer } from "./approval-escalator";
 import { DenyingAuthorizer } from "./denying-authorizer";
@@ -29,12 +29,15 @@ export type AuthorizerVerdict =
  * decide it or defer to the next link (ADR 0007). The chain injects a narrow,
  * session-scoped {@link PermissionQuery} at `authorize` time (§3), so a link
  * queries the deterministic engine at gate parity rather than reaching for the
- * cross-extension service via `Symbol.for()`.
+ * cross-extension service via `Symbol.for()`. It also injects an
+ * {@link AuthorizerLog} so a link can record its decision trail to the shared
+ * permission review log (same §3 injection pattern).
  */
 export interface Authorizer {
   authorize(
     details: PromptPermissionDetails,
     query: PermissionQuery,
+    log: AuthorizerLog,
   ): Promise<AuthorizerVerdict>;
 }
 

package/src/authority/delegation-envelope.ts

@@ -26,13 +26,14 @@ export const DELEGATION_EXCLUDED_SURFACES: ReadonlySet<string> = new Set([
 /**
  * Wrap a link's `authorize` so an `allow` on an excluded surface is capped to
  * `defer`. All other verdicts, and `allow`s on non-excluded surfaces, pass
- * through unchanged. `details` and the injected `query` are forwarded as-is.
+ * through unchanged. `details`, the injected `query`, and the review-log `log`
+ * are forwarded as-is.
  */
 export function encloseInDelegationEnvelope(
   authorize: Authorizer["authorize"],
 ): Authorizer["authorize"] {
-  return async (details, query) => {
-    const verdict = await authorize(details, query);
+  return async (details, query, log) => {
+    const verdict = await authorize(details, query, log);
     if (verdict.kind === "allow" && isExcludedSurface(details)) {
       return { kind: "defer" };
     }

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/service.ts

@@ -20,6 +20,22 @@ export type {
   Authorizer,
   AuthorizerVerdict,
 } from "./authority/authorizer";
+
+/**
+ * The narrow review-log seam handed to a chain link at `authorize` time
+ * (ADR 0007 §3, same injection pattern as {@link PermissionQuery}).
+ *
+ * A link uses it to record a positive decision trail to the permission review
+ * log — `review` for the durable, default-on audit entry (one per handled
+ * ask), `debug` for verbose or short-circuit detail gated behind the
+ * `debugLog` toggle. The session's own logger is passed straight through, so a
+ * link's entries land in the same `pi-permission-system-permission-review.jsonl`
+ * as the gate decisions, keying to a gate entry by `requestId`.
+ */
+export interface AuthorizerLog {
+  review(event: string, details?: Record<string, unknown>): void;
+  debug(event: string, details?: Record<string, unknown>): void;
+}
 export type { PromptPermissionDetails } from "./authority/permission-prompter";
 export type {
   ForwardedPromptContext,
@@ -143,7 +159,10 @@ export interface PermissionsService extends PermissionQuery {
    * throws. The returned disposer unregisters the link.
    *
    * @param name      - Operator-facing link name referenced from `authorizerChain`.
-   * @param authorize - The link's decision callback (`(details, query) => verdict`).
+   * @param authorize - The link's decision callback
+   *                    (`(details, query, log) => verdict`); `log` is an
+   *                    {@link AuthorizerLog} for recording a decision trail to
+   *                    the shared permission review log.
    */
   registerAuthorizer(
     name: string,

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;
 }
 
 /**