@gotgenes/pi-permission-system 18.2.0 → 19.0.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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).
 
+## [19.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v18.2.0...pi-permission-system-v19.0.0) (2026-07-06)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** The permission-system config loader was tolerant — it silently discarded malformed fields (a non-boolean `debugLog`, an invalid permission action, an unknown key) and loaded the rest. It now rejects the entire config file for that scope when any field is invalid, and reports each problem with its JSON path. On upgrade, a config that previously loaded with silently-dropped fields will be rejected until the reported problems are fixed; the affected scope falls back to the safe `ask` default until then. Fix each field named in the emitted issues (visible in the permission review log / debug log).
+
+### Features
+
+* **pi-permission-system:** add zod config schema as validation source ([6b71491](https://github.com/gotgenes/pi-packages/commit/6b71491b058d64e328139bd8ccfa104e9bbe2f5a))
+* **pi-permission-system:** generate JSON Schema from zod and fix hosted $id URL ([7b6556d](https://github.com/gotgenes/pi-packages/commit/7b6556d7676b8e6574cd01eeec2032a499b19649))
+* **pi-permission-system:** validate config with zod and reject invalid fields ([7e32cae](https://github.com/gotgenes/pi-packages/commit/7e32caea8f750637069ebaf243bb1db90ae745f7))
+
+
+### Documentation
+
+* **pi-permission-system:** document zod config schema and strict validation ([c8babf9](https://github.com/gotgenes/pi-packages/commit/c8babf962be56fa48eba22d5a7fe7ca34ccfa1e7))
+
 ## [18.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v18.1.2...pi-permission-system-v18.2.0) (2026-07-06)
 
 

package/README.md

@@ -132,6 +132,7 @@ If you relied on the old permissive behavior for bash, set an explicit permissiv
 | [docs/opencode-compatibility.md](docs/opencode-compatibility.md)                                                               | OpenCode compatibility — shared concepts, divergences, porting guide                    |
 | [docs/troubleshooting.md](docs/troubleshooting.md)                                                                             | Common issues, diagnostic logging, threat model                                         |
 | [docs/migration/legacy-to-flat.md](docs/migration/legacy-to-flat.md)                                                           | Migration from pre-v2 config layout                                                     |
+| [docs/migration/strict-config-validation.md](docs/migration/strict-config-validation.md)                                       | Strict config validation (breaking) — reading and fixing rejected configs               |
 
 ## Development
 

package/config/config.example.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-permission-system/main/schemas/permissions.schema.json",
+  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-packages/main/packages/pi-permission-system/schemas/permissions.schema.json",
 
   "debugLog": false,
   "permissionReviewLog": true,

package/docs/configuration.md

@@ -36,7 +36,7 @@ Scalar fields (`debugLog`, `permissionReviewLog`, `yoloMode`) use simple replace
 
 ```jsonc
 {
-  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-permission-system/main/schemas/permissions.schema.json",
+  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-packages/main/packages/pi-permission-system/schemas/permissions.schema.json",
 
   // Runtime knobs
   "debugLog": false,
@@ -697,4 +697,10 @@ npx --yes ajv-cli@5 validate \
   -d ./config.json
 ```
 
-**Editor tip:** Add `"$schema": "./schemas/permissions.schema.json"` to your config for autocomplete support.
+**Editor tip:** Add the hosted schema URL as the `$schema` key in your config for autocomplete and validation support:
+
+```json
+"$schema": "https://raw.githubusercontent.com/gotgenes/pi-packages/main/packages/pi-permission-system/schemas/permissions.schema.json"
+```
+
+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/docs/migration/strict-config-validation.md

@@ -0,0 +1,38 @@
+# Migration guide: strict config validation
+
+Starting with the release that closes #547, the permission-system config loader validates each config file against a JSON Schema derived from a zod source of truth.
+This is a **breaking change** in how malformed config is handled.
+
+## What changed
+
+The loader used to be **tolerant**: it silently discarded a malformed field and loaded the rest.
+For example, a config with `"debugLog": "yes"` (a string, not a boolean) simply dropped `debugLog` and kept going; an unknown key like `"debugLo": true` was ignored.
+
+The loader is now **strict and fail-closed**:
+
+- A config file with **any** invalid field is rejected as a whole scope (global or project).
+- The rejected scope contributes **no** permission rules, so its surfaces fall back to the safe universal `ask` default — never `allow`.
+- Each problem is reported as a clear, path-qualified issue in the permission review log (and the debug log when `debugLog` is on).
+
+Nothing about the config **format** changed — a config that was already valid keeps working unchanged.
+
+## What you need to do
+
+If your config was valid, nothing.
+
+If a scope stops taking effect after upgrading (surfaces start prompting with `ask`), open the permission review log and look for `Invalid config value at '<path>': …` or `Unrecognized config key '<key>'.` messages.
+Fix each reported problem, then reload.
+
+Common fixes:
+
+- **Wrong type** — e.g. `"toolInputPreviewMaxLength": "400"` (string) → `400` (number); `"debugLog": "true"` → `true`.
+- **Unknown key** — a typo (`"debugLo"` → `"debugLog"`) or a legacy top-level policy key (`defaultPolicy`, `tools`, `bash`, …) that belongs under `permission` (see `legacy-to-flat.md`).
+- **Invalid permission action** — an action must be `"allow"`, `"deny"`, or `"ask"` (or a `{ "action": "deny", "reason": "…" }` object).
+
+## Editor support
+
+Add the hosted schema to your config for autocomplete and inline validation, so these problems surface as you type:
+
+```json
+"$schema": "https://raw.githubusercontent.com/gotgenes/pi-packages/main/packages/pi-permission-system/schemas/permissions.schema.json"
+```

package/docs/opencode-compatibility.md

@@ -153,7 +153,7 @@ The result is broader coverage (paths detected in any command, not just a curate
 
 ```jsonc
 {
-  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-permission-system/main/schemas/permissions.schema.json",
+  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-packages/main/packages/pi-permission-system/schemas/permissions.schema.json",
   "permission": {
     "*": "allow",
     "bash": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "18.2.0",
+  "version": "19.0.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -73,10 +73,12 @@
   },
   "dependencies": {
     "tree-sitter-bash": "^0.25.1",
-    "web-tree-sitter": "^0.26.9"
+    "web-tree-sitter": "^0.26.9",
+    "zod": "^4.4.3"
   },
   "scripts": {
     "check": "tsc --noEmit",
+    "gen:schema": "node --experimental-strip-types scripts/generate-permissions-schema.ts && biome format --write schemas/permissions.schema.json",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint:md": "rumdl check *.md docs/**/*.md",

package/schemas/permissions.schema.json

@@ -1,11 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/gotgenes/pi-permission-system/main/schemas/permissions.schema.json",
-  "title": "PI Permission System Configuration",
-  "description": "Unified config file combining runtime knobs and flat permission policy for pi-permission-system.",
-  "markdownDescription": "Unified config file combining runtime knobs and flat permission policy for [pi-permission-system](https://github.com/gotgenes/pi-permission-system).\n\nPlace at `~/.pi/agent/extensions/pi-permission-system/config.json` (global) or `<project>/.pi/extensions/pi-permission-system/config.json` (project).",
+  "$id": "https://raw.githubusercontent.com/gotgenes/pi-packages/main/packages/pi-permission-system/schemas/permissions.schema.json",
   "type": "object",
-  "additionalProperties": false,
   "properties": {
     "$schema": {
       "description": "JSON Schema URI for editor autocomplete and validation.",
@@ -14,64 +10,64 @@
     "debugLog": {
       "description": "Write verbose permission-system diagnostics to the extension logs directory.",
       "markdownDescription": "Write verbose permission-system diagnostics to `logs/pi-permission-system-debug.jsonl` under the extension config directory.",
-      "type": "boolean",
-      "default": false
+      "default": false,
+      "type": "boolean"
     },
     "permissionReviewLog": {
       "description": "Write permission request and decision audit events to the extension logs directory.",
       "markdownDescription": "Write permission request and decision audit events to `logs/pi-permission-system-permission-review.jsonl` under the extension config directory.",
-      "type": "boolean",
-      "default": true
+      "default": true,
+      "type": "boolean"
     },
     "yoloMode": {
       "description": "Auto-approve ask-state permission checks, including subagent approval forwarding.",
       "markdownDescription": "Auto-approve `ask`-state permission checks, including subagent approval forwarding.\n\n⚠️ **Use with caution** — this disables all interactive confirmation prompts.",
-      "type": "boolean",
-      "default": false
+      "default": false,
+      "type": "boolean"
     },
     "toolInputPreviewMaxLength": {
       "description": "Maximum character length of the inline-JSON tool-input preview shown in permission prompts. Omit to use the default (200). Set to a large value to disable truncation.",
       "markdownDescription": "Maximum character length of the inline-JSON tool-input preview shown in permission prompts.\n\nOmit to use the default (200). Set to a large value (e.g. `10000`) to effectively disable truncation and see the full input.",
       "type": "integer",
-      "minimum": 1
+      "minimum": 1,
+      "maximum": 9007199254740991
     },
     "toolTextSummaryMaxLength": {
       "description": "Maximum character length of inline pattern/path summaries (e.g. grep patterns, find globs, ls paths) in permission prompts. Omit to use the default (80).",
       "markdownDescription": "Maximum character length of inline pattern/path summaries (e.g. grep patterns, find globs, ls paths) shown in permission prompts.\n\nOmit to use the default (80). Increase this when working with long regexes or deep paths that are being cut off.",
       "type": "integer",
-      "minimum": 1
+      "minimum": 1,
+      "maximum": 9007199254740991
     },
     "piInfrastructureReadPaths": {
       "description": "Additional directories to auto-allow for reads as Pi infrastructure, bypassing the external_directory gate. Supports ~ expansion and wildcard patterns (* and ?).",
       "markdownDescription": "Additional directories to auto-allow for reads as Pi infrastructure, bypassing the `external_directory` gate.\n\nThe extension auto-discovers the global node_modules root (walks up from the extension's install path; falls back to `npm root -g` from a dev checkout), Pi's own install directory (via the coding-agent `getPackageDir()` API), `agentDir`, `agentDir/git`, and project-local `.pi/npm/` and `.pi/git/`. Add entries here for edge cases where auto-discovery is insufficient (e.g. custom `npmCommand` pointing to pnpm).\n\nSupports `~`/`$HOME` expansion. Entries may be plain directory prefixes or wildcard patterns using `*` (matches any characters, including `/`) and `?` (matches exactly one character). `**` and `*` are equivalent — both cross directory boundaries.\n\nOn Windows, matching is case-insensitive and tolerant of either path separator.",
+      "default": [],
       "type": "array",
       "items": {
         "type": "string",
         "minLength": 1
-      },
-      "default": []
+      }
     },
     "permission": {
-      "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.",
       "type": "object",
       "propertyNames": {
-        "description": "A surface name or the universal fallback key '*'.",
         "type": "string",
-        "minLength": 1
+        "minLength": 1,
+        "description": "A surface name or the universal fallback key '*'."
       },
       "additionalProperties": {
-        "oneOf": [
+        "anyOf": [
           {
-            "$ref": "#/$defs/permissionState",
-            "description": "Catch-all shorthand: equivalent to { \"*\": action }."
+            "$ref": "#/$defs/permissionState"
           },
           {
-            "$ref": "#/$defs/permissionMap",
-            "description": "Pattern→action map for this surface."
+            "$ref": "#/$defs/permissionMap"
           }
         ]
       },
+      "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.",
       "examples": [
         {
           "*": "ask",
@@ -90,69 +86,85 @@
             "git status": "allow",
             "git diff": "allow"
           },
-          "mcp": { "*": "ask", "mcp_status": "allow", "exa:*": "allow" },
-          "skill": { "*": "ask", "librarian": "allow" },
-          "external_directory": { "*": "ask", "~/.cargo/registry/*": "allow" }
+          "mcp": {
+            "*": "ask",
+            "mcp_status": "allow",
+            "exa:*": "allow"
+          },
+          "skill": {
+            "*": "ask",
+            "librarian": "allow"
+          },
+          "external_directory": {
+            "*": "ask",
+            "~/.cargo/registry/*": "allow"
+          }
         }
       ]
     }
   },
+  "additionalProperties": false,
+  "title": "PI Permission System Configuration",
+  "description": "Unified config file combining runtime knobs and flat permission policy for pi-permission-system.",
+  "markdownDescription": "Unified config file combining runtime knobs and flat permission policy for [pi-permission-system](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system).\n\nPlace at `~/.pi/agent/extensions/pi-permission-system/config.json` (global) or `<project>/.pi/extensions/pi-permission-system/config.json` (project).",
   "$defs": {
     "permissionState": {
-      "description": "A permission decision: allow (permit silently), deny (block with error), or ask (prompt the user for confirmation).",
-      "oneOf": [
+      "anyOf": [
         {
+          "type": "string",
           "const": "allow",
           "description": "Permit the action silently with no user interaction."
         },
         {
+          "type": "string",
           "const": "deny",
           "description": "Block the action with an error message. The agent is told not to retry."
         },
         {
+          "type": "string",
           "const": "ask",
           "description": "Prompt the user for confirmation via the interactive UI before proceeding."
         }
-      ]
+      ],
+      "description": "A permission decision: allow (permit silently), deny (block with error), or ask (prompt the user for confirmation)."
     },
     "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.\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. Prefix with ~/ or $HOME/ for home-relative paths.",
         "type": "string",
-        "minLength": 1
+        "minLength": 1,
+        "description": "A non-empty pattern string. Use * for wildcard matching. Prefix with ~/ or $HOME/ for home-relative paths."
       },
       "additionalProperties": {
-        "oneOf": [
+        "anyOf": [
           {
-            "$ref": "#/$defs/permissionState",
-            "description": "A permission decision for this pattern."
+            "$ref": "#/$defs/permissionState"
           },
           {
-            "$ref": "#/$defs/denyWithReason",
-            "description": "Deny this pattern with an optional custom reason."
+            "$ref": "#/$defs/denyWithReason"
           }
         ]
-      }
+      },
+      "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.\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/*`)."
     },
     "denyWithReason": {
       "type": "object",
-      "description": "Deny with an optional custom reason shown to the agent when the action is blocked.",
       "properties": {
         "action": {
+          "type": "string",
           "const": "deny",
-          "description": "The permission decision \u2014 must be \"deny\"."
+          "description": "The permission decision — must be \"deny\"."
         },
         "reason": {
+          "description": "Optional reason shown to the agent when this action is denied.",
           "type": "string",
-          "maxLength": 500,
-          "description": "Optional reason shown to the agent when this action is denied."
+          "maxLength": 500
         }
       },
       "required": ["action"],
-      "additionalProperties": false
+      "additionalProperties": false,
+      "description": "Deny with an optional custom reason shown to the agent when the action is blocked."
     }
   }
 }

package/src/config-loader.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { normalize } from "node:path";
+import type { ZodError } from "zod";
 import {
   getGlobalConfigPath,
   getLegacyExtensionConfigPath,
@@ -7,32 +8,19 @@ import {
   getLegacyProjectPolicyPath,
   getProjectConfigPath,
 } from "./config-paths";
+import {
+  type UnifiedPermissionConfig,
+  unifiedConfigSchema,
+} from "./config-schema";
 import { mergeFlatPermissions } from "./permission-merge";
 import type { FlatPermissionConfig, PatternValue } from "./types";
-import {
-  isDenyWithReason,
-  isPermissionState,
-  normalizeOptionalPositiveInt,
-  normalizeOptionalStringArray,
-  toRecord,
-} from "./value-guards";
+import { isDenyWithReason, isPermissionState } from "./value-guards";
 
-/**
- * Unified config shape combining runtime knobs and flat permission policy.
- * All fields are optional so partial configs (project-only, global-only) work.
- */
-export interface UnifiedPermissionConfig {
-  // Runtime knobs
-  debugLog?: boolean;
-  permissionReviewLog?: boolean;
-  yoloMode?: boolean;
-  toolInputPreviewMaxLength?: number;
-  toolTextSummaryMaxLength?: number;
-  piInfrastructureReadPaths?: string[];
-
-  // Flat permission policy
-  permission?: FlatPermissionConfig;
-}
+// The unified config shape is derived from the zod schema (config-schema.ts,
+// the single source of truth) and re-exported so existing importers keep their
+// import path. All fields are optional so partial configs merge before
+// defaults are applied downstream.
+export type { UnifiedPermissionConfig };
 
 export interface UnifiedConfigLoadResult {
   config: UnifiedPermissionConfig;
@@ -118,20 +106,13 @@ function consumeString(input: string, start: number): ScanSegment {
   return { output, nextIndex: i };
 }
 
-function normalizeOptionalBoolean(value: unknown): boolean | undefined {
-  if (typeof value === "boolean") {
-    return value;
-  }
-  return undefined;
-}
-
 /**
  * Normalize a raw `permission` value from parsed JSON into a FlatPermissionConfig.
  * Accepts PermissionState strings and DenyWithReason objects inside pattern
  * maps. Drops non-object top-level values, invalid PermissionState strings, and
  * invalid action values inside object maps.
  */
-function normalizeFlatPermissionValue(
+export function normalizeFlatPermissionValue(
   value: unknown,
 ): FlatPermissionConfig | undefined {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -172,52 +153,39 @@ function normalizeFlatPermissionValue(
 }
 
 /**
- * Normalize raw parsed JSON into the unified config shape.
+ * Validate raw parsed JSON against the config schema (the single source of
+ * truth in `config-schema.ts`).
+ *
+ * On success the typed config is returned. On failure the whole scope config is
+ * rejected — fail-closed: an empty config contributes no rules, so missing
+ * surfaces fall through to the universal `ask` default rather than `allow` —
+ * and every schema violation is reported as a clear, actionable issue.
  */
-export function normalizeUnifiedConfig(raw: unknown): {
-  config: UnifiedPermissionConfig;
-  issues: string[];
-} {
-  const record = toRecord(raw);
-  const issues: string[] = [];
-  const config: UnifiedPermissionConfig = {};
-
-  // Runtime knobs
-  const debugLog = normalizeOptionalBoolean(record.debugLog);
-  if (debugLog !== undefined) config.debugLog = debugLog;
-
-  const permissionReviewLog = normalizeOptionalBoolean(
-    record.permissionReviewLog,
-  );
-  if (permissionReviewLog !== undefined)
-    config.permissionReviewLog = permissionReviewLog;
-
-  const yoloMode = normalizeOptionalBoolean(record.yoloMode);
-  if (yoloMode !== undefined) config.yoloMode = yoloMode;
-
-  const toolInputPreviewMaxLength = normalizeOptionalPositiveInt(
-    record.toolInputPreviewMaxLength,
-  );
-  if (toolInputPreviewMaxLength !== undefined)
-    config.toolInputPreviewMaxLength = toolInputPreviewMaxLength;
-
-  const toolTextSummaryMaxLength = normalizeOptionalPositiveInt(
-    record.toolTextSummaryMaxLength,
-  );
-  if (toolTextSummaryMaxLength !== undefined)
-    config.toolTextSummaryMaxLength = toolTextSummaryMaxLength;
-
-  const piInfrastructureReadPaths = normalizeOptionalStringArray(
-    record.piInfrastructureReadPaths,
-  );
-  if (piInfrastructureReadPaths !== undefined)
-    config.piInfrastructureReadPaths = piInfrastructureReadPaths;
-
-  // Flat permission policy
-  const permission = normalizeFlatPermissionValue(record.permission);
-  if (permission !== undefined) config.permission = permission;
+export function validateUnifiedConfig(
+  parsed: unknown,
+): UnifiedConfigLoadResult {
+  const result = unifiedConfigSchema.safeParse(parsed);
+  if (result.success) {
+    return { config: result.data, issues: [] };
+  }
+  return { config: {}, issues: formatConfigIssues(result.error) };
+}
 
-  return { config, issues };
+/** Render each schema violation as a clear, path-qualified message. */
+function formatConfigIssues(error: ZodError): string[] {
+  const messages: string[] = [];
+  for (const issue of error.issues) {
+    if (issue.code === "unrecognized_keys") {
+      for (const key of issue.keys) {
+        messages.push(`Unrecognized config key '${key}'.`);
+      }
+      continue;
+    }
+    const location =
+      issue.path.length > 0 ? issue.path.map(String).join(".") : "(root)";
+    messages.push(`Invalid config value at '${location}': ${issue.message}`);
+  }
+  return messages;
 }
 
 /**
@@ -320,7 +288,8 @@ export function loadAndMergeConfigs(
         `Move it to '${newGlobalPath}':\n` +
         `  mv '${legacyGlobalPolicyPath}' '${newGlobalPath}'`,
     );
-    allIssues.push(...legacy.issues);
+    // Legacy files are migrated away; the move-it guidance above is the
+    // actionable signal, so strict-validation issues for them are suppressed.
     merged = mergeUnifiedConfigs(merged, legacy.config);
   }
 
@@ -337,7 +306,7 @@ export function loadAndMergeConfigs(
         `Move runtime settings to '${newGlobalPath}':\n` +
         `  mv '${legacyExtConfigPath}' '${newGlobalPath}'`,
     );
-    allIssues.push(...legacy.issues);
+    // See above: legacy-file validation issues are suppressed.
     merged = mergeUnifiedConfigs(merged, legacy.config);
   }
 
@@ -355,7 +324,7 @@ export function loadAndMergeConfigs(
         `Move it to '${newProjectPath}':\n` +
         `  mv '${legacyProjectPolicyPath}' '${newProjectPath}'`,
     );
-    allIssues.push(...legacy.issues);
+    // See above: legacy-file validation issues are suppressed.
     merged = mergeUnifiedConfigs(merged, legacy.config);
   }
 
@@ -421,7 +390,7 @@ export function loadUnifiedConfig(path: string): UnifiedConfigLoadResult {
   try {
     const raw = readFileSync(path, "utf-8");
     const parsed = JSON.parse(stripJsonComments(raw)) as unknown;
-    return normalizeUnifiedConfig(parsed);
+    return validateUnifiedConfig(parsed);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     return {

package/src/config-schema.ts

@@ -0,0 +1,204 @@
+import { z } from "zod";
+
+/**
+ * Single source of truth for the permission-system config file shape.
+ *
+ * These composable zod schemas drive two consumers:
+ * 1. Runtime validation in the config-file loader (`config-loader.ts`).
+ * 2. The published JSON Schema (`schemas/permissions.schema.json`), derived by
+ *    `buildPermissionsJsonSchema()` and regenerated via `pnpm run gen:schema`.
+ *
+ * Edit the schemas here — never the generated JSON by hand. A parity test
+ * (`config-schema.test.ts`) fails if the committed JSON drifts from this source.
+ */
+
+/** Canonical hosted location of the generated JSON Schema (monorepo raw path). */
+export const PERMISSIONS_SCHEMA_URL =
+  "https://raw.githubusercontent.com/gotgenes/pi-packages/main/packages/pi-permission-system/schemas/permissions.schema.json";
+
+const permissionStateSchema = z
+  .union([
+    z.literal("allow").meta({
+      description: "Permit the action silently with no user interaction.",
+    }),
+    z.literal("deny").meta({
+      description:
+        "Block the action with an error message. The agent is told not to retry.",
+    }),
+    z.literal("ask").meta({
+      description:
+        "Prompt the user for confirmation via the interactive UI before proceeding.",
+    }),
+  ])
+  .meta({
+    id: "permissionState",
+    description:
+      "A permission decision: allow (permit silently), deny (block with error), or ask (prompt the user for confirmation).",
+  });
+
+const denyWithReasonSchema = z
+  .strictObject({
+    action: z.literal("deny").meta({
+      description: 'The permission decision — must be "deny".',
+    }),
+    reason: z.string().max(500).optional().meta({
+      description:
+        "Optional reason shown to the agent when this action is denied.",
+    }),
+  })
+  .meta({
+    id: "denyWithReason",
+    description:
+      "Deny with an optional custom reason shown to the agent when the action is blocked.",
+  });
+
+const patternValueSchema = z.union([
+  permissionStateSchema,
+  denyWithReasonSchema,
+]);
+
+const permissionMapSchema = z
+  .record(
+    z.string().min(1).meta({
+      description:
+        "A non-empty pattern string. Use * for wildcard matching. Prefix with ~/ or $HOME/ for home-relative paths.",
+    }),
+    patternValueSchema,
+  )
+  .meta({
+    id: "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.\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/*`).",
+  });
+
+const permissionSchema = z
+  .record(
+    z.string().min(1).meta({
+      description: "A surface name or the universal fallback key '*'.",
+    }),
+    z.union([permissionStateSchema, permissionMapSchema]),
+  )
+  .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.',
+    examples: [
+      {
+        "*": "ask",
+        path: {
+          "*": "allow",
+          "*.env": "deny",
+          "*.env.*": "deny",
+          "*.env.example": "allow",
+        },
+        read: "allow",
+        write: "deny",
+        edit: "deny",
+        bash: {
+          "*": "ask",
+          "git *": "ask",
+          "git status": "allow",
+          "git diff": "allow",
+        },
+        mcp: { "*": "ask", mcp_status: "allow", "exa:*": "allow" },
+        skill: { "*": "ask", librarian: "allow" },
+        external_directory: { "*": "ask", "~/.cargo/registry/*": "allow" },
+      },
+    ],
+  });
+
+/**
+ * The on-disk config file shape.
+ *
+ * Every field is optional so partial global/project configs merge before the
+ * runtime defaults are applied downstream (`normalizePermissionSystemConfig`).
+ * No `.default()` lives here — injecting defaults at parse time would break the
+ * global-vs-project override semantics. `strictObject` makes unknown top-level
+ * keys an error, so editors flag typos and the runtime loader rejects them.
+ */
+export const unifiedConfigSchema = z
+  .strictObject({
+    $schema: z.string().optional().meta({
+      description: "JSON Schema URI for editor autocomplete and validation.",
+    }),
+    debugLog: z.boolean().optional().meta({
+      description:
+        "Write verbose permission-system diagnostics to the extension logs directory.",
+      markdownDescription:
+        "Write verbose permission-system diagnostics to `logs/pi-permission-system-debug.jsonl` under the extension config directory.",
+      default: false,
+    }),
+    permissionReviewLog: z.boolean().optional().meta({
+      description:
+        "Write permission request and decision audit events to the extension logs directory.",
+      markdownDescription:
+        "Write permission request and decision audit events to `logs/pi-permission-system-permission-review.jsonl` under the extension config directory.",
+      default: true,
+    }),
+    yoloMode: z.boolean().optional().meta({
+      description:
+        "Auto-approve ask-state permission checks, including subagent approval forwarding.",
+      markdownDescription:
+        "Auto-approve `ask`-state permission checks, including subagent approval forwarding.\n\n⚠️ **Use with caution** — this disables all interactive confirmation prompts.",
+      default: false,
+    }),
+    toolInputPreviewMaxLength: z.number().int().min(1).optional().meta({
+      description:
+        "Maximum character length of the inline-JSON tool-input preview shown in permission prompts. Omit to use the default (200). Set to a large value to disable truncation.",
+      markdownDescription:
+        "Maximum character length of the inline-JSON tool-input preview shown in permission prompts.\n\nOmit to use the default (200). Set to a large value (e.g. `10000`) to effectively disable truncation and see the full input.",
+    }),
+    toolTextSummaryMaxLength: z.number().int().min(1).optional().meta({
+      description:
+        "Maximum character length of inline pattern/path summaries (e.g. grep patterns, find globs, ls paths) in permission prompts. Omit to use the default (80).",
+      markdownDescription:
+        "Maximum character length of inline pattern/path summaries (e.g. grep patterns, find globs, ls paths) shown in permission prompts.\n\nOmit to use the default (80). Increase this when working with long regexes or deep paths that are being cut off.",
+    }),
+    piInfrastructureReadPaths: z.array(z.string().min(1)).optional().meta({
+      description:
+        "Additional directories to auto-allow for reads as Pi infrastructure, bypassing the external_directory gate. Supports ~ expansion and wildcard patterns (* and ?).",
+      markdownDescription:
+        "Additional directories to auto-allow for reads as Pi infrastructure, bypassing the `external_directory` gate.\n\nThe extension auto-discovers the global node_modules root (walks up from the extension's install path; falls back to `npm root -g` from a dev checkout), Pi's own install directory (via the coding-agent `getPackageDir()` API), `agentDir`, `agentDir/git`, and project-local `.pi/npm/` and `.pi/git/`. Add entries here for edge cases where auto-discovery is insufficient (e.g. custom `npmCommand` pointing to pnpm).\n\nSupports `~`/`$HOME` expansion. Entries may be plain directory prefixes or wildcard patterns using `*` (matches any characters, including `/`) and `?` (matches exactly one character). `**` and `*` are equivalent — both cross directory boundaries.\n\nOn Windows, matching is case-insensitive and tolerant of either path separator.",
+      default: [],
+    }),
+    permission: permissionSchema.optional(),
+  })
+  .meta({
+    title: "PI Permission System Configuration",
+    description:
+      "Unified config file combining runtime knobs and flat permission policy for pi-permission-system.",
+    markdownDescription:
+      "Unified config file combining runtime knobs and flat permission policy for [pi-permission-system](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system).\n\nPlace at `~/.pi/agent/extensions/pi-permission-system/config.json` (global) or `<project>/.pi/extensions/pi-permission-system/config.json` (project).",
+  });
+
+/** A permission decision. */
+export type PermissionState = z.infer<typeof permissionStateSchema>;
+
+/** A deny action with an optional custom reason. */
+export type DenyWithReason = z.infer<typeof denyWithReasonSchema>;
+
+/** A pattern value: a PermissionState string OR a DenyWithReason object. */
+export type PatternValue = z.infer<typeof patternValueSchema>;
+
+/** The on-disk permission shape inside the `"permission"` key. */
+export type FlatPermissionConfig = z.infer<typeof permissionSchema>;
+
+/** The raw config file shape after validation (all fields optional). */
+export type UnifiedPermissionConfig = z.infer<typeof unifiedConfigSchema>;
+
+/**
+ * Derive the published JSON Schema (Draft 2020-12) from the zod source.
+ *
+ * The three id-tagged sub-schemas (`permissionState`, `permissionMap`,
+ * `denyWithReason`) become `$defs` referenced by `$ref`; everything else
+ * inlines. The root `$id` is set to the canonical monorepo URL.
+ */
+export function buildPermissionsJsonSchema(): Record<string, unknown> {
+  const { $schema, ...rest } = z.toJSONSchema(unifiedConfigSchema, {
+    target: "draft-2020-12",
+  });
+  return { $schema, $id: PERMISSIONS_SCHEMA_URL, ...rest };
+}

package/src/policy-loader.ts

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import {
   loadUnifiedConfig,
-  normalizeUnifiedConfig,
+  normalizeFlatPermissionValue,
   stripJsonComments,
 } from "./config-loader";
 import { getGlobalConfigPath } from "./config-paths";
@@ -263,10 +263,14 @@ export class FilePolicyLoader implements PolicyLoader {
       if (!frontmatter) {
         value = {};
       } else {
+        // Agent frontmatter carries non-config keys (name, description, model,
+        // …) alongside `permission`, so it is not validated by the strict
+        // config-file schema; only the `permission` block is extracted, and its
+        // malformed entries are dropped tolerantly as before.
         const parsed = parseSimpleYamlMap(frontmatter);
-        const { config, issues } = normalizeUnifiedConfig(parsed);
-        this.accumulateConfigIssues(issues);
-        value = { permission: config.permission };
+        value = {
+          permission: normalizeFlatPermissionValue(parsed.permission),
+        };
       }
     } catch {
       value = {};

package/src/types.ts

@@ -1,20 +1,21 @@
-export type PermissionState = "allow" | "deny" | "ask";
-
+import type {
+  DenyWithReason,
+  FlatPermissionConfig,
+  PatternValue,
+  PermissionState,
+} from "./config-schema";
 import type { RuleOrigin } from "./rule";
 
-export type { RuleOrigin };
-
-/**
- * A deny action with an optional reason annotation, used when a pattern maps
- * to an object instead of a plain PermissionState string.
- */
-export interface DenyWithReason {
-  action: "deny";
-  reason?: string;
-}
-
-/** A pattern value: a PermissionState string OR a DenyWithReason object. */
-export type PatternValue = PermissionState | DenyWithReason;
+// The config-file shape types are derived from the zod schema
+// (config-schema.ts) — the single source of truth — and re-exported here so
+// existing importers keep their import path.
+export type {
+  DenyWithReason,
+  FlatPermissionConfig,
+  PatternValue,
+  PermissionState,
+  RuleOrigin,
+};
 
 /**
  * Predicate deciding whether a bare bash token should be promoted into the
@@ -27,17 +28,6 @@ export type PatternValue = PermissionState | DenyWithReason;
  */
 export type PathRuleTokenMatcher = (token: string) => boolean;
 
-/**
- * The on-disk permission shape inside the `"permission"` key.
- * A surface value is a PermissionState string (shorthand for `{ "*": action }`)
- * or a pattern→value map. Pattern values may be a PermissionState string or a
- * DenyWithReason object. A top-level value is never a bare DenyWithReason.
- */
-export type FlatPermissionConfig = Record<
-  string,
-  PermissionState | Record<string, PatternValue>
->;
-
 /**
  * Per-scope permission config shape after loading and validation.
  * Holds only the flat permission map — all policy is expressed there.

package/src/value-guards.ts

@@ -17,23 +17,6 @@ export function getNonEmptyString(value: unknown): string | null {
   return trimmed.length > 0 ? trimmed : null;
 }
 
-/** Returns `raw` if it is an array of strings; otherwise `undefined`. */
-export function normalizeOptionalStringArray(
-  raw: unknown,
-): string[] | undefined {
-  return Array.isArray(raw) &&
-    raw.every((p): p is string => typeof p === "string")
-    ? raw
-    : undefined;
-}
-
-/** Returns `raw` if it is a positive integer; otherwise `undefined`. */
-export function normalizeOptionalPositiveInt(raw: unknown): number | undefined {
-  return typeof raw === "number" && Number.isInteger(raw) && raw > 0
-    ? raw
-    : undefined;
-}
-
 export function isPermissionState(value: unknown): value is PermissionState {
   return value === "allow" || value === "deny" || value === "ask";
 }