@gotgenes/pi-permission-system 39.0.1 → 39.0.2

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v39.0.1...pi-permission-system-v39.0.2) (2026-10-03)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** stop logging config- and default-allowed bash external paths as session approvals ([1e597c0](https://github.com/gotgenes/pi-packages/commit/1e597c033c58843f298d9fd0f01cf227dc649e60)), closes [#1011](https://github.com/gotgenes/pi-packages/issues/1011)
+
+### Documentation
+
+* **pi-permission-system:** say what external_directory does when the key is absent ([7319277](https://github.com/gotgenes/pi-packages/commit/7319277d338665225d59af21c43b463e94bda6e6)), closes [#1011](https://github.com/gotgenes/pi-packages/issues/1011)
+
 ## [39.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v39.0.0...pi-permission-system-v39.0.1) (2026-10-03)
 
 

package/docs/configuration.md

@@ -789,6 +789,9 @@ Use a pattern map to allow specific directories without opening all external acc
 For example, `read: "allow"` can permit ordinary reads while `external_directory: "ask"` still requires confirmation before reading `../outside.txt` or an absolute path outside `ctx.cwd`.
 Optional-path search tools (`find`, `grep`, `ls`) skip this check when no `path` is provided.
 
+When no `external_directory` key is present, the universal fallback (`permission["*"]`) applies.
+So `"*": "allow"` lets every outside-CWD access through with no prompt and, like any policy allow, no review-log entry; the examples on this page set `"*": "ask"` inside `external_directory` so the boundary asks regardless of the fallback.
+
 #### Allow an outside-CWD cache directory
 
 When an agent keeps reading a local cache outside the working tree — `~/.cargo/registry`, `~/.npm`, `~/go/pkg/mod` — and you want to stop confirming it every time, allow that directory on the `external_directory` surface:

package/package.json

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

package/src/handlers/gates/bash-external-directory.ts

@@ -14,7 +14,10 @@ import type { ToolCallContext } from "./types";
  * Reads the external paths from the injected `BashProgram` and checks whether
  * any reference directories outside the working directory. Returns `null` when the gate
  * does not apply (not a shell invocation, no command, or no external paths found).
- * Returns a `GateBypass` when all paths are allowed (by config or session rule).
+ * Returns `null` when every path is allowed by a config rule or the universal
+ * fallback — like any policy allow, it writes no review entry. Returns a
+ * `GateBypass` recording a session approval when every path is allowed and at
+ * least one was covered by a session grant.
  * Returns a `GateDescriptor` with multi-pattern sessionApproval for uncovered paths.
  *
  * Each path is resolved on the narrowest `external_directory`-family surface
@@ -42,23 +45,29 @@ export function describeBashExternalDirectoryGate(
 
   // Resolve every external path on the external_directory surface and keep the
   // ones not already allowed (config-level allows suppress the prompt just as
-  // session-level allows do); the shared helper single-sources the #418 alias
-  // matching and the worst-uncovered selection.
-  const { uncovered: uncoveredEntries, worstCheck } =
-    selectUncoveredExternalPaths(
-      externalAccesses,
-      resolver,
-      tcc.agentName ?? undefined,
-    );
+  // session-level allows do), noting which allowed ones a session grant
+  // covered; the shared helper single-sources the #418 alias matching and the
+  // worst-uncovered selection.
+  const {
+    uncovered: uncoveredEntries,
+    sessionCovered,
+    worstCheck,
+  } = selectUncoveredExternalPaths(
+    externalAccesses,
+    resolver,
+    tcc.agentName ?? undefined,
+  );
   const uncoveredPaths = uncoveredEntries.map(({ path }) => path.value());
 
   if (uncoveredPaths.length === 0) {
+    // No session grant decided any path: policy alone allowed the command.
+    if (sessionCovered.length === 0) return null;
     return {
       action: "allow",
-      // A whole-command bypass covers every external path at once, and each
-      // may have matched a different session pattern -- so the surface is one
-      // value and the pattern is not. The entry's `externalPaths` lists what
-      // was covered.
+      // A whole-command bypass covers every session-granted path at once, and
+      // each may have matched a different session pattern -- so the surface is
+      // one value and the pattern is not. The entry's `externalPaths` lists the
+      // paths a grant covered, never the ones policy allowed.
       decidedBy: {
         kind: "session_approval",
         surface: "external_directory",
@@ -72,7 +81,7 @@ export function describeBashExternalDirectoryGate(
           toolName: tcc.toolName,
           agentName: tcc.agentName,
           command,
-          externalPaths: externalAccesses.map(({ path }) => path.value()),
+          externalPaths: sessionCovered.map((path) => path.value()),
           resolution: "session_approved",
         },
       },

package/src/handlers/gates/external-directory-policy.ts

@@ -16,9 +16,18 @@ export interface UncoveredExternalPath {
   check: PermissionCheckResult;
 }
 
-/** The uncovered external paths plus the most restrictive check among them. */
-export interface UncoveredExternalPaths {
+/**
+ * How a set of external paths resolved: the uncovered ones, the worst among
+ * them, and which allowed paths a session grant covered.
+ */
+export interface ExternalPathCoverage {
   uncovered: UncoveredExternalPath[];
+  /**
+   * Allowed paths whose winning rule was a session grant. A path allowed by a
+   * config rule or the universal fallback is in neither list, so a caller can
+   * stamp `session_approval` only where a grant actually decided.
+   */
+  sessionCovered: AccessPath[];
   /** Worst check among uncovered paths; `undefined` only when none are uncovered. */
   worstCheck: PermissionCheckResult | undefined;
 }
@@ -60,14 +69,16 @@ export function resolveExternalDirectoryPolicy(
  * not "allow" are collected (filtering on state, not source, so config-level
  * allow rules suppress the prompt just as session-level allow rules do), and
  * the most restrictive uncovered check is returned so a config "deny" is not
- * downgraded to the catch-all "ask".
+ * downgraded to the catch-all "ask". Allowed entries a session rule decided
+ * are reported apart, as the provenance a whole-command bypass records.
  */
 export function selectUncoveredExternalPaths(
   accesses: readonly BashExternalPath[],
   resolver: ScopedPermissionResolver,
   agentName: string | undefined,
-): UncoveredExternalPaths {
+): ExternalPathCoverage {
   const uncovered: UncoveredExternalPath[] = [];
+  const sessionCovered: AccessPath[] = [];
   for (const { path, effect } of accesses) {
     const surface = capabilitySurfaceForEffect(
       "external_directory",
@@ -81,10 +92,13 @@ export function selectUncoveredExternalPaths(
     );
     if (check.state !== "allow") {
       uncovered.push({ path, surface, effect, check });
+    } else if (check.source === "session") {
+      sessionCovered.push(path);
     }
   }
   return {
     uncovered,
+    sessionCovered,
     worstCheck: pickMostRestrictive(uncovered.map(({ check }) => check)),
   };
 }