@gotgenes/pi-permission-system 20.9.0 → 20.10.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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).
 
+## [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)
+
+
+### Documentation
+
+* **pi-permission-system:** cite pi-permission-model-judge as a registerAuthorizer example ([6bc1e67](https://github.com/gotgenes/pi-packages/commit/6bc1e6710ea70c7d95b87d77fb4e744f0b81e614))
+
 ## [20.9.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.8.0...pi-permission-system-v20.9.0) (2026-07-19)
 
 

package/README.md

@@ -114,6 +114,7 @@ The optional `shellTools` field records which non-`bash` tools carry shell seman
 
 The optional `authorizerChain` field names registered case-by-case decision links (e.g. a light model judge) to consult when a request lands on `ask`, ahead of the interactive prompt.
 A downstream extension registers a link via `getPermissionsService().registerAuthorizer(name, authorize)`; it decides nothing until you name it here (opt-in), config order fixes the chain order, and the chain owner caps any link's `allow` on `external_directory`/`path` to keep it within your policy — see [docs/configuration.md](docs/configuration.md#authorizer-chain--case-by-case-decision-links).
+[`@gotgenes/pi-permission-model-judge`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-model-judge) is a first-party reference implementation of such a link — a deny-first reviewer that auto-denies mistyped out-of-directory paths.
 
 For the full reference — all surfaces, runtime knobs, per-agent overrides, merge semantics, and common recipes — see [docs/configuration.md](docs/configuration.md).
 

package/dist/public.d.ts

@@ -217,10 +217,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 +259,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 +366,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 +404,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

@@ -194,6 +194,7 @@ Deny and defer are never capped.
 
 Extension authors: register a link from a `permissions:ready` handler via `getPermissionsService().registerAuthorizer(name, authorize)`; the callback receives the ask details and a narrow, session-scoped `PermissionQuery` (`checkPermission` / `getToolPermission`) so it can consult the deterministic engine at gate parity.
 Registration returns a disposer, and only one link may hold a given name.
+For a complete working example, see [`@gotgenes/pi-permission-model-judge`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-model-judge): it registers a `model-judge` link on `permissions:ready` that reviews `external_directory` asks and auto-denies mistyped paths with a corrective reason.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "20.9.0",
+  "version": "20.10.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/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,