@gotgenes/pi-permission-system 4.6.0 → 4.8.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.8.0](https://github.com/gotgenes/pi-permission-system/compare/v4.7.0...v4.8.0) (2026-05-05)
+
+
+### Features
+
+* add expandHomePath utility for ~ and $HOME expansion ([18264e1](https://github.com/gotgenes/pi-permission-system/commit/18264e104f6aa12ca004a127d0f7b09b9e4fb740))
+* expand ~ and $HOME in wildcard patterns at compile time ([3c7e0c2](https://github.com/gotgenes/pi-permission-system/commit/3c7e0c2ab92c1e6bb58fdab32cfd9ae2c72e100a))
+
+
+### Documentation
+
+* document ~/$HOME pattern expansion in schema, example config, and README ([8ad5190](https://github.com/gotgenes/pi-permission-system/commit/8ad51909512ca294c83876868407866290234882))
+* plan home directory expansion in permission patterns ([#53](https://github.com/gotgenes/pi-permission-system/issues/53)) ([b5b77b6](https://github.com/gotgenes/pi-permission-system/commit/b5b77b640006b67b51420135be8fb78484c9d9a1))
+* **retro:** add retro notes for issue [#52](https://github.com/gotgenes/pi-permission-system/issues/52) ([7fc8113](https://github.com/gotgenes/pi-permission-system/commit/7fc8113390fd1dd9cf09c05e903d597c16d80104))
+* sleep before pulling release commit and tag ([af701b5](https://github.com/gotgenes/pi-permission-system/commit/af701b543b20f274ca9f8aa904af0a39bc232c26))
+
+## [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

@@ -156,7 +156,7 @@ The `permission` object maps surface names to actions:
 | `bash` | string or object | Bash catch-all or `{ pattern: action }` map |
 | `mcp` | string or object | MCP catch-all or `{ pattern: action }` map |
 | `skill` | string or object | Skill catch-all or `{ pattern: action }` map |
-| `external_directory` | string | Controls access to paths outside `cwd` |
+| `external_directory` | string or object | Controls access to paths outside `cwd`; supports `~/` and `$HOME/` patterns |
 
 > **Note:** Trailing commas are **not** supported. If parsing fails, the extension falls back to `ask` for all categories.
 
@@ -330,14 +330,36 @@ Skill name patterns use `*` wildcards (note: surface is `skill`, not `skills`):
 }
 ```
 
+### Home directory expansion in patterns
+
+Pattern keys in any permission surface can start with `~/` or `$HOME/` (or be exactly `~` / `$HOME`).
+They are expanded to the OS home directory at match time, so configs are portable across machines and users.
+
+```jsonc
+{
+  "permission": {
+    "external_directory": {
+      "*": "ask",
+      "~/development/*": "allow"
+    }
+  }
+}
+```
+
+The pattern is stored and displayed as written (e.g. `~/development/*`) in logs and approval dialogs.
+
 ### `external_directory` surface
 
-Controls access to paths outside the active working directory:
+Controls access to paths outside the active working directory.
+Use a pattern map to allow specific directories without opening all external access:
 
 ```jsonc
 {
   "permission": {
-    "external_directory": "ask"
+    "external_directory": {
+      "*": "ask",
+      "~/development/*": "allow"
+    }
   }
 }
 ```
@@ -450,13 +472,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 +546,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/config/config.example.json

@@ -17,6 +17,9 @@
     },
     "mcp": { "*": "ask", "mcp_status": "allow", "mcp_list": "allow" },
     "skill": { "*": "ask" },
-    "external_directory": "ask"
+    "external_directory": {
+      "*": "ask",
+      "~/development/*": "allow"
+    }
   }
 }

package/package.json

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

package/schemas/permissions.schema.json

@@ -88,10 +88,10 @@
     },
     "permissionMap": {
       "description": "A map of wildcard patterns to permission states. Last matching pattern wins.",
-      "markdownDescription": "A map of wildcard patterns to permission states.\n\nUse `*` for wildcard matching. When multiple patterns match, the **last matching rule wins** — put broad catch-alls first and specific overrides after them.",
+      "markdownDescription": "A map of wildcard patterns to permission states.\n\nUse `*` for wildcard matching. When multiple patterns match, the **last matching rule wins** — put broad catch-alls first and specific overrides after them.\n\nPattern keys support home directory expansion:\n- `~/path` or `$HOME/path` — expanded to the OS home directory at match time.\n- `~` or `$HOME` alone — expands to the home directory itself.\n\nThe stored pattern is always shown in logs and approval dialogs as written (e.g. `~/dev/*`).",
       "type": "object",
       "propertyNames": {
-        "description": "A non-empty pattern string. Use * for wildcard matching.",
+        "description": "A non-empty pattern string. Use * for wildcard matching. Prefix with ~/ or $HOME/ for home-relative paths.",
         "type": "string",
         "minLength": 1
       },

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/expand-home.ts

@@ -0,0 +1,28 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Expand `~` and `$HOME` prefixes in a pattern to the OS home directory.
+ *
+ * Supported forms:
+ * - `~`          → `homedir()`
+ * - `~/path`     → `homedir()/path`
+ * - `~\path`     → `homedir()\path` (Windows)
+ * - `$HOME`      → `homedir()`
+ * - `$HOME/path` → `homedir()/path`
+ * - `$HOME\path` → `homedir()\path` (Windows)
+ *
+ * All other patterns are returned unchanged.
+ */
+export function expandHomePath(pattern: string): string {
+  if (pattern === "~" || pattern === "$HOME") {
+    return homedir();
+  }
+  if (pattern.startsWith("~/") || pattern.startsWith("~\\")) {
+    return join(homedir(), pattern.slice(2));
+  }
+  if (pattern.startsWith("$HOME/") || pattern.startsWith("$HOME\\")) {
+    return join(homedir(), pattern.slice(6));
+  }
+  return pattern;
+}

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/src/wildcard-matcher.ts

@@ -1,3 +1,5 @@
+import { expandHomePath } from "./expand-home";
+
 export type CompiledWildcardPattern<TState> = {
   pattern: string;
   state: TState;
@@ -18,7 +20,8 @@ export function compileWildcardPattern<TState>(
   pattern: string,
   state: TState,
 ): CompiledWildcardPattern<TState> {
-  const escaped = pattern
+  const expanded = expandHomePath(pattern);
+  const escaped = expanded
     .split("*")
     .map((part) => escapeRegExp(part))
     .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/expand-home.test.ts

@@ -0,0 +1,93 @@
+import { join } from "node:path";
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+const mockHomedir = vi.hoisted(() => vi.fn(() => "/home/testuser"));
+
+vi.mock("node:os", () => ({
+  homedir: mockHomedir,
+  default: { homedir: mockHomedir },
+}));
+
+import { expandHomePath } from "../src/expand-home";
+
+const FAKE_HOME = "/home/testuser";
+
+afterEach(() => {
+  mockHomedir.mockClear();
+});
+
+describe("expandHomePath", () => {
+  describe("~ expansion", () => {
+    test("bare ~ expands to homedir()", () => {
+      expect(expandHomePath("~")).toBe(FAKE_HOME);
+    });
+
+    test("~/path expands to homedir()/path", () => {
+      expect(expandHomePath("~/dev/project")).toBe(
+        join(FAKE_HOME, "dev/project"),
+      );
+    });
+
+    test("~/path/* expands to homedir()/path/*", () => {
+      expect(expandHomePath("~/dev/*")).toBe(join(FAKE_HOME, "dev/*"));
+    });
+
+    test("~\\ (Windows separator) expands to homedir() + rest", () => {
+      expect(expandHomePath("~\\dev\\project")).toBe(
+        join(FAKE_HOME, "dev\\project"),
+      );
+    });
+
+    test("~username (no separator) is not expanded (no-op)", () => {
+      expect(expandHomePath("~username")).toBe("~username");
+    });
+  });
+
+  describe("$HOME expansion", () => {
+    test("bare $HOME expands to homedir()", () => {
+      expect(expandHomePath("$HOME")).toBe(FAKE_HOME);
+    });
+
+    test("$HOME/path expands to homedir()/path", () => {
+      expect(expandHomePath("$HOME/dev/project")).toBe(
+        join(FAKE_HOME, "dev/project"),
+      );
+    });
+
+    test("$HOME/path/* expands to homedir()/path/*", () => {
+      expect(expandHomePath("$HOME/dev/*")).toBe(join(FAKE_HOME, "dev/*"));
+    });
+
+    test("$HOME\\ (Windows separator) expands to homedir() + rest", () => {
+      expect(expandHomePath("$HOME\\dev\\project")).toBe(
+        join(FAKE_HOME, "dev\\project"),
+      );
+    });
+
+    test("$HOMEDIR (no separator) is not expanded (no-op)", () => {
+      expect(expandHomePath("$HOMEDIR")).toBe("$HOMEDIR");
+    });
+  });
+
+  describe("no-op patterns", () => {
+    test("absolute path is unchanged", () => {
+      expect(expandHomePath("/usr/local/bin")).toBe("/usr/local/bin");
+    });
+
+    test("relative path is unchanged", () => {
+      expect(expandHomePath("dev/project")).toBe("dev/project");
+    });
+
+    test("glob-only pattern is unchanged", () => {
+      expect(expandHomePath("*")).toBe("*");
+    });
+
+    test("empty string is unchanged", () => {
+      expect(expandHomePath("")).toBe("");
+    });
+
+    test("bash command pattern starting with a word is unchanged", () => {
+      expect(expandHomePath("git push *")).toBe("git push *");
+    });
+  });
+});

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", () => {

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

@@ -5,7 +5,7 @@
  * Step 6: all five surfaces produce identical decisions to the old branching code.
  */
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { PermissionManager } from "../src/permission-manager";
@@ -373,3 +373,76 @@ describe("checkPermission — source derivation and matchedPattern", () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Home directory expansion in external_directory patterns
+// ---------------------------------------------------------------------------
+
+describe("checkPermission — home path expansion in external_directory rules", () => {
+  it("~/glob pattern allows a path under the real home directory", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      "*": "ask",
+      external_directory: { "~/trusted/*": "allow" },
+    });
+    try {
+      const result = manager.checkPermission("external_directory", {
+        path: join(homedir(), "trusted/repo"),
+      });
+      expect(result.state).toBe("allow");
+      expect(result.source).toBe("special");
+      expect(result.matchedPattern).toBe("~/trusted/*");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("$HOME/glob pattern allows a path under the real home directory", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      "*": "ask",
+      external_directory: { "$HOME/trusted/*": "allow" },
+    });
+    try {
+      const result = manager.checkPermission("external_directory", {
+        path: join(homedir(), "trusted/repo"),
+      });
+      expect(result.state).toBe("allow");
+      expect(result.source).toBe("special");
+      expect(result.matchedPattern).toBe("$HOME/trusted/*");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("~/glob deny rule blocks a path under home", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      "*": "allow",
+      external_directory: { "~/private/*": "deny" },
+    });
+    try {
+      const result = manager.checkPermission("external_directory", {
+        path: join(homedir(), "private/secrets.txt"),
+      });
+      expect(result.state).toBe("deny");
+      expect(result.matchedPattern).toBe("~/private/*");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("~/glob pattern does not match a path outside home", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      "*": "ask",
+      external_directory: { "~/trusted/*": "allow" },
+    });
+    try {
+      const result = manager.checkPermission("external_directory", {
+        path: "/tmp/not-home/file",
+      });
+      // Falls back to the "*": "ask" default — no allow from the ~/trusted/* rule.
+      expect(result.state).toBe("ask");
+      expect(result.matchedPattern).toBeUndefined();
+    } finally {
+      cleanup();
+    }
+  });
+});

package/tests/wildcard-matcher.test.ts

@@ -1,5 +1,15 @@
+import { join } from "node:path";
 import { afterEach, describe, expect, test, vi } from "vitest";
 
+const mockHomedir = vi.hoisted(() => vi.fn(() => "/home/testuser"));
+
+vi.mock("node:os", () => ({
+  homedir: mockHomedir,
+  default: { homedir: mockHomedir },
+}));
+
+const FAKE_HOME = "/home/testuser";
+
 import {
   compileWildcardPattern,
   compileWildcardPatternEntries,
@@ -9,6 +19,7 @@ import {
 } from "../src/wildcard-matcher";
 
 afterEach(() => {
+  mockHomedir.mockClear();
   vi.restoreAllMocks();
 });
 
@@ -233,3 +244,50 @@ describe("wildcardMatch", () => {
     expect(wildcardMatch("tool.name", "toolXname")).toBe(false);
   });
 });
+
+describe("home path expansion in patterns", () => {
+  test("wildcardMatch expands ~ prefix in pattern before matching", () => {
+    const expandedPath = join(FAKE_HOME, "dev/project");
+    expect(wildcardMatch("~/dev/project", expandedPath)).toBe(true);
+  });
+
+  test("wildcardMatch expands ~/glob in pattern", () => {
+    const expandedFile = join(FAKE_HOME, "dev/project/file.ts");
+    expect(wildcardMatch("~/dev/*", expandedFile)).toBe(true);
+  });
+
+  test("wildcardMatch ~/glob does not match a different home directory", () => {
+    expect(wildcardMatch("~/dev/*", "/other/user/dev/file.ts")).toBe(false);
+  });
+
+  test("wildcardMatch expands $HOME prefix in pattern before matching", () => {
+    const expandedPath = join(FAKE_HOME, "dev/project");
+    expect(wildcardMatch("$HOME/dev/project", expandedPath)).toBe(true);
+  });
+
+  test("wildcardMatch expands $HOME/glob in pattern", () => {
+    const expandedFile = join(FAKE_HOME, "work/file.ts");
+    expect(wildcardMatch("$HOME/work/*", expandedFile)).toBe(true);
+  });
+
+  test("compileWildcardPattern retains original ~ pattern in .pattern field", () => {
+    const compiled = compileWildcardPattern("~/dev/*", "allow");
+    expect(compiled.pattern).toBe("~/dev/*");
+  });
+
+  test("compileWildcardPattern retains original $HOME pattern in .pattern field", () => {
+    const compiled = compileWildcardPattern("$HOME/dev/*", "allow");
+    expect(compiled.pattern).toBe("$HOME/dev/*");
+  });
+
+  test("compileWildcardPattern expanded regex matches the expanded path", () => {
+    const compiled = compileWildcardPattern("~/dev/*", "allow");
+    const expandedFile = join(FAKE_HOME, "dev/file.ts");
+    expect(compiled.regex.test(expandedFile)).toBe(true);
+  });
+
+  test("non-home pattern is unaffected", () => {
+    expect(wildcardMatch("/absolute/path/*", "/absolute/path/file")).toBe(true);
+    expect(wildcardMatch("/absolute/path/*", "/other/file")).toBe(false);
+  });
+});