@gotgenes/pi-permission-system 13.2.0 → 14.0.1

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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).
 
+## [14.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v14.0.0...pi-permission-system-v14.0.1) (2026-06-19)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** strip shell comment lines from bash commands before matching ([d045591](https://github.com/gotgenes/pi-packages/commit/d0455915d6d4ce50534884639e516a9e1ef38976))
+
+## [14.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v13.2.0...pi-permission-system-v14.0.0) (2026-06-17)
+
+
+### ⚠ BREAKING CHANGES
+
+* project agents' `permission:` frontmatter at `<cwd>/.pi/agents/<name>.md` is now read and enforced. Previously the wrong directory (`<cwd>/.pi/agent/agents`) was checked and the frontmatter was silently ignored, so a session may become more restrictive on upgrade.
+
+### Bug Fixes
+
+* correct project agents directory path to &lt;cwd&gt;/.pi/agents ([#428](https://github.com/gotgenes/pi-packages/issues/428)) ([eb5af78](https://github.com/gotgenes/pi-packages/commit/eb5af78193fa3cc574da6b8d80efd643ebce0ef9))
+
+
+### Documentation
+
+* correct project agent override path to &lt;cwd&gt;/.pi/agents ([#428](https://github.com/gotgenes/pi-packages/issues/428)) ([d193d6a](https://github.com/gotgenes/pi-packages/commit/d193d6a61155fb4e4a064800509cdbbd84b0ceb9))
+* fix stale project agents path in troubleshooting and ADR-0001 ([#428](https://github.com/gotgenes/pi-packages/issues/428)) ([95effeb](https://github.com/gotgenes/pi-packages/commit/95effebfd0b2e87db4512c91adc134b2470f26a3))
+
 ## [13.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v13.1.2...pi-permission-system-v13.2.0) (2026-06-17)
 
 

package/package.json

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

package/src/bash-arity.ts

@@ -184,3 +184,27 @@ export function prefix(tokens: string[]): string[] {
   // Unknown command — default arity 1.
   return [tokens[0]];
 }
+
+/**
+ * Remove shell comment lines from a bash command string.
+ *
+ * A comment line is one whose first non-whitespace character is `#`. Agents
+ * frequently prepend descriptive comments before the real command
+ * (e.g. `"# Check debug logs\nfind ..."`); such prefixes defeat wildcard
+ * pattern matching and session-approval suggestions, which tokenize the
+ * leading text. Stripping comment lines lets matching operate on the actual
+ * command.
+ *
+ * The original command is never returned: when every line is a comment (or
+ * the input is blank) an empty string is returned, and each caller applies
+ * its own fallback.
+ *
+ * @param command - Raw bash command, possibly multi-line.
+ * @returns The command with comment lines removed and surrounding whitespace
+ *   trimmed, or an empty string when nothing meaningful remains.
+ */
+export function stripBashCommentLines(command: string): string {
+  const lines = command.split("\n");
+  const meaningful = lines.filter((line) => !/^\s*#/.test(line));
+  return meaningful.join("\n").trim();
+}

package/src/config-paths.ts

@@ -21,6 +21,19 @@ export function getProjectConfigPath(cwd: string): string {
   return join(cwd, ".pi", "extensions", EXTENSION_ID, "config.json");
 }
 
+/**
+ * Directory holding project-scoped custom agent definition files.
+ *
+ * `<cwd>/.pi/agents` is a Pi platform convention, also encoded by
+ * `@gotgenes/pi-subagents`' `loadCustomAgents` (`config/custom-agents.ts`).
+ * The two packages encode it independently — pi-permission-system has no
+ * dependency on pi-subagents (ADR-0002) — so this is this package's
+ * authoritative copy.
+ */
+export function getProjectAgentsDir(cwd: string): string {
+  return join(cwd, ".pi", "agents");
+}
+
 export function getLegacyGlobalPolicyPath(agentDir: string): string {
   return join(agentDir, "pi-permissions.jsonc");
 }

package/src/input-normalizer.ts

@@ -1,3 +1,4 @@
+import { stripBashCommentLines } from "./bash-arity";
 import { getNonEmptyString, toRecord } from "./common";
 import { createMcpPermissionTargets } from "./mcp-targets";
 import { getPathPolicyValues, PATH_BEARING_TOOLS } from "./path-utils";
@@ -92,9 +93,14 @@ export function normalizeInput(
   if (toolName === "bash") {
     const record = toRecord(input);
     const command = typeof record.command === "string" ? record.command : "";
+    // Strip leading shell comment lines so pattern matching operates on the
+    // actual command, not a `# description` prefix agents often prepend.
+    // Fall back to the raw command when stripping leaves nothing, so an
+    // all-comment command still evaluates against its literal text.
+    const matchValue = stripBashCommentLines(command) || command;
     return {
       surface: "bash",
-      values: [command],
+      values: [matchValue],
       resultExtras: { command },
     };
   }

package/src/pattern-suggest.ts

@@ -1,4 +1,4 @@
-import { prefix } from "./bash-arity";
+import { prefix, stripBashCommentLines } from "./bash-arity";
 import { PATH_BEARING_TOOLS } from "./path-utils";
 import { deriveApprovalPattern } from "./session-rules";
 
@@ -26,11 +26,15 @@ export interface SessionApprovalSuggestion {
 export function suggestBashPattern(command: string): string {
   const trimmed = command.trim();
   if (!trimmed) return "";
-  const tokens = trimmed.split(/\s+/);
-  if (tokens.length === 1) return trimmed;
+  // Strip leading shell comment lines so the suggestion is based on the
+  // actual command, not a `# description` prefix agents often prepend.
+  const stripped = stripBashCommentLines(trimmed);
+  if (!stripped) return "";
+  const tokens = stripped.split(/\s+/);
+  if (tokens.length === 1) return stripped;
   const meaningful = prefix(tokens);
   if (meaningful.length >= tokens.length) {
-    return `${trimmed}*`;
+    return `${stripped}*`;
   }
   return `${meaningful.join(" ")} *`;
 }

package/src/permission-manager.ts

@@ -1,6 +1,10 @@
 import { join } from "node:path";
 import { isPermissionState } from "./common";
-import { getGlobalConfigPath, getProjectConfigPath } from "./config-paths";
+import {
+  getGlobalConfigPath,
+  getProjectAgentsDir,
+  getProjectConfigPath,
+} from "./config-paths";
 import { normalizeInput } from "./input-normalizer";
 import { normalizeFlatConfig } from "./normalize";
 import { PATH_SURFACES } from "./path-utils";
@@ -350,7 +354,7 @@ function derivePolicyLoaderOptions(
     globalConfigPath: getGlobalConfigPath(agentDir),
     agentsDir: join(agentDir, "agents"),
     projectGlobalConfigPath: cwd ? getProjectConfigPath(cwd) : undefined,
-    projectAgentsDir: cwd ? join(cwd, ".pi", "agent", "agents") : undefined,
+    projectAgentsDir: cwd ? getProjectAgentsDir(cwd) : undefined,
   };
 }
 

package/test/bash-arity.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { ARITY, prefix } from "#src/bash-arity";
+import { ARITY, prefix, stripBashCommentLines } from "#src/bash-arity";
 
 describe("ARITY dictionary", () => {
   it("is exported as a plain object", () => {
@@ -104,3 +104,41 @@ describe("prefix", () => {
     expect(prefix(["ls", "-la", "/tmp"])).toEqual(["ls"]);
   });
 });
+
+describe("stripBashCommentLines", () => {
+  it("removes a single leading comment line", () => {
+    expect(
+      stripBashCommentLines("# Check debug logs\nfind /home -type f"),
+    ).toBe("find /home -type f");
+  });
+
+  it("removes multiple leading comment lines", () => {
+    expect(
+      stripBashCommentLines("# Step 1\n# Step 2\ngit status --short"),
+    ).toBe("git status --short");
+  });
+
+  it("returns empty string when all lines are comments", () => {
+    expect(stripBashCommentLines("# just a comment")).toBe("");
+  });
+
+  it("returns empty string for blank input", () => {
+    expect(stripBashCommentLines("")).toBe("");
+  });
+
+  it("returns the command unchanged when no comment lines are present", () => {
+    expect(stripBashCommentLines("grep -rn foo src/")).toBe(
+      "grep -rn foo src/",
+    );
+  });
+
+  it("trims surrounding whitespace from the result", () => {
+    expect(stripBashCommentLines("\n\n  ls -la  \n")).toBe("ls -la");
+  });
+
+  it("treats indented comment lines as comments", () => {
+    expect(stripBashCommentLines("    # indented comment\necho hi")).toBe(
+      "echo hi",
+    );
+  });
+});

package/test/config-paths.test.ts

@@ -9,6 +9,7 @@ import {
   getLegacyExtensionConfigPath,
   getLegacyGlobalPolicyPath,
   getLegacyProjectPolicyPath,
+  getProjectAgentsDir,
   getProjectConfigPath,
   REVIEW_LOG_FILENAME,
 } from "#src/config-paths";
@@ -42,6 +43,10 @@ describe("config-paths", () => {
         join(cwd, ".pi", "extensions", "pi-permission-system", "config.json"),
       );
     });
+
+    it("getProjectAgentsDir returns .pi/agents under cwd", () => {
+      expect(getProjectAgentsDir(cwd)).toBe(join(cwd, ".pi", "agents"));
+    });
   });
 
   describe("legacy paths", () => {

package/test/input-normalizer.test.ts

@@ -198,6 +198,34 @@ describe("normalizeInput — non-MCP surfaces", () => {
       expect(result.values).toEqual([""]);
       expect(result.resultExtras).toEqual({ command: "" });
     });
+
+    it("strips leading comment lines from values but keeps original in resultExtras", () => {
+      const cmd = "# Check debug logs\nfind /home -path '*debug*' -type f";
+      const result = normalizeInput("bash", { command: cmd }, []);
+      expect(result.values).toEqual(["find /home -path '*debug*' -type f"]);
+      expect(result.resultExtras).toEqual({ command: cmd });
+    });
+
+    it("strips multiple comment lines", () => {
+      const cmd = "# Step 1\n# Step 2\ngit status --short";
+      const result = normalizeInput("bash", { command: cmd }, []);
+      expect(result.values).toEqual(["git status --short"]);
+    });
+
+    it("preserves command when no comment lines present", () => {
+      const result = normalizeInput(
+        "bash",
+        { command: "grep -rn foo src/" },
+        [],
+      );
+      expect(result.values).toEqual(["grep -rn foo src/"]);
+    });
+
+    it("falls back to original when all lines are comments", () => {
+      const cmd = "# just a comment";
+      const result = normalizeInput("bash", { command: cmd }, []);
+      expect(result.values).toEqual(["# just a comment"]);
+    });
   });
 
   describe("path-bearing tools (read, write, edit, grep, find, ls)", () => {

package/test/pattern-suggest.test.ts

@@ -42,6 +42,30 @@ describe("suggestBashPattern", () => {
       "docker compose up *",
     );
   });
+
+  it("strips leading comment lines and suggests based on the actual command", () => {
+    expect(
+      suggestBashPattern(
+        "# Check debug logs\nfind /home -path '*debug*' -type f",
+      ),
+    ).toBe("find *");
+  });
+
+  it("strips multiple leading comment lines", () => {
+    expect(suggestBashPattern("# Step 1\n# Step 2\ngit status --short")).toBe(
+      "git status *",
+    );
+  });
+
+  it("returns empty for comment-only input", () => {
+    expect(suggestBashPattern("# just a comment")).toBe("");
+  });
+
+  it("handles mixed comment and command lines", () => {
+    expect(suggestBashPattern("# description\nrm -rf ./build; echo done")).toBe(
+      "rm *",
+    );
+  });
 });
 
 describe("suggestMcpPattern", () => {

package/test/permission-manager-unified.test.ts

@@ -8,7 +8,11 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { describe, expect, it, test } from "vitest";
-import { getGlobalConfigPath, getProjectConfigPath } from "#src/config-paths";
+import {
+  getGlobalConfigPath,
+  getProjectAgentsDir,
+  getProjectConfigPath,
+} from "#src/config-paths";
 import {
   PermissionManager,
   type ScopedPermissionManager,
@@ -1669,6 +1673,53 @@ describe("PermissionManager — configureForCwd and agentDir option", () => {
       cleanup();
     }
   });
+
+  it("configureForCwd(cwd) derives projectAgentsDir at <cwd>/.pi/agents (regression: #428)", () => {
+    // Bug: old code derived <cwd>/.pi/agent/agents instead of <cwd>/.pi/agents.
+    // This test pins the correct path and verifies agentsDir is unchanged.
+    const { agentDir, cwd, cleanup } = makeAgentDirSetup({
+      globalPermission: { read: "allow" },
+    });
+    try {
+      const manager = new PermissionManager({ agentDir });
+      manager.configureForCwd(cwd);
+      const paths = manager.getResolvedPolicyPaths();
+      expect(paths.projectAgentsDir).toBe(getProjectAgentsDir(cwd));
+      expect(paths.agentsDir).toBe(join(agentDir, "agents"));
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("configureForCwd(cwd) enforces permission: frontmatter from <cwd>/.pi/agents/<agent>.md (regression: #428)", () => {
+    // Bug: wrong directory meant project-agent frontmatter was never loaded.
+    const { agentDir, cwd, cleanup } = makeAgentDirSetup({
+      globalPermission: { read: "allow" },
+    });
+    try {
+      // Write a project agent definition with a deny override.
+      const projectAgentsDir = getProjectAgentsDir(cwd);
+      mkdirSync(projectAgentsDir, { recursive: true });
+      writeFileSync(
+        join(projectAgentsDir, "coder.md"),
+        "---\npermission:\n  read: deny\n---\n# Coder\n",
+      );
+
+      const manager = new PermissionManager({ agentDir });
+      manager.configureForCwd(cwd);
+
+      // Without an agent name: global allow applies.
+      expect(manager.checkPermission("read", { path: "foo.txt" }).state).toBe(
+        "allow",
+      );
+      // With the "coder" agent: project-agent deny overrides global allow.
+      expect(
+        manager.checkPermission("read", { path: "foo.txt" }, "coder").state,
+      ).toBe("deny");
+    } finally {
+      cleanup();
+    }
+  });
 });
 
 // ---------------------------------------------------------------------------