@gotgenes/pi-permission-system 7.3.1 → 7.3.3

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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).
 
+## [7.3.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v7.3.2...pi-permission-system-v7.3.3) (2026-05-28)
+
+
+### Bug Fixes
+
+* respect config-level allow/deny in bash external-directory gate ([#249](https://github.com/gotgenes/pi-packages/issues/249)) ([1437ff3](https://github.com/gotgenes/pi-packages/commit/1437ff3e3c0bdde93927ba9fdf9e3cf5b52e7c0c))
+
+
+### Documentation
+
+* plan fix for bash external-directory config-level allow bypass ([#249](https://github.com/gotgenes/pi-packages/issues/249)) ([9e09f35](https://github.com/gotgenes/pi-packages/commit/9e09f35e6cfad09b53a1b55b54fcd44af4ed6a7b))
+* **retro:** add planning stage notes for issue [#249](https://github.com/gotgenes/pi-packages/issues/249) ([fe13214](https://github.com/gotgenes/pi-packages/commit/fe132144869db93bfc83c4e940abb7d3ce813d46))
+* **retro:** add TDD stage notes for issue [#249](https://github.com/gotgenes/pi-packages/issues/249) ([b5d22f6](https://github.com/gotgenes/pi-packages/commit/b5d22f6d67f7d2c28ed406c99bc0458df9024713))
+
+## [7.3.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v7.3.1...pi-permission-system-v7.3.2) (2026-05-27)
+
+
+### Documentation
+
+* replace \n with <br/> in Mermaid node labels ([3312a45](https://github.com/gotgenes/pi-packages/commit/3312a4559100cf9ae923f67819653b5a99fceb12))
+
 ## [7.3.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v7.3.0...pi-permission-system-v7.3.1) (2026-05-26)
 
 

package/package.json

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

package/src/handlers/before-agent-start.ts

@@ -41,7 +41,6 @@ export function shouldExposeTool(
  */
 export class AgentPrepHandler {
   constructor(
-    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: accessed via destructuring (const { session } = this)
     private readonly session: PermissionSession,
     private readonly toolRegistry: ToolRegistry,
   ) {}
@@ -51,11 +50,10 @@ export class AgentPrepHandler {
     event: BeforeAgentStartPayload,
     ctx: ExtensionContext,
   ): Promise<BeforeAgentStartEventResult> {
-    const { session } = this;
-    session.activate(ctx);
-    session.refreshConfig(ctx);
+    this.session.activate(ctx);
+    this.session.refreshConfig(ctx);
 
-    const agentName = session.resolveAgentName(ctx, event.systemPrompt);
+    const agentName = this.session.resolveAgentName(ctx, event.systemPrompt);
     const allTools = this.toolRegistry.getAll();
     const allowedTools: string[] = [];
 
@@ -66,7 +64,7 @@ export class AgentPrepHandler {
       }
       if (
         shouldExposeTool(toolName, agentName, (t, a) =>
-          session.getToolPermission(t, a),
+          this.session.getToolPermission(t, a),
         )
       ) {
         allowedTools.push(toolName);
@@ -74,24 +72,24 @@ export class AgentPrepHandler {
     }
 
     const activeToolsCacheKey = createActiveToolsCacheKey(allowedTools);
-    if (session.shouldUpdateActiveTools(activeToolsCacheKey)) {
+    if (this.session.shouldUpdateActiveTools(activeToolsCacheKey)) {
       this.toolRegistry.setActive(allowedTools);
-      session.commitActiveToolsCacheKey(activeToolsCacheKey);
+      this.session.commitActiveToolsCacheKey(activeToolsCacheKey);
     }
 
     const promptStateCacheKey = createBeforeAgentStartPromptStateKey({
       agentName,
       cwd: ctx.cwd,
-      permissionStamp: session.getPolicyCacheStamp(agentName ?? undefined),
+      permissionStamp: this.session.getPolicyCacheStamp(agentName ?? undefined),
       systemPrompt: event.systemPrompt,
       allowedToolNames: allowedTools,
     });
 
-    if (!session.shouldUpdatePromptState(promptStateCacheKey)) {
+    if (!this.session.shouldUpdatePromptState(promptStateCacheKey)) {
       return {};
     }
 
-    session.commitPromptStateCacheKey(promptStateCacheKey);
+    this.session.commitPromptStateCacheKey(promptStateCacheKey);
 
     const toolPromptResult = sanitizeAvailableToolsSection(
       event.systemPrompt,
@@ -99,11 +97,11 @@ export class AgentPrepHandler {
     );
     const skillPromptResult = resolveSkillPromptEntries(
       toolPromptResult.prompt,
-      session,
+      this.session,
       agentName,
       ctx.cwd,
     );
-    session.setActiveSkillEntries(skillPromptResult.entries);
+    this.session.setActiveSkillEntries(skillPromptResult.entries);
 
     if (skillPromptResult.prompt !== event.systemPrompt) {
       return { systemPrompt: skillPromptResult.prompt };

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

@@ -21,7 +21,7 @@ type CheckPermissionFn = (
  * Extracts paths from a bash command and checks whether any reference
  * directories outside the working directory. Returns `null` when the gate
  * does not apply (tool is not bash, no CWD, or no external paths found).
- * Returns a `GateBypass` when all paths are session-covered.
+ * Returns a `GateBypass` when all paths are allowed (by config or session rule).
  * Returns a `GateDescriptor` with multi-pattern sessionApproval for uncovered paths.
  */
 export async function describeBashExternalDirectoryGate(
@@ -41,15 +41,26 @@ export async function describeBashExternalDirectoryGate(
   if (externalPaths.length === 0) return null;
 
   const bashSessionRules = getSessionRuleset();
-  const uncoveredPaths = externalPaths.filter(
-    (p) =>
-      checkPermission(
-        "external_directory",
-        { path: p },
-        tcc.agentName ?? undefined,
-        bashSessionRules,
-      ).source !== "session",
-  );
+
+  // Collect paths whose resolved state is not already "allow".
+  // Checking state (not source) ensures config-level allow rules (source: "special")
+  // suppress the prompt just as session-level allow rules (source: "session") do.
+  const uncoveredEntries: Array<{
+    path: string;
+    check: PermissionCheckResult;
+  }> = [];
+  for (const p of externalPaths) {
+    const check = checkPermission(
+      "external_directory",
+      { path: p },
+      tcc.agentName ?? undefined,
+      bashSessionRules,
+    );
+    if (check.state !== "allow") {
+      uncoveredEntries.push({ path: p, check });
+    }
+  }
+  const uncoveredPaths = uncoveredEntries.map(({ path }) => path);
 
   if (uncoveredPaths.length === 0) {
     return {
@@ -69,12 +80,12 @@ export async function describeBashExternalDirectoryGate(
     };
   }
 
-  // Get the config-level policy (no path → no session check).
-  const extCheck = checkPermission(
-    "external_directory",
-    {},
-    tcc.agentName ?? undefined,
-  );
+  // Use the most restrictive check among uncovered paths as the pre-check result.
+  // This ensures a config-level "deny" rule is not downgraded to "ask" by the
+  // generic "*" catch-all that the old path-less checkPermission call returned.
+  const worstCheck =
+    uncoveredEntries.find(({ check }) => check.state === "deny")?.check ??
+    uncoveredEntries[0].check;
 
   const bashExtMessage = formatBashExternalDirectoryAskPrompt(
     command,
@@ -120,6 +131,6 @@ export async function describeBashExternalDirectoryGate(
       surface: "external_directory",
       value: command,
     },
-    preCheck: extCheck,
+    preCheck: worstCheck,
   };
 }

package/src/handlers/lifecycle.ts

@@ -22,7 +22,6 @@ interface ResourcesDiscoverPayload {
  */
 export class SessionLifecycleHandler {
   constructor(
-    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: accessed via destructuring (const { session } = this)
     private readonly session: PermissionSession,
     private readonly cleanupRpc: () => void,
   ) {}
@@ -31,19 +30,18 @@ export class SessionLifecycleHandler {
     event: SessionStartPayload,
     ctx: ExtensionContext,
   ): Promise<void> {
-    const { session } = this;
-    session.refreshConfig(ctx);
-    session.resetForNewSession(ctx);
-    session.logResolvedConfigPaths();
+    this.session.refreshConfig(ctx);
+    this.session.resetForNewSession(ctx);
+    this.session.logResolvedConfigPaths();
 
-    const agentName = session.resolveAgentName(ctx);
-    const policyIssues = session.getConfigIssues(agentName ?? undefined);
+    const agentName = this.session.resolveAgentName(ctx);
+    const policyIssues = this.session.getConfigIssues(agentName ?? undefined);
     for (const issue of policyIssues) {
-      session.logger.warn(issue);
+      this.session.logger.warn(issue);
     }
 
     if (event.reason === "reload") {
-      session.logger.debug("lifecycle.reload", {
+      this.session.logger.debug("lifecycle.reload", {
         triggeredBy: "session_start",
         reason: event.reason,
         cwd: ctx.cwd,
@@ -57,23 +55,21 @@ export class SessionLifecycleHandler {
       return Promise.resolve();
     }
 
-    const { session } = this;
-    session.reload();
-    session.logger.debug("lifecycle.reload", {
+    this.session.reload();
+    this.session.logger.debug("lifecycle.reload", {
       triggeredBy: "resources_discover",
       reason: event.reason,
-      cwd: session.getRuntimeContext()?.cwd ?? null,
+      cwd: this.session.getRuntimeContext()?.cwd ?? null,
     });
     return Promise.resolve();
   }
 
   handleSessionShutdown(): Promise<void> {
-    const { session } = this;
-    const ctx = session.getRuntimeContext();
+    const ctx = this.session.getRuntimeContext();
     if (ctx) {
       ctx.ui.setStatus(PERMISSION_SYSTEM_STATUS_KEY, undefined);
     }
-    session.shutdown();
+    this.session.shutdown();
     this.cleanupRpc();
     return Promise.resolve();
   }

package/src/handlers/permission-gate-handler.ts

@@ -47,7 +47,6 @@ interface InputPayload {
  */
 export class PermissionGateHandler {
   constructor(
-    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: accessed via destructuring (const { session } = this)
     private readonly session: PermissionSession,
     private readonly events: PermissionEventBus,
     private readonly toolRegistry: ToolRegistry,
@@ -57,10 +56,9 @@ export class PermissionGateHandler {
     event: unknown,
     ctx: ExtensionContext,
   ): Promise<{ block?: true; reason?: string }> {
-    const { session } = this;
-    session.activate(ctx);
+    this.session.activate(ctx);
 
-    const agentName = session.resolveAgentName(ctx);
+    const agentName = this.session.resolveAgentName(ctx);
     const toolName = getToolNameFromValue(event);
 
     if (!toolName) {
@@ -100,22 +98,22 @@ export class PermissionGateHandler {
     };
 
     // ── Shared gate adapter closures ─────────────────────────────────────
-    const canConfirm = () => session.canPrompt(ctx);
+    const canConfirm = () => this.session.canPrompt(ctx);
     const promptPermission = (details: PromptPermissionDetails) =>
-      session.prompt(ctx, details);
+      this.session.prompt(ctx, details);
     const emitDecision: GateRunnerDeps["emitDecision"] = (e) =>
       emitDecisionEvent(this.events, e);
     // eslint-disable-next-line @typescript-eslint/unbound-method -- logger.review is a plain function closure; no this-binding issue
-    const writeReviewLog = session.logger.review;
+    const writeReviewLog = this.session.logger.review;
     const checkPermission: GateRunnerDeps["checkPermission"] = (
       surface,
       input,
       agent,
       sessionRules,
-    ) => session.checkPermission(surface, input, agent, sessionRules);
-    const getSessionRuleset = () => session.getSessionRuleset();
+    ) => this.session.checkPermission(surface, input, agent, sessionRules);
+    const getSessionRuleset = () => this.session.getSessionRuleset();
     const approveSessionRule = (surface: string, pattern: string) =>
-      session.approveSessionRule(surface, pattern);
+      this.session.approveSessionRule(surface, pattern);
 
     // ── Shared runner deps (built once, reused for all gates) ────────────
     const runnerDeps: GateRunnerDeps = {
@@ -130,7 +128,7 @@ export class PermissionGateHandler {
 
     // ── Skill-read gate (descriptor + runner) ───────────────────────────────
     const skillDescriptor = describeSkillReadGate(tcc, () =>
-      session.getActiveSkillEntries(),
+      this.session.getActiveSkillEntries(),
     );
     if (skillDescriptor) {
       const skillResult = await runGateCheck(
@@ -166,8 +164,8 @@ export class PermissionGateHandler {
 
     // ── External-directory gate (descriptor + runner) ────────────────────────
     const infraDirs = [
-      ...session.getInfrastructureDirs(),
-      ...session.getInfrastructureReadPaths(),
+      ...this.session.getInfrastructureDirs(),
+      ...this.session.getInfrastructureReadPaths(),
     ];
     const extDirDesc = describeExternalDirectoryGate(tcc, infraDirs);
     if (extDirDesc) {
@@ -265,16 +263,15 @@ export class PermissionGateHandler {
     event: InputPayload,
     ctx: ExtensionContext,
   ): Promise<InputEventResult> {
-    const { session } = this;
-    session.activate(ctx);
+    this.session.activate(ctx);
 
     const skillName = extractSkillNameFromInput(event.text);
     if (!skillName) {
       return { action: "continue" };
     }
 
-    const agentName = session.resolveAgentName(ctx);
-    const check = session.checkPermission(
+    const agentName = this.session.resolveAgentName(ctx);
+    const check = this.session.checkPermission(
       "skill",
       { name: skillName },
       agentName ?? undefined,
@@ -291,14 +288,14 @@ export class PermissionGateHandler {
       skillName,
       agentName ?? undefined,
     );
-    const skillInputCanConfirm = session.canPrompt(ctx);
+    const skillInputCanConfirm = this.session.canPrompt(ctx);
     let skillInputAutoApproved = false;
     const skillInputGate = await applyPermissionGate({
       state: check.state,
       canConfirm: skillInputCanConfirm,
       promptForApproval: async () => {
-        const decision = await session.prompt(ctx, {
-          requestId: session.createPermissionRequestId("skill-input"),
+        const decision = await this.session.prompt(ctx, {
+          requestId: this.session.createPermissionRequestId("skill-input"),
           source: "skill_input",
           agentName,
           message: skillInputMessage,
@@ -308,7 +305,7 @@ export class PermissionGateHandler {
         return decision;
       },
       // eslint-disable-next-line @typescript-eslint/unbound-method -- logger.review is a plain function closure; no this-binding issue
-      writeLog: session.logger.review,
+      writeLog: this.session.logger.review,
       logContext: {
         source: "skill_input",
         skillName,

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

@@ -98,16 +98,39 @@ describe("describeBashExternalDirectoryGate", () => {
     expect(patterns.length).toBeGreaterThan(0);
   });
 
-  it("uses config-level checkPermission for the policy state", async () => {
+  it("returns GateBypass when all external paths are config-level allowed", async () => {
+    // Config-level allow (source: "special") should suppress the prompt,
+    // not just session-level allow. This was the bug: source !== "session"
+    // kept config-allowed paths in the uncovered set.
     const checkPermission = vi
       .fn()
       .mockImplementation(
         (_surface: string, input: Record<string, unknown>) => {
-          // Path-specific check returns session for coverage filtering
           if (input.path)
             return makeCheckResult("allow", { source: "special" });
-          // Config-level check (no path) returns deny
-          return makeCheckResult("deny");
+          return makeCheckResult("ask");
+        },
+      );
+    const result = await describeBashExternalDirectoryGate(
+      makeTcc(),
+      checkPermission,
+      vi.fn().mockReturnValue([]),
+    );
+    expect(result).not.toBeNull();
+    expect(isGateBypass(result)).toBe(true);
+  });
+
+  it("uses worst-check state from uncovered paths for preCheck (config deny > catch-all ask)", async () => {
+    // The path-less extCheck used to always return the "*" catch-all (ask),
+    // silently downgrading a config-level deny to ask. After the fix, the
+    // descriptor's preCheck is derived from the actual path check result.
+    const checkPermission = vi
+      .fn()
+      .mockImplementation(
+        (_surface: string, input: Record<string, unknown>) => {
+          if (input.path) return makeCheckResult("deny", { source: "special" });
+          // Path-less catch-all returns ask — should NOT be used as preCheck.
+          return makeCheckResult("ask");
         },
       );
     const result = await describeBashExternalDirectoryGate(
@@ -116,8 +139,6 @@ describe("describeBashExternalDirectoryGate", () => {
       vi.fn().mockReturnValue([]),
     );
     expect(isGateDescriptor(result)).toBe(true);
-    // The descriptor should carry the deny state from the config-level check
-    // (it will be checked as preCheck by the runner)
     const desc = result as GateDescriptor;
     expect(desc.preCheck?.state).toBe("deny");
   });
@@ -172,6 +193,53 @@ describe("describeBashExternalDirectoryGate", () => {
     });
   });
 
+  it("config-allowed path is excluded; remaining ask path produces a descriptor", async () => {
+    // One path config-allowed, one config-ask → descriptor with only the ask path.
+    const checkPermission = vi
+      .fn()
+      .mockImplementation(
+        (_surface: string, input: Record<string, unknown>) => {
+          if (input.path === "/outside/a.ts")
+            return makeCheckResult("allow", { source: "special" });
+          return makeCheckResult("ask");
+        },
+      );
+    const result = await describeBashExternalDirectoryGate(
+      makeTcc({ input: { command: "diff /outside/a.ts /outside/b.ts" } }),
+      checkPermission,
+      vi.fn().mockReturnValue([]),
+    );
+    expect(isGateDescriptor(result)).toBe(true);
+    const desc = result as GateDescriptor;
+    const patterns = (desc.sessionApproval as { patterns: string[] }).patterns;
+    expect(patterns.length).toBe(1);
+    expect(desc.preCheck?.state).toBe("ask");
+  });
+
+  it("config-denied path makes worstCheck deny even when another path is ask", async () => {
+    // One path config-denied, one config-ask → descriptor with preCheck.state === "deny".
+    const checkPermission = vi
+      .fn()
+      .mockImplementation(
+        (_surface: string, input: Record<string, unknown>) => {
+          if (input.path === "/outside/a.ts")
+            return makeCheckResult("deny", { source: "special" });
+          return makeCheckResult("ask");
+        },
+      );
+    const result = await describeBashExternalDirectoryGate(
+      makeTcc({ input: { command: "diff /outside/a.ts /outside/b.ts" } }),
+      checkPermission,
+      vi.fn().mockReturnValue([]),
+    );
+    expect(isGateDescriptor(result)).toBe(true);
+    const desc = result as GateDescriptor;
+    expect(desc.preCheck?.state).toBe("deny");
+    // Both paths are uncovered (neither is allow), so both patterns are included.
+    const patterns = (desc.sessionApproval as { patterns: string[] }).patterns;
+    expect(patterns.length).toBe(2);
+  });
+
   it("only includes uncovered paths when some are session-covered", async () => {
     const checkPermission = vi
       .fn()