@gotgenes/pi-permission-system 3.8.0 → 3.10.0

package/CHANGELOG.md

@@ -5,6 +5,43 @@ 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).
 
+## [3.10.0](https://github.com/gotgenes/pi-permission-system/compare/v3.9.0...v3.10.0) (2026-05-04)
+
+
+### Features
+
+* migrate tool_call external_directory to SessionRules ([42c2bd9](https://github.com/gotgenes/pi-permission-system/commit/42c2bd91dbc35c6e4343133fb907f43a6a2550bf))
+* remove SessionApprovalCache ([9d5a5be](https://github.com/gotgenes/pi-permission-system/commit/9d5a5be8251491a66b2826183ca22cbd5a232374))
+* replace SessionApprovalCache with SessionRules in runtime ([4cec9c5](https://github.com/gotgenes/pi-permission-system/commit/4cec9c553779afa8a5fb62bf2ffbd35a43af3e23))
+
+
+### Documentation
+
+* plan replace SessionApprovalCache with session Ruleset ([#57](https://github.com/gotgenes/pi-permission-system/issues/57)) ([ed1cefe](https://github.com/gotgenes/pi-permission-system/commit/ed1cefec2fd81542084460eb02cd3706b7093c07))
+* **retro:** add retro notes for issue [#56](https://github.com/gotgenes/pi-permission-system/issues/56) ([f97f65c](https://github.com/gotgenes/pi-permission-system/commit/f97f65c448bd907866042bf9804378f441ae7c36))
+* update session approval references ([#57](https://github.com/gotgenes/pi-permission-system/issues/57)) ([40e5e89](https://github.com/gotgenes/pi-permission-system/commit/40e5e89bf29b404b36fedaa48c896391d30574f6))
+
+## [3.9.0](https://github.com/gotgenes/pi-permission-system/compare/v3.8.0...v3.9.0) (2026-05-03)
+
+
+### Features
+
+* add normalizeConfig and defaults modules ([84f9c3e](https://github.com/gotgenes/pi-permission-system/commit/84f9c3ef1c665e8d55b694ecf8bbec2dff41b093))
+* evaluate() accepts optional defaultAction parameter ([69dde81](https://github.com/gotgenes/pi-permission-system/commit/69dde81d05722065307b04102a8af6935df0e17c))
+
+
+### Bug Fixes
+
+* remove unused imports flagged by biome ([62704a3](https://github.com/gotgenes/pi-permission-system/commit/62704a3b5c833af74a3bd27942ffc4247c92c12c))
+
+
+### Documentation
+
+* mark [#42](https://github.com/gotgenes/pi-permission-system/issues/42) and [#43](https://github.com/gotgenes/pi-permission-system/issues/43) complete in target architecture ([04430f2](https://github.com/gotgenes/pi-permission-system/commit/04430f2ea000e9607541262a71ad2be633dc7bb6))
+* mark [#56](https://github.com/gotgenes/pi-permission-system/issues/56) complete in target architecture ([2fe95c5](https://github.com/gotgenes/pi-permission-system/commit/2fe95c577ec97e78c1390db91020294ba25662e0))
+* plan unify Rule type and normalize config into flat Ruleset ([#56](https://github.com/gotgenes/pi-permission-system/issues/56)) ([61e8c48](https://github.com/gotgenes/pi-permission-system/commit/61e8c4800f39a173b69f2773e8b2f09fa9c7318b))
+* **retro:** add retro notes for issue [#43](https://github.com/gotgenes/pi-permission-system/issues/43) ([bd6aea6](https://github.com/gotgenes/pi-permission-system/commit/bd6aea6ed2e1dfdad1ef610f9abb8319d87460cd))
+
 ## [3.8.0](https://github.com/gotgenes/pi-permission-system/compare/v3.7.0...v3.8.0) (2026-05-03)
 
 

package/README.md

@@ -529,7 +529,7 @@ This makes it easy to verify which files the extension actually loaded:
 index.ts                    → Root Pi entrypoint shim
 src/
 ├── index.ts                → Extension bootstrap, permission checks, readable prompts, review logging, reload handling, and subagent forwarding
-├── session-approval-cache.ts → Ephemeral session-scoped approval cache for external-directory access
+├── session-rules.ts          → Ephemeral session-scoped approval rules (Ruleset-based, external-directory access)
 ├── config-loader.ts        → Unified config loader, merger, and legacy-path detection
 ├── config-paths.ts         → Path derivation for global, project, and legacy config locations
 ├── config-reporter.ts      → Resolved config path reporting for diagnostic logs

package/package.json

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

package/src/defaults.ts

@@ -0,0 +1,60 @@
+import type { PermissionDefaultPolicy, PermissionState } from "./types";
+
+/** Hardcoded fallback — every surface defaults to "ask" (least privilege). */
+export const DEFAULT_POLICY: PermissionDefaultPolicy = {
+  tools: "ask",
+  bash: "ask",
+  mcp: "ask",
+  skills: "ask",
+  special: "ask",
+};
+
+/**
+ * Map a surface name used in evaluate() to the corresponding
+ * defaultPolicy key. Surfaces not listed here fall through to
+ * either "tools" or "special" via getSurfaceDefault().
+ */
+const SURFACE_TO_DEFAULT_KEY: Record<string, keyof PermissionDefaultPolicy> = {
+  bash: "bash",
+  mcp: "mcp",
+  skill: "skills",
+};
+
+/**
+ * Resolve the default action for a surface, consulting merged defaults.
+ *
+ * - "bash", "mcp", "skill" → dedicated defaultPolicy key
+ * - special-key surfaces (e.g. "external_directory") → defaults.special
+ * - everything else (tool-name surfaces) → defaults.tools
+ */
+export function getSurfaceDefault(
+  surface: string,
+  defaults: PermissionDefaultPolicy,
+  specialKeys: ReadonlySet<string>,
+): PermissionState {
+  const key = SURFACE_TO_DEFAULT_KEY[surface];
+  if (key) return defaults[key];
+  if (specialKeys.has(surface)) return defaults.special;
+  return defaults.tools;
+}
+
+/**
+ * Merge zero or more partial default policies on top of DEFAULT_POLICY.
+ * Later partials override earlier ones (shallow spread per key).
+ */
+export function mergeDefaults(
+  ...partials: ReadonlyArray<Partial<PermissionDefaultPolicy> | undefined>
+): PermissionDefaultPolicy {
+  const merged: PermissionDefaultPolicy = { ...DEFAULT_POLICY };
+
+  for (const partial of partials) {
+    if (!partial) continue;
+    if (partial.tools) merged.tools = partial.tools;
+    if (partial.bash) merged.bash = partial.bash;
+    if (partial.mcp) merged.mcp = partial.mcp;
+    if (partial.skills) merged.skills = partial.skills;
+    if (partial.special) merged.special = partial.special;
+  }
+
+  return merged;
+}

package/src/handlers/lifecycle.ts

@@ -76,6 +76,6 @@ export async function handleSessionShutdown(deps: HandlerDeps): Promise<void> {
   deps.runtime.activeSkillEntries = [];
   deps.runtime.lastActiveToolsCacheKey = null;
   deps.runtime.lastPromptStateCacheKey = null;
-  deps.runtime.sessionApprovalCache.clear();
+  deps.runtime.sessionRules.clear();
   deps.stopForwardedPermissionPolling();
 }

package/src/handlers/tool-call.ts

@@ -29,7 +29,8 @@ import {
   formatUnknownToolReason,
   formatUserDeniedReason,
 } from "../permission-prompts";
-import { deriveApprovalPrefix } from "../session-approval-cache";
+import { evaluate } from "../rule";
+import { deriveApprovalPattern } from "../session-rules";
 import { findSkillPathMatch } from "../skill-prompt-sanitizer";
 import { getPermissionLogContext } from "../tool-input-preview";
 import {
@@ -169,12 +170,15 @@ export async function handleToolCall(
       externalDirectoryPath,
       ctx.cwd,
     );
-    const sessionPrefix = deps.runtime.sessionApprovalCache.findMatchingPrefix(
+    const sessionRuleset = deps.runtime.sessionRules.getRuleset();
+    const sessionMatch = evaluate(
       "external_directory",
       normalizedExtPath,
+      sessionRuleset,
     );
+    const isSessionApproved = sessionRuleset.includes(sessionMatch);
 
-    if (sessionPrefix) {
+    if (isSessionApproved) {
       deps.runtime.writeReviewLog("permission_request.session_approved", {
         source: "tool_call",
         toolCallId: (event as { toolCallId: string }).toolCallId,
@@ -182,7 +186,7 @@ export async function handleToolCall(
         agentName,
         path: externalDirectoryPath,
         resolution: "session_approved",
-        sessionApprovalPrefix: sessionPrefix,
+        sessionApprovalPattern: sessionMatch.pattern,
       });
       // Fall through to normal permission check
     } else {
@@ -245,8 +249,8 @@ export async function handleToolCall(
       }
 
       if (extDirDecision?.state === "approved_for_session") {
-        const prefix = deriveApprovalPrefix(normalizedExtPath);
-        deps.runtime.sessionApprovalCache.approve("external_directory", prefix);
+        const pattern = deriveApprovalPattern(normalizedExtPath);
+        deps.runtime.sessionRules.approve("external_directory", pattern);
       }
     }
     // Fall through to normal permission check
@@ -261,9 +265,12 @@ export async function handleToolCall(
         ctx.cwd,
       );
       if (externalPaths.length > 0) {
+        const bashSessionRuleset = deps.runtime.sessionRules.getRuleset();
         const uncoveredPaths = externalPaths.filter(
           (p) =>
-            !deps.runtime.sessionApprovalCache.has("external_directory", p),
+            !bashSessionRuleset.includes(
+              evaluate("external_directory", p, bashSessionRuleset),
+            ),
         );
 
         if (uncoveredPaths.length === 0) {
@@ -339,11 +346,8 @@ export async function handleToolCall(
 
           if (bashExtDecision?.state === "approved_for_session") {
             for (const extPath of uncoveredPaths) {
-              const prefix = deriveApprovalPrefix(extPath);
-              deps.runtime.sessionApprovalCache.approve(
-                "external_directory",
-                prefix,
-              );
+              const pattern = deriveApprovalPattern(extPath);
+              deps.runtime.sessionRules.approve("external_directory", pattern);
             }
           }
         }

package/src/index.ts

@@ -11,10 +11,7 @@ import {
   handleSessionStart,
   handleToolCall,
 } from "./handlers";
-import {
-  type PermissionPromptDecision,
-  requestPermissionDecisionFromUi,
-} from "./permission-dialog";
+import { requestPermissionDecisionFromUi } from "./permission-dialog";
 import {
   createExtensionRuntime,
   createPermissionManagerForCwd,

package/src/normalize.ts

@@ -0,0 +1,70 @@
+import type { Rule, Ruleset } from "./rule";
+import type { PermissionState } from "./types";
+
+/**
+ * Subset of UnifiedPermissionConfig covering only policy fields.
+ * Used as the input shape for normalizeConfig().
+ */
+export interface NormalizableConfig {
+  tools?: Record<string, PermissionState>;
+  bash?: Record<string, PermissionState>;
+  mcp?: Record<string, PermissionState>;
+  skills?: Record<string, PermissionState>;
+  special?: Record<string, PermissionState>;
+}
+
+/**
+ * Keys in the `tools` map that serve as fallback defaults for their
+ * respective pattern-based surfaces rather than as tool-level rules.
+ *
+ * `tools.bash` sets the bash default (fallback when no bash pattern matches).
+ * `tools.mcp` sets the tool-level MCP fallback.
+ *
+ * These are NOT normalized into the Ruleset — they are extracted by the
+ * caller and handled as separate fallbacks to preserve the semantic that
+ * specific bash/mcp patterns always have priority.
+ */
+export const TOOL_SURFACE_OVERRIDE_KEYS: ReadonlySet<string> = new Set([
+  "bash",
+  "mcp",
+]);
+
+/**
+ * Convert the on-disk config shape into a flat Ruleset.
+ *
+ * Ordering within a scope:
+ * 1. tools entries (tool-name-as-surface, pattern "*") — excluding bash/mcp
+ * 2. bash entries (surface "bash", pattern = command glob)
+ * 3. mcp entries (surface "mcp", pattern = target glob)
+ * 4. skills entries (surface "skill", pattern = skill glob)
+ * 5. special entries (surface "special", pattern = key name)
+ *
+ * `tools.bash` and `tools.mcp` are excluded — see TOOL_SURFACE_OVERRIDE_KEYS.
+ * `defaultPolicy` is NOT included — handled separately by the caller.
+ */
+export function normalizeConfig(config: NormalizableConfig): Ruleset {
+  const rules: Rule[] = [];
+
+  for (const [name, action] of Object.entries(config.tools ?? {})) {
+    if (TOOL_SURFACE_OVERRIDE_KEYS.has(name)) continue;
+    rules.push({ surface: name, pattern: "*", action });
+  }
+
+  for (const [pattern, action] of Object.entries(config.bash ?? {})) {
+    rules.push({ surface: "bash", pattern, action });
+  }
+
+  for (const [pattern, action] of Object.entries(config.mcp ?? {})) {
+    rules.push({ surface: "mcp", pattern, action });
+  }
+
+  for (const [pattern, action] of Object.entries(config.skills ?? {})) {
+    rules.push({ surface: "skill", pattern, action });
+  }
+
+  for (const [name, action] of Object.entries(config.special ?? {})) {
+    rules.push({ surface: "special", pattern: name, action });
+  }
+
+  return rules;
+}