@gotgenes/pi-permission-system 4.6.0 → 4.7.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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).
 
+## [4.7.0](https://github.com/gotgenes/pi-permission-system/compare/v4.6.0...v4.7.0) (2026-05-05)
+
+
+### Features
+
+* add bash arity table with prefix lookup ([#52](https://github.com/gotgenes/pi-permission-system/issues/52)) ([56a8e81](https://github.com/gotgenes/pi-permission-system/commit/56a8e81911a5869bceabf9076bca6e1bb709814b))
+* integrate arity table into suggestBashPattern ([#52](https://github.com/gotgenes/pi-permission-system/issues/52)) ([5a3c809](https://github.com/gotgenes/pi-permission-system/commit/5a3c8094319166a8f3bd7c97a68af6b8cd0d0205))
+
+
+### Documentation
+
+* document bash arity table ([#52](https://github.com/gotgenes/pi-permission-system/issues/52)) ([376ae5c](https://github.com/gotgenes/pi-permission-system/commit/376ae5cdd9d3a9d28f0e26ec26455f44b45b56d7))
+* plan bash arity table for smart approval patterns ([#52](https://github.com/gotgenes/pi-permission-system/issues/52)) ([6a78244](https://github.com/gotgenes/pi-permission-system/commit/6a78244b7552563e331bb2d426aa0abd35ef9065))
+* **retro:** add retro notes for issue [#60](https://github.com/gotgenes/pi-permission-system/issues/60) ([54ed04a](https://github.com/gotgenes/pi-permission-system/commit/54ed04a85e47a5b1ceb9d496851474856fb0fa17))
+
 ## [4.6.0](https://github.com/gotgenes/pi-permission-system/compare/v4.5.0...v4.6.0) (2026-05-05)
 
 

package/README.md

@@ -450,13 +450,32 @@ The suggested pattern is surface-specific:
 
 |Surface|Example request|Suggested session pattern|
 |---|---|---|
-|bash|`git status --short`|`git *`|
+|bash|`git status --short`|`git status *`|
 |mcp (qualified)|`exa:search`|`exa:*`|
 |mcp (munged)|`exa_search`|`exa_*`|
 |skill|`librarian`|`librarian`|
 |tool (read, write, …)|`read`|`*`|
 |external_directory|`/other/project/src/foo.ts`|`/other/project/src/*`|
 
+#### Bash arity table
+
+Bash pattern suggestions use a curated arity dictionary (`src/bash-arity.ts`) to determine how many tokens define the "human-understandable subcommand."
+Longest matching prefix wins, so `npm run` (arity 3) takes precedence over `npm` (arity 2).
+Unknown commands default to arity 1 (first word only).
+
+|Example command|Arity entry matched|Suggested pattern|
+|---|---|---|
+|`git checkout main`|`git` → 2|`git checkout *`|
+|`npm run dev`|`npm run` → 3|`npm run dev*`|
+|`npm install lodash`|`npm` → 2|`npm install *`|
+|`docker compose up`|`docker compose` → 3|`docker compose up *`|
+|`rm -rf node_modules`|`rm` → 1|`rm *`|
+|`mytool --verbose`|(unknown) → 1|`mytool *`|
+
+The arity table covers common CLI tools including git, npm/pnpm/yarn/bun, docker, cargo, go, kubectl, gh, and others.
+To add an entry, open `src/bash-arity.ts` and add a key/arity pair to the `ARITY` object.
+Put the most specific multi-word prefix first (e.g. `"npm run": 3`) before the shorter fallback (`"npm": 2`).
+
 Session approvals are ephemeral — they are never persisted to disk and are cleared on `session_shutdown`.
 The review log records these decisions: `resolution: "approved_for_session"` when the user approves, and `resolution: "session_approved"` when a later request is matched by an existing session rule.
 
@@ -505,6 +524,7 @@ index.ts                    → Root Pi entrypoint shim
 src/
 ├── index.ts                → Extension bootstrap, permission checks, readable prompts, review logging, reload handling, and subagent forwarding
 ├── pattern-suggest.ts        → Per-surface session approval pattern suggestions
+├── bash-arity.ts             → Curated arity dictionary for smarter bash session-approval patterns
 ├── session-rules.ts          → Ephemeral session-scoped approval rules (Ruleset-based, wildcard patterns across all surfaces)
 ├── config-loader.ts        → Unified config loader, merger, and legacy-path detection
 ├── config-paths.ts         → Path derivation for global, project, and legacy config locations

package/package.json

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

package/src/bash-arity.ts

@@ -0,0 +1,185 @@
+/**
+ * Curated arity dictionary for common CLI commands.
+ *
+ * Keys are lowercase, space-joined command prefixes.
+ * Values are the total token count that defines the "human-understandable
+ * subcommand" — i.e. how many tokens to include in a session-approval pattern.
+ *
+ * Multi-level entries (e.g. "npm run": 3) take precedence over shorter entries
+ * ("npm": 2) because `prefix()` uses longest-match-wins.
+ *
+ * Exported for testability.
+ */
+export const ARITY: Record<string, number> = {
+  // Version control
+  git: 2,
+  hg: 2,
+  svn: 2,
+
+  // Node.js package managers
+  npm: 2,
+  "npm run": 3,
+  "npm exec": 3,
+  npx: 2,
+  pnpm: 2,
+  "pnpm run": 3,
+  "pnpm exec": 3,
+  "pnpm dlx": 3,
+  yarn: 2,
+  "yarn run": 3,
+  bun: 2,
+  "bun run": 3,
+  "bun add": 2,
+  "bun x": 3,
+
+  // Runtimes
+  deno: 2,
+  "deno run": 3,
+  "deno task": 3,
+  "deno compile": 3,
+
+  // Python
+  pip: 2,
+  pip3: 2,
+  uv: 2,
+  "uv run": 3,
+  "uv pip": 3,
+
+  // Rust
+  cargo: 2,
+
+  // Go
+  go: 2,
+  "go run": 3,
+
+  // Ruby
+  bundle: 2,
+  "bundle exec": 3,
+
+  // Docker / container
+  docker: 2,
+  "docker compose": 3,
+  "docker container": 3,
+  "docker image": 3,
+  "docker network": 3,
+  "docker volume": 3,
+  podman: 2,
+  "podman compose": 3,
+
+  // Kubernetes
+  kubectl: 2,
+  helm: 2,
+
+  // Cloud CLIs
+  aws: 3,
+  az: 3,
+  gcloud: 3,
+  gh: 2,
+  "gh pr": 3,
+  "gh issue": 3,
+  "gh repo": 3,
+  fly: 2,
+  vercel: 2,
+  wrangler: 2,
+
+  // Build tools
+  make: 1,
+  bazel: 2,
+
+  // Infrastructure
+  terraform: 2,
+  tofu: 2,
+  pulumi: 2,
+
+  // System service management
+  systemctl: 2,
+  service: 2,
+
+  // Shell file-ops — args are paths/targets, not subcommands
+  ls: 1,
+  ll: 1,
+  la: 1,
+  cat: 1,
+  less: 1,
+  more: 1,
+  head: 1,
+  tail: 1,
+  grep: 1,
+  rg: 1,
+  ag: 1,
+  find: 1,
+  touch: 1,
+  mkdir: 1,
+  rm: 1,
+  cp: 1,
+  mv: 1,
+  ln: 1,
+  chmod: 1,
+  chown: 1,
+  du: 1,
+  df: 1,
+  echo: 1,
+  printf: 1,
+  diff: 1,
+  patch: 1,
+  wc: 1,
+  sort: 1,
+  uniq: 1,
+  awk: 1,
+  sed: 1,
+  tar: 1,
+  zip: 1,
+  unzip: 1,
+
+  // Network
+  curl: 1,
+  wget: 1,
+  ssh: 1,
+  scp: 1,
+  rsync: 1,
+  ping: 1,
+
+  // Process management
+  kill: 1,
+  killall: 1,
+  pkill: 1,
+
+  // Package managers (system)
+  brew: 2,
+  apt: 2,
+  "apt-get": 2,
+  yum: 2,
+  dnf: 2,
+};
+
+/**
+ * Return the semantically meaningful prefix tokens for a tokenized command.
+ *
+ * Performs a longest-match-wins lookup against the `ARITY` dictionary:
+ * iterates from the longest possible prefix down to a single token, returning
+ * the first (longest) match. Lookup is case-insensitive; the returned tokens
+ * preserve their original casing.
+ *
+ * When no entry matches, defaults to arity 1 (first token only).
+ * When the resolved arity exceeds the available tokens, it is clamped.
+ *
+ * @param tokens - The command split by whitespace (e.g. `["git", "checkout", "main"]`).
+ * @returns The prefix tokens defining the meaningful subcommand.
+ */
+export function prefix(tokens: string[]): string[] {
+  if (tokens.length === 0) return [];
+
+  for (let n = tokens.length; n >= 1; n--) {
+    const key = tokens
+      .slice(0, n)
+      .map((t) => t.toLowerCase())
+      .join(" ");
+    const arity = ARITY[key];
+    if (arity !== undefined) {
+      return tokens.slice(0, Math.min(arity, tokens.length));
+    }
+  }
+
+  // Unknown command — default arity 1.
+  return [tokens[0]];
+}

package/src/pattern-suggest.ts

@@ -1,3 +1,4 @@
+import { prefix } from "./bash-arity";
 import { deriveApprovalPattern } from "./session-rules";
 
 /** The suggestion returned for a "Yes, for this session" dialog option. */
@@ -13,20 +14,24 @@ export interface SessionApprovalSuggestion {
 /**
  * Suggest a bash session-approval pattern from a command string.
  *
- * Heuristic: split on the first space to get the base command.
- * Multi-word commands → `<command> *`.
- * Single-word commands → exact command (no wildcard).
+ * Uses the arity table (`src/bash-arity.ts`) to identify the semantically
+ * meaningful prefix tokens for the command, then produces a wildcard pattern:
  *
- * This is intentionally conservative. The arity table (#52) will refine
- * suggestions later (e.g. `git checkout *` instead of `git *`).
+ * - Single bare token (no args): exact command (`ls`).
+ * - Arity prefix covers all tokens: trailing wildcard (`npm run build*`).
+ * - Arity prefix shorter than token list: space + wildcard (`git checkout *`).
+ * - Unknown command: first token + space wildcard (`mytool *`).
  */
 export function suggestBashPattern(command: string): string {
   const trimmed = command.trim();
-  const spaceIndex = trimmed.indexOf(" ");
-  if (spaceIndex === -1) {
-    return trimmed;
+  if (!trimmed) return "";
+  const tokens = trimmed.split(/\s+/);
+  if (tokens.length === 1) return trimmed;
+  const meaningful = prefix(tokens);
+  if (meaningful.length >= tokens.length) {
+    return `${trimmed}*`;
   }
-  return `${trimmed.slice(0, spaceIndex)} *`;
+  return `${meaningful.join(" ")} *`;
 }
 
 /**

package/tests/bash-arity.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "vitest";
+import { ARITY, prefix } from "../src/bash-arity";
+
+describe("ARITY dictionary", () => {
+  it("is exported as a plain object", () => {
+    expect(typeof ARITY).toBe("object");
+  });
+
+  it("maps 'git' to arity 2", () => {
+    expect(ARITY["git"]).toBe(2);
+  });
+
+  it("maps 'npm run' to arity 3", () => {
+    expect(ARITY["npm run"]).toBe(3);
+  });
+
+  it("maps 'npm' to arity 2 (fallback when 'npm run' does not match)", () => {
+    expect(ARITY["npm"]).toBe(2);
+  });
+
+  it("maps 'docker compose' to arity 3", () => {
+    expect(ARITY["docker compose"]).toBe(3);
+  });
+
+  it("maps 'docker' to arity 2 (fallback)", () => {
+    expect(ARITY["docker"]).toBe(2);
+  });
+});
+
+describe("prefix", () => {
+  it("returns empty array for empty input", () => {
+    expect(prefix([])).toEqual([]);
+  });
+
+  it("returns single-element array for a bare known command", () => {
+    // 'git' alone has arity 2 but only 1 token is available — clamp.
+    expect(prefix(["git"])).toEqual(["git"]);
+  });
+
+  it("returns arity-2 prefix for git subcommands", () => {
+    expect(prefix(["git", "checkout", "main"])).toEqual(["git", "checkout"]);
+  });
+
+  it("returns arity-2 prefix for git status with flags", () => {
+    expect(prefix(["git", "status", "--short"])).toEqual(["git", "status"]);
+  });
+
+  it("returns arity-3 prefix for npm run (longest match wins over npm arity-2)", () => {
+    expect(prefix(["npm", "run", "dev"])).toEqual(["npm", "run", "dev"]);
+  });
+
+  it("returns arity-2 prefix for npm install (npm fallback, npm run does not match)", () => {
+    expect(prefix(["npm", "install", "lodash"])).toEqual(["npm", "install"]);
+  });
+
+  it("returns arity-3 prefix for docker compose subcommands", () => {
+    expect(prefix(["docker", "compose", "up", "--build"])).toEqual([
+      "docker",
+      "compose",
+      "up",
+    ]);
+  });
+
+  it("returns arity-2 prefix for docker pull (docker fallback)", () => {
+    expect(prefix(["docker", "pull", "ubuntu"])).toEqual(["docker", "pull"]);
+  });
+
+  it("returns arity-1 prefix for unknown commands", () => {
+    expect(prefix(["unknown-tool", "--flag"])).toEqual(["unknown-tool"]);
+  });
+
+  it("returns arity-1 prefix for rm (args are targets, not subcommands)", () => {
+    expect(prefix(["rm", "-rf", "node_modules"])).toEqual(["rm"]);
+  });
+
+  it("returns arity-1 prefix for cat", () => {
+    expect(prefix(["cat", "file.txt"])).toEqual(["cat"]);
+  });
+
+  it("is case-insensitive: 'Git' looks up as 'git'", () => {
+    // Tokens are preserved as-is; only the lookup key is lowercased.
+    expect(prefix(["Git", "checkout", "main"])).toEqual(["Git", "checkout"]);
+  });
+
+  it("clamps arity to available token count when command is shorter than arity", () => {
+    // npm run has arity 3; only ["npm", "run"] provided → return both.
+    expect(prefix(["npm", "run"])).toEqual(["npm", "run"]);
+  });
+
+  it("returns arity-2 prefix for pnpm run (longest match wins over pnpm)", () => {
+    // pnpm run <script> — arity 3 means include the script name.
+    expect(prefix(["pnpm", "run", "build"])).toEqual(["pnpm", "run", "build"]);
+  });
+
+  it("returns arity-2 prefix for cargo subcommands", () => {
+    expect(prefix(["cargo", "build", "--release"])).toEqual(["cargo", "build"]);
+  });
+
+  it("returns arity-2 prefix for kubectl subcommands", () => {
+    expect(prefix(["kubectl", "get", "pods"])).toEqual(["kubectl", "get"]);
+  });
+
+  it("returns arity-1 for bare 'ls' (args are paths)", () => {
+    expect(prefix(["ls", "-la", "/tmp"])).toEqual(["ls"]);
+  });
+});

package/tests/handlers/tool-call.test.ts

@@ -568,7 +568,8 @@ describe("handleToolCall — session recording on approved_for_session", () => {
       input: { command: "git status" },
     });
     await handleToolCall(deps, event, makeCtx());
-    expect(sessionRules.approve).toHaveBeenCalledWith("bash", "git *");
+    // git arity=2: "git status" prefix covers all 2 tokens → trailing wildcard.
+    expect(sessionRules.approve).toHaveBeenCalledWith("bash", "git status*");
   });
 
   it("records mcp session approval with suggestMcpPattern result", async () => {

package/tests/pattern-suggest.test.ts

@@ -6,25 +6,42 @@ import {
 } from "../src/pattern-suggest";
 
 describe("suggestBashPattern", () => {
-  it("returns <command> * for a multi-word command", () => {
-    expect(suggestBashPattern("git status --short")).toBe("git *");
+  it("returns <command> <subcommand> * using the arity table", () => {
+    // git arity=2: include the subcommand in the prefix.
+    expect(suggestBashPattern("git status --short")).toBe("git status *");
   });
 
-  it("uses only the first word as the base", () => {
-    expect(suggestBashPattern("npm run build")).toBe("npm *");
+  it("appends trailing * when arity covers all tokens (multi-word script name)", () => {
+    // npm run arity=3: prefix covers all three tokens → trailing wildcard.
+    expect(suggestBashPattern("npm run build")).toBe("npm run build*");
   });
 
   it("returns the exact command when there are no arguments", () => {
     expect(suggestBashPattern("ls")).toBe("ls");
   });
 
-  it("trims leading and trailing whitespace", () => {
-    expect(suggestBashPattern("  git log  ")).toBe("git *");
+  it("trims leading and trailing whitespace before lookup", () => {
+    // git arity=2, tokens=["git","log"], prefix covers all → trailing wildcard.
+    expect(suggestBashPattern("  git log  ")).toBe("git log*");
   });
 
   it("handles empty string gracefully", () => {
     expect(suggestBashPattern("")).toBe("");
   });
+
+  it("falls back to first-word prefix for unknown commands", () => {
+    expect(suggestBashPattern("mytool --verbose run")).toBe("mytool *");
+  });
+
+  it("returns first-word * for known arity-1 commands with args", () => {
+    expect(suggestBashPattern("rm -rf node_modules")).toBe("rm *");
+  });
+
+  it("produces tighter pattern for docker compose than plain docker", () => {
+    expect(suggestBashPattern("docker compose up --build")).toBe(
+      "docker compose up *",
+    );
+  });
 });
 
 describe("suggestMcpPattern", () => {
@@ -52,11 +69,12 @@ describe("suggestMcpPattern", () => {
 
 describe("suggestSessionPattern", () => {
   describe("bash surface", () => {
-    it("returns bash surface with <command> * pattern for multi-word command", () => {
+    it("returns arity-aware subcommand pattern for multi-word command", () => {
+      // git arity=2: include the subcommand token in the prefix.
       const result = suggestSessionPattern("bash", "git status --short");
       expect(result).toMatchObject({
         surface: "bash",
-        pattern: "git *",
+        pattern: "git status *",
       });
     });
 
@@ -122,8 +140,9 @@ describe("suggestSessionPattern", () => {
 
   describe("label field", () => {
     it("includes the suggested pattern in the label", () => {
+      // git arity=2, "git status" has 2 tokens → trailing wildcard.
       const result = suggestSessionPattern("bash", "git status");
-      expect(result.label).toContain("git *");
+      expect(result.label).toContain("git status*");
     });
 
     it("wraps the pattern in quotes in the label", () => {