@gotgenes/pi-permission-system 29.2.0 → 29.3.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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).
 
+## [29.3.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v29.2.0...pi-permission-system-v29.3.0) (2026-09-02)
+
+
+### Features
+
+* **pi-permission-system:** name and document the well-known permission surfaces ([#808](https://github.com/gotgenes/pi-packages/issues/808)) ([95ef9ab](https://github.com/gotgenes/pi-packages/commit/95ef9ab9c00ee09d4dda820d43abc7fe7e5ff1b2)), closes [#808](https://github.com/gotgenes/pi-packages/issues/808)
+
+### Documentation
+
+* **pi-permission-system:** document the named permission surfaces ([#808](https://github.com/gotgenes/pi-packages/issues/808)) ([03c6a52](https://github.com/gotgenes/pi-packages/commit/03c6a5228aa050ac940d851e6c219e62062acbd6))
+
+### Miscellaneous Chores
+
+* upgrade lint tooling and pin rumdl below the MD013 reflow regression ([0ee1ad8](https://github.com/gotgenes/pi-packages/commit/0ee1ad886815e6e50d99f66050fbbcf5a9f0319a)), closes [#866](https://github.com/gotgenes/pi-packages/issues/866)
+* upgrade fallow to 3.22.0 ([1b2a562](https://github.com/gotgenes/pi-packages/commit/1b2a5620bf5d7f1014676b47e58df8b43ff00496)), closes [#866](https://github.com/gotgenes/pi-packages/issues/866)
+
 ## [29.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v29.1.0...pi-permission-system-v29.2.0) (2026-09-01)
 
 

package/docs/configuration.md

@@ -1204,4 +1204,6 @@ npx --yes ajv-cli@5 validate \
 "$schema": "https://raw.githubusercontent.com/gotgenes/pi-packages/main/packages/pi-permission-system/schemas/permissions.schema.json"
 ```
 
+The well-known surface keys — `*`, `path`, `external_directory`, `bash`, `mcp`, `skill`, and the four directional keys — are named properties in the schema, so an editor completes them and shows each key's own documentation on hover; any other registered tool name still validates as a surface.
+
 The schema is generated from the extension's zod source of truth (`src/config-schema.ts`); regenerate it with `pnpm run gen:schema` after changing the config shape.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "29.2.0",
+  "version": "29.3.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -67,15 +67,15 @@
     "@earendil-works/pi-tui": ">=0.79.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.16",
+    "@biomejs/biome": "^2.5.11",
     "@earendil-works/pi-coding-agent": "0.79.1",
     "@earendil-works/pi-tui": "0.79.1",
     "@types/node": "^22.15.3",
-    "rollup": "^4.62.2",
-    "rollup-plugin-dts": "^6.4.1",
-    "rumdl": "^0.2.10",
+    "rollup": "^4.63.1",
+    "rollup-plugin-dts": "^6.5.1",
+    "rumdl": "0.2.24",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.11"
   },
   "dependencies": {
     "tree-sitter-bash": "^0.25.1",

package/schemas/permissions.schema.json

@@ -102,6 +102,30 @@
     "permission": {
       "type": "object",
       "properties": {
+        "*": {
+          "description": "Universal fallback — the action used when no surface-specific rule matches. Omitted, it defaults to ask.",
+          "markdownDescription": "Universal fallback — the action used when **no** surface-specific rule matches.\n\n`{ \"*\": \"ask\" }` is the least-privilege posture, and is what an omitted `\"*\"` means anyway. It replaces `defaultPolicy.tools` from the legacy config format.\n\nA surface-specific rule always beats it, whatever the key order in the file.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/permissionState"
+            },
+            {
+              "$ref": "#/$defs/permissionMap"
+            }
+          ]
+        },
+        "path": {
+          "description": "Cross-cutting gate for file access by path pattern, across every path-aware tool. Sugar for both directions.",
+          "markdownDescription": "Cross-cutting gate that applies to **all** file access: Pi tools, bash commands, MCP calls (via `input.arguments.path`), and extension tools (via `input.path` or a registered access extractor).\n\nA `path` deny cannot be overridden by a per-tool allow. Use it to protect sensitive files (`.env`, `~/.ssh/*`) from every path-aware tool at once.\n\nThis bare key is **sugar**: it expands at load into `path_read` and `path_write`, its entries placed first, so an explicit directional entry always has the final say whatever the key order in the file.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/permissionState"
+            },
+            {
+              "$ref": "#/$defs/permissionMap"
+            }
+          ]
+        },
         "path_read": {
           "description": "Cross-cutting gate for reading a file, by path pattern. The useful directional grant.",
           "markdownDescription": "Cross-cutting gate for **reading** a file, matched by path pattern across all path-aware tools.\n\nThis is the directional key worth granting: `\"path_read\": { \"~/dev/*\": \"allow\" }` permits reads without permitting writes.\n\nA bare `\"path\"` key is sugar that expands into this key **and** `path_write`, with its entries placed first — so an explicit `path_read` entry always has the final say, whatever the key order in the file.",
@@ -126,6 +150,18 @@
             }
           ]
         },
+        "external_directory": {
+          "description": "Boundary gate for access outside the session working directory. Sugar for both directions.",
+          "markdownDescription": "Boundary gate for access **outside** the session working directory.\n\nGive it a pattern map to allow specific outside-CWD directories without opening all external access — e.g. `{ \"*\": \"ask\", \"~/.cargo/registry/*\": \"allow\" }` to silence repeated prompts on a local cache. The trailing `*` is greedy and crosses subdirectory boundaries; a bare `~/.cargo/registry` matches only the directory entry itself.\n\nBecause layers compose with most-restrictive-wins, a `path` allow cannot loosen an `external_directory: ask` boundary — allow outside-CWD directories here, not on `path`.\n\nThis bare key is **sugar**: it expands at load into `external_directory_read` and `external_directory_write`, its entries placed first.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/permissionState"
+            },
+            {
+              "$ref": "#/$defs/permissionMap"
+            }
+          ]
+        },
         "external_directory_read": {
           "description": "Boundary gate for reading outside the working directory. The relief most asks want.",
           "markdownDescription": "Boundary gate for **reading** a path outside the session working directory.\n\nThe one-line grant for an external root: `\"external_directory_read\": { \"~/dev/*\": \"allow\" }` silences repeated read prompts on a directory outside the tree while a write to the same path still prompts. No parallel `path_read` entry is needed.",
@@ -149,6 +185,42 @@
               "$ref": "#/$defs/permissionMap"
             }
           ]
+        },
+        "bash": {
+          "description": "Shell command execution, matched per top-level command in a chain. Most restrictive wins.",
+          "markdownDescription": "Shell command execution, matched by **command pattern**.\n\nA chain (`&&`, `||`, `;`, `|`, newline) is split into its top-level commands and each is matched independently, most-restrictive-wins — so `cd /repo && npm install x` is denied when `npm *` is. A command nested in a substitution, process substitution, or subshell is matched too, since it really runs.\n\nA leading env-var assignment is stripped before matching (`AWS_PROFILE=prod aws …` matches `aws *`), and a pattern ending in ` *` (space + wildcard) also matches the bare command (`git *` matches `git`). A pattern containing a chain operator never matches — write one pattern per command.\n\nA shell wrapper (`bash -c`, `eval`, `sudo`, `xargs`) is floored from `allow` to `ask`, so an opaque payload cannot ride a permissive rule.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/permissionState"
+            },
+            {
+              "$ref": "#/$defs/permissionMap"
+            }
+          ]
+        },
+        "mcp": {
+          "description": "Registered MCP proxy tools, matched against targets derived from the tool input.",
+          "markdownDescription": "Registered MCP proxy tools, matched against targets derived from the tool input: a baseline op (`mcp_status`, `mcp_list`, `mcp_search`, `mcp_describe`, `mcp_connect`), a server name (`myServer`), a server/tool combination (`myServer:search`, `myServer_search`), or the generic `mcp_call`.\n\nBaseline discovery targets auto-allow whenever any explicit `mcp` allow rule exists.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/permissionState"
+            },
+            {
+              "$ref": "#/$defs/permissionMap"
+            }
+          ]
+        },
+        "skill": {
+          "description": "Skill invocation, matched by skill name. The surface is `skill`, not `skills`.",
+          "markdownDescription": "Skill invocation, matched by skill name — the surface is `skill`, not `skills`.\n\nWildcards behave as everywhere else: `{ \"*\": \"ask\", \"dangerous-*\": \"deny\", \"librarian\": \"allow\" }`.",
+          "anyOf": [
+            {
+              "$ref": "#/$defs/permissionState"
+            },
+            {
+              "$ref": "#/$defs/permissionMap"
+            }
+          ]
         }
       },
       "additionalProperties": {
@@ -162,7 +234,7 @@
         ]
       },
       "description": "Flat permission policy. Each key is a surface name; values are a PermissionState string (catch-all) or a pattern→action map.",
-      "markdownDescription": "Flat permission policy.\n\nEach top-level key is a surface name:\n- `\"*\"` — universal fallback (replaces `defaultPolicy.tools` from the legacy format)\n- Tool names (`read`, `write`, `bash`, `mcp`, `skill`, `external_directory`, `path`, etc.)\n\nA **string** value is shorthand for `{ \"*\": action }` (surface-level catch-all).\nAn **object** value maps wildcard patterns to actions — last matching pattern wins.\n\nFor built-in file tools (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns are matched against the file path from `input.path`. For example, `\"read\": { \"*\": \"allow\", \"*.env\": \"deny\" }` allows reads but denies `.env` files.\n\nWhen Pi's current working directory is known, relative path inputs also match their cwd-normalized absolute form, so `src/App.jsx` can match both `src/*` and `/workspace/project/*`. Bash path tokens use the effective directory after literal `cd` commands for this matching; non-literal `cd \"$DIR\"` style commands remain conservative.\n\nThe `path` surface is a cross-cutting gate that applies to **all** file access: Pi tools, bash commands, MCP calls (via `input.arguments.path`), and extension tools (via `input.path` or a registered access extractor). A `path` deny cannot be overridden by a per-tool allow. Use it to protect sensitive files (`.env`, `~/.ssh/*`) from all path-aware tools at once.\n\nThe `external_directory` surface gates access **outside** the working directory. Give it a pattern map to allow specific outside-CWD directories without opening all external access — e.g. `\"external_directory\": { \"*\": \"ask\", \"~/.cargo/registry/*\": \"allow\" }` to silence repeated prompts on a local cache. The trailing `*` is greedy and crosses subdirectory boundaries; a bare `~/.cargo/registry` matches only the directory entry itself. Because layers compose with most-restrictive-wins, a `path` allow cannot loosen an `external_directory: ask` boundary — allow outside-CWD directories here, not on `path`.\n\n**Merge order (lowest → highest precedence):** global → project → per-agent frontmatter.",
+      "markdownDescription": "Flat permission policy.\n\nEach top-level key is a surface: the `\"*\"` fallback, a well-known surface documented below, or any registered tool name.\n\nA **string** value is shorthand for `{ \"*\": action }` (a surface-level catch-all).\nAn **object** value maps wildcard patterns to actions — last matching pattern wins.\n\nFor built-in file tools (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns are matched against the file path from `input.path`. For example, `\"read\": { \"*\": \"allow\", \"*.env\": \"deny\" }` allows reads but denies `.env` files.\n\nWhen Pi's current working directory is known, relative path inputs also match their cwd-normalized absolute form, so `src/App.jsx` can match both `src/*` and `/workspace/project/*`. Bash path tokens use the effective directory after literal `cd` commands for this matching; non-literal `cd \"$DIR\"` style commands remain conservative.\n\n**Merge order (lowest → highest precedence):** global → project → per-agent frontmatter.",
       "examples": [
         {
           "*": "ask",

package/src/config-schema.ts

@@ -79,57 +79,103 @@ const surfaceValueSchema = z.union([
 ]);
 
 /**
- * The `path` and `external_directory` families' directional members
- * (ADR 0013 §3), named so editors offer autocomplete and hover documentation.
+ * The legal spellings of a directional surface key (ADR 0013 §3).
  *
- * Naming them as properties rather than leaving them to the catchall is also
- * what lets the loader tell a legal directional key from a misspelled one —
- * see {@link rejectMisspelledDirectionalKeys}.
+ * This is the loader's allowlist — {@link rejectUnusableSurfaceKeys} rejects a
+ * key shaped like a directional surface that is not one of these — and the
+ * schema documents exactly these four as named properties. Nothing structural
+ * holds the two halves together, so a test in `config-schema.test.ts` does.
  */
-const DIRECTIONAL_SURFACE_DESCRIPTIONS: Record<
-  string,
-  { description: string; markdownDescription: string }
-> = {
-  path_read: {
-    description:
-      "Cross-cutting gate for reading a file, by path pattern. The useful directional grant.",
-    markdownDescription:
-      'Cross-cutting gate for **reading** a file, matched by path pattern across all path-aware tools.\n\nThis is the directional key worth granting: `"path_read": { "~/dev/*": "allow" }` permits reads without permitting writes.\n\nA bare `"path"` key is sugar that expands into this key **and** `path_write`, with its entries placed first — so an explicit `path_read` entry always has the final say, whatever the key order in the file.',
-  },
-  path_write: {
-    description:
-      "Cross-cutting gate for writing a file, by path pattern. Earns its keep as a restriction.",
-    markdownDescription:
-      'Cross-cutting gate for **writing** a file, matched by path pattern across all path-aware tools.\n\nThis key earns its keep as a *restriction* rather than a grant: `"path_write": { "*": "deny" }` is a coherent read-only-agent posture. A `"path_write": "allow"` on its own does not silence an `edit`, which also reads — grant `path_read` too, or use the bare `"path"` key.',
-  },
-  external_directory_read: {
-    description:
-      "Boundary gate for reading outside the working directory. The relief most asks want.",
-    markdownDescription:
-      'Boundary gate for **reading** a path outside the session working directory.\n\nThe one-line grant for an external root: `"external_directory_read": { "~/dev/*": "allow" }` silences repeated read prompts on a directory outside the tree while a write to the same path still prompts. No parallel `path_read` entry is needed.',
-  },
-  external_directory_write: {
-    description: "Boundary gate for writing outside the working directory.",
-    markdownDescription:
-      'Boundary gate for **writing** to a path outside the session working directory.\n\nA bare `"external_directory"` key is sugar that expands into this key and `external_directory_read`; write this one only to give the two directions different answers.',
-  },
-};
+const DIRECTIONAL_SURFACE_KEYS = [
+  "path_read",
+  "path_write",
+  "external_directory_read",
+  "external_directory_write",
+] as const;
+
+/**
+ * One documented, optional property for a well-known permission surface.
+ *
+ * A named property is what an editor completes and hovers; the enclosing
+ * object's `.catchall(...)` is what keeps every other tool name valid. Each
+ * surface's prose lives here rather than on the object, so a reader gets the
+ * key under their cursor and not all nine of its neighbours.
+ */
+function surfaceProperty(meta: {
+  description: string;
+  markdownDescription: string;
+}) {
+  return surfaceValueSchema.optional().meta(meta);
+}
 
 const permissionSchema = z
-  .object(
-    Object.fromEntries(
-      Object.entries(DIRECTIONAL_SURFACE_DESCRIPTIONS).map(([key, meta]) => [
-        key,
-        surfaceValueSchema.optional().meta(meta),
-      ]),
-    ),
-  )
+  .object({
+    "*": surfaceProperty({
+      description:
+        "Universal fallback — the action used when no surface-specific rule matches. Omitted, it defaults to ask.",
+      markdownDescription:
+        'Universal fallback — the action used when **no** surface-specific rule matches.\n\n`{ "*": "ask" }` is the least-privilege posture, and is what an omitted `"*"` means anyway. It replaces `defaultPolicy.tools` from the legacy config format.\n\nA surface-specific rule always beats it, whatever the key order in the file.',
+    }),
+    path: surfaceProperty({
+      description:
+        "Cross-cutting gate for file access by path pattern, across every path-aware tool. Sugar for both directions.",
+      markdownDescription:
+        "Cross-cutting gate that applies to **all** file access: Pi tools, bash commands, MCP calls (via `input.arguments.path`), and extension tools (via `input.path` or a registered access extractor).\n\nA `path` deny cannot be overridden by a per-tool allow. Use it to protect sensitive files (`.env`, `~/.ssh/*`) from every path-aware tool at once.\n\nThis bare key is **sugar**: it expands at load into `path_read` and `path_write`, its entries placed first, so an explicit directional entry always has the final say whatever the key order in the file.",
+    }),
+    path_read: surfaceProperty({
+      description:
+        "Cross-cutting gate for reading a file, by path pattern. The useful directional grant.",
+      markdownDescription:
+        'Cross-cutting gate for **reading** a file, matched by path pattern across all path-aware tools.\n\nThis is the directional key worth granting: `"path_read": { "~/dev/*": "allow" }` permits reads without permitting writes.\n\nA bare `"path"` key is sugar that expands into this key **and** `path_write`, with its entries placed first — so an explicit `path_read` entry always has the final say, whatever the key order in the file.',
+    }),
+    path_write: surfaceProperty({
+      description:
+        "Cross-cutting gate for writing a file, by path pattern. Earns its keep as a restriction.",
+      markdownDescription:
+        'Cross-cutting gate for **writing** a file, matched by path pattern across all path-aware tools.\n\nThis key earns its keep as a *restriction* rather than a grant: `"path_write": { "*": "deny" }` is a coherent read-only-agent posture. A `"path_write": "allow"` on its own does not silence an `edit`, which also reads — grant `path_read` too, or use the bare `"path"` key.',
+    }),
+    external_directory: surfaceProperty({
+      description:
+        "Boundary gate for access outside the session working directory. Sugar for both directions.",
+      markdownDescription:
+        'Boundary gate for access **outside** the session working directory.\n\nGive it a pattern map to allow specific outside-CWD directories without opening all external access — e.g. `{ "*": "ask", "~/.cargo/registry/*": "allow" }` to silence repeated prompts on a local cache. The trailing `*` is greedy and crosses subdirectory boundaries; a bare `~/.cargo/registry` matches only the directory entry itself.\n\nBecause layers compose with most-restrictive-wins, a `path` allow cannot loosen an `external_directory: ask` boundary — allow outside-CWD directories here, not on `path`.\n\nThis bare key is **sugar**: it expands at load into `external_directory_read` and `external_directory_write`, its entries placed first.',
+    }),
+    external_directory_read: surfaceProperty({
+      description:
+        "Boundary gate for reading outside the working directory. The relief most asks want.",
+      markdownDescription:
+        'Boundary gate for **reading** a path outside the session working directory.\n\nThe one-line grant for an external root: `"external_directory_read": { "~/dev/*": "allow" }` silences repeated read prompts on a directory outside the tree while a write to the same path still prompts. No parallel `path_read` entry is needed.',
+    }),
+    external_directory_write: surfaceProperty({
+      description: "Boundary gate for writing outside the working directory.",
+      markdownDescription:
+        'Boundary gate for **writing** to a path outside the session working directory.\n\nA bare `"external_directory"` key is sugar that expands into this key and `external_directory_read`; write this one only to give the two directions different answers.',
+    }),
+    bash: surfaceProperty({
+      description:
+        "Shell command execution, matched per top-level command in a chain. Most restrictive wins.",
+      markdownDescription:
+        "Shell command execution, matched by **command pattern**.\n\nA chain (`&&`, `||`, `;`, `|`, newline) is split into its top-level commands and each is matched independently, most-restrictive-wins — so `cd /repo && npm install x` is denied when `npm *` is. A command nested in a substitution, process substitution, or subshell is matched too, since it really runs.\n\nA leading env-var assignment is stripped before matching (`AWS_PROFILE=prod aws …` matches `aws *`), and a pattern ending in ` *` (space + wildcard) also matches the bare command (`git *` matches `git`). A pattern containing a chain operator never matches — write one pattern per command.\n\nA shell wrapper (`bash -c`, `eval`, `sudo`, `xargs`) is floored from `allow` to `ask`, so an opaque payload cannot ride a permissive rule.",
+    }),
+    mcp: surfaceProperty({
+      description:
+        "Registered MCP proxy tools, matched against targets derived from the tool input.",
+      markdownDescription:
+        "Registered MCP proxy tools, matched against targets derived from the tool input: a baseline op (`mcp_status`, `mcp_list`, `mcp_search`, `mcp_describe`, `mcp_connect`), a server name (`myServer`), a server/tool combination (`myServer:search`, `myServer_search`), or the generic `mcp_call`.\n\nBaseline discovery targets auto-allow whenever any explicit `mcp` allow rule exists.",
+    }),
+    skill: surfaceProperty({
+      description:
+        "Skill invocation, matched by skill name. The surface is `skill`, not `skills`.",
+      markdownDescription:
+        'Skill invocation, matched by skill name — the surface is `skill`, not `skills`.\n\nWildcards behave as everywhere else: `{ "*": "ask", "dangerous-*": "deny", "librarian": "allow" }`.',
+    }),
+  })
   .catchall(surfaceValueSchema)
   .meta({
     description:
       "Flat permission policy. Each key is a surface name; values are a PermissionState string (catch-all) or a pattern→action map.",
     markdownDescription:
-      'Flat permission policy.\n\nEach top-level key is a surface name:\n- `"*"` — universal fallback (replaces `defaultPolicy.tools` from the legacy format)\n- Tool names (`read`, `write`, `bash`, `mcp`, `skill`, `external_directory`, `path`, etc.)\n\nA **string** value is shorthand for `{ "*": action }` (surface-level catch-all).\nAn **object** value maps wildcard patterns to actions — last matching pattern wins.\n\nFor built-in file tools (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns are matched against the file path from `input.path`. For example, `"read": { "*": "allow", "*.env": "deny" }` allows reads but denies `.env` files.\n\nWhen Pi\'s current working directory is known, relative path inputs also match their cwd-normalized absolute form, so `src/App.jsx` can match both `src/*` and `/workspace/project/*`. Bash path tokens use the effective directory after literal `cd` commands for this matching; non-literal `cd "$DIR"` style commands remain conservative.\n\nThe `path` surface is a cross-cutting gate that applies to **all** file access: Pi tools, bash commands, MCP calls (via `input.arguments.path`), and extension tools (via `input.path` or a registered access extractor). A `path` deny cannot be overridden by a per-tool allow. Use it to protect sensitive files (`.env`, `~/.ssh/*`) from all path-aware tools at once.\n\nThe `external_directory` surface gates access **outside** the working directory. Give it a pattern map to allow specific outside-CWD directories without opening all external access — e.g. `"external_directory": { "*": "ask", "~/.cargo/registry/*": "allow" }` to silence repeated prompts on a local cache. The trailing `*` is greedy and crosses subdirectory boundaries; a bare `~/.cargo/registry` matches only the directory entry itself. Because layers compose with most-restrictive-wins, a `path` allow cannot loosen an `external_directory: ask` boundary — allow outside-CWD directories here, not on `path`.\n\n**Merge order (lowest → highest precedence):** global → project → per-agent frontmatter.',
+      'Flat permission policy.\n\nEach top-level key is a surface: the `"*"` fallback, a well-known surface documented below, or any registered tool name.\n\nA **string** value is shorthand for `{ "*": action }` (a surface-level catch-all).\nAn **object** value maps wildcard patterns to actions — last matching pattern wins.\n\nFor built-in file tools (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns are matched against the file path from `input.path`. For example, `"read": { "*": "allow", "*.env": "deny" }` allows reads but denies `.env` files.\n\nWhen Pi\'s current working directory is known, relative path inputs also match their cwd-normalized absolute form, so `src/App.jsx` can match both `src/*` and `/workspace/project/*`. Bash path tokens use the effective directory after literal `cd` commands for this matching; non-literal `cd "$DIR"` style commands remain conservative.\n\n**Merge order (lowest → highest precedence):** global → project → per-agent frontmatter.',
     examples: [
       {
         "*": "ask",
@@ -176,7 +222,7 @@ function rejectUnusableSurfaceKeys(
   permission: Record<string, unknown>,
   ctx: z.core.$RefinementCtx,
 ): void {
-  const legalDirectionalKeys = Object.keys(DIRECTIONAL_SURFACE_DESCRIPTIONS);
+  const legalDirectionalKeys: readonly string[] = DIRECTIONAL_SURFACE_KEYS;
   for (const key of Object.keys(permission)) {
     if (key === "") {
       ctx.addIssue({

package/src/config-store.ts

@@ -140,8 +140,6 @@ export class ConfigStore implements SessionConfigStore, CommandConfigStore {
    *
    * Equivalent to `saveExtensionConfig(runtime, next, ctx)`.
    */
-  // Called via the CommandConfigStore interface from config-modal.ts — fallow cannot trace through interfaces.
-  // fallow-ignore-next-line unused-class-member
   save(
     next: PermissionSystemExtensionConfig,
     ctx: ExtensionCommandContext,

package/src/normalize.ts

@@ -35,6 +35,11 @@ export function expandDirectionalSugar(
   const expanded: FlatPermissionConfig = {};
   for (const [surface, value] of Object.entries(permission)) {
     // A key present with an explicit `undefined` value carries no rules.
+    // `Object.entries` resolves to the catchall's non-optional value type, so
+    // the type cannot see this case even though a named optional surface
+    // admits it; dropping the guard expands `{ path: undefined }` into two
+    // empty directional surfaces. Pinned in `normalize.test.ts`.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime-reachable; see above
     if (value === undefined) continue;
     const members = surfaceFamilyMembers(surface);
     if (members === null) {