@gotgenes/pi-permission-model-judge 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 1.0.0 (2026-07-20)
+
+
+### Features
+
+* **pi-permission-model-judge:** deny-first external_directory reviewer ([27d8c31](https://github.com/gotgenes/pi-packages/commit/27d8c317f4f11a233482fed004e35ad35654fe79))
+* **pi-permission-model-judge:** model confirmation of typo paths ([2439faa](https://github.com/gotgenes/pi-packages/commit/2439faacd3950b10bb01940aa0c82dd8999138bb))
+* **pi-permission-model-judge:** register the model-judge link on permissions:ready ([4ce1ead](https://github.com/gotgenes/pi-packages/commit/4ce1ead9fe7c47ce066cf7a7e48d86729cd53eee))
+* **pi-permission-model-judge:** ship generated config JSON schema and example ([0158258](https://github.com/gotgenes/pi-packages/commit/0158258e39b60eda0b99ed8dfa3f255a5368eaf4))
+* **pi-permission-model-judge:** typo-pattern compilation and matching ([a4e6639](https://github.com/gotgenes/pi-packages/commit/a4e6639f2fee9db323bfc0ddd6183cc0b5685e2b))
+* **pi-permission-model-judge:** zod config schema and layered loader ([d9cbc7a](https://github.com/gotgenes/pi-packages/commit/d9cbc7a952db59a4fa89b375648c98a0536803b8))
+
+
+### Documentation
+
+* **pi-permission-model-judge:** package README and configuration reference ([25e4ff9](https://github.com/gotgenes/pi-packages/commit/25e4ff949ffc85c5246da44528efbe2acbd5744c))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christopher D. Lasher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @gotgenes/pi-permission-model-judge
+
+A [Pi](https://github.com/earendil-works/pi) extension that reviews out-of-directory permission asks with a light model and auto-denies mistyped paths with a teaching reason.
+
+It is the first consumer of [`@gotgenes/pi-permission-system`](../pi-permission-system/)'s `registerAuthorizer` seam: it registers a `"model-judge"` chain link that reviews `external_directory` asks, and — when a path matches one of your configured typo patterns — asks a model whether the path is a mistake.
+A confirmed typo is denied with a short explanation (the wrong segment and the correct location) so the invoking agent self-corrects; everything else defers to the normal prompt.
+
+## Why
+
+Agents frequently invoke a tool against a malformed path — for example `…/pi-permission-system/packages/pi-permission-system/src/x.ts`, where the doubled segment should be `pi-packages`.
+Each one lands as an `external_directory` ask you hand-deny, one by one.
+This extension turns that repetitive hand-denial into an automatic, explained denial that teaches the agent the correct location.
+
+## How it works
+
+The reviewer runs a short, cheap decision on each ask and defers at the first miss:
+
+1. The ask is on the `external_directory` surface (otherwise defer).
+2. A candidate path is present (otherwise defer).
+3. The path matches one of your `typoPatterns` (otherwise defer — no model call).
+4. The model confirms the typo and returns a teaching reason (`deny`), or is unsure (`defer`).
+
+It is fail-safe by construction: a missing model, invalid config, model timeout, unparseable reply, or an unsure verdict all resolve to `defer`.
+Deferring means the ask falls through to the normal permission prompt — this extension only ever *removes* a hand-denial, never grants access (it emits no `allow`).
+
+## Install
+
+```bash
+pnpm add -D @gotgenes/pi-permission-model-judge
+```
+
+This extension does nothing on its own — it requires `@gotgenes/pi-permission-system` (peer dependency) and `@earendil-works/pi-ai` (provided by Pi).
+
+## Enable
+
+Two independent config files are involved — the safety policy lives in pi-permission-system, the model mechanism lives here.
+
+1. In your **pi-permission-system** config, name the link in `authorizerChain` (opt-in — the link decides nothing until you list it):
+
+   ```jsonc
+   // ~/.pi/agent/extensions/pi-permission-system/config.json
+   { "authorizerChain": ["model-judge"] }
+   ```
+
+2. In **this** extension's config, declare the model mechanism and your typo patterns:
+
+   ```jsonc
+   // ~/.pi/agent/extensions/pi-permission-model-judge/config.json
+   {
+     "provider": "anthropic",
+     "model": "claude-haiku-4-5",
+     "instructions": "Deny a path that repeats a directory segment…",
+     "typoPatterns": ["pi-permission-system/packages/pi-permission-system"]
+   }
+   ```
+
+See [`config/config.example.json`](config/config.example.json) for a complete example and [docs/configuration.md](docs/configuration.md) for the full field reference.
+
+## Configuration
+
+Config is layered — a project file (`<cwd>/.pi/extensions/pi-permission-model-judge/config.json`) overrides the global one — and validated against a [JSON Schema](schemas/model-judge.schema.json).
+
+| Field          | Type       | Default  | Description                                                                                |
+| -------------- | ---------- | -------- | ------------------------------------------------------------------------------------------ |
+| `provider`     | `string`   | required | Model provider (e.g. `anthropic`), resolved against Pi's model registry.                   |
+| `model`        | `string`   | required | Model id (e.g. `claude-haiku-4-5`).                                                        |
+| `instructions` | `string`   | required | System prompt describing what a typo path is and the teaching reason to return.            |
+| `typoPatterns` | `string[]` | `[]`     | Regular expressions; only a path matching one reaches the model. Empty means never review. |
+| `timeoutMs`    | `integer`  | `5000`   | Per-review model-call budget in milliseconds; a timeout defers.                            |
+
+An empty or absent `typoPatterns` (or a missing config) makes the reviewer defer everything — a safe no-op.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/config/config.example.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://raw.githubusercontent.com/gotgenes/pi-packages/main/packages/pi-permission-model-judge/schemas/model-judge.schema.json",
+  "provider": "anthropic",
+  "model": "claude-haiku-4-5",
+  "instructions": "You review a filesystem path a tool is about to access outside the working directory. A typo path repeats a directory segment that should appear once — for example a path containing `pi-permission-system/packages/pi-permission-system`, where the first segment should be `pi-packages`. Deny only a clear typo, and in the reason state the wrong segment and the correct location so the caller can self-correct. When unsure, defer.",
+  "typoPatterns": [
+    "pi-permission-system/packages/pi-permission-system",
+    "pi-packages/packages/[^/]+/packages/"
+  ],
+  "timeoutMs": 5000
+}

package/docs/configuration.md

@@ -0,0 +1,76 @@
+# Configuration
+
+`@gotgenes/pi-permission-model-judge` reads one config file per scope, following the standard `@gotgenes/pi-*` convention.
+
+- Global: `~/.pi/agent/extensions/pi-permission-model-judge/config.json` (respects `PI_CODING_AGENT_DIR`).
+- Project: `<cwd>/.pi/extensions/pi-permission-model-judge/config.json`.
+
+The project file overrides the global one field-by-field; array fields (`typoPatterns`) replace wholesale rather than merging.
+Point your editor at the bundled [JSON Schema](../schemas/model-judge.schema.json) via `$schema` for completion and validation.
+
+## Two config files, one link name
+
+This extension owns only the *model mechanism*.
+The *chain policy* — whether the link runs at all, and its order — lives in `@gotgenes/pi-permission-system`.
+The two files are joined only by the link name `model-judge`:
+
+```jsonc
+// pi-permission-system config.json — the safety policy
+{ "authorizerChain": ["model-judge"] }
+```
+
+```jsonc
+// pi-permission-model-judge config.json — the model mechanism
+{
+  "provider": "anthropic",
+  "model": "claude-haiku-4-5",
+  "instructions": "…",
+  "typoPatterns": ["…"]
+}
+```
+
+The link decides nothing until you name it in `authorizerChain` (opt-in activation), and pi-permission-system caps any link's authority, so this extension can only ever deny or defer an `external_directory` ask — never widen access.
+
+## Fields
+
+| Field          | Type       | Default  | Description                                                                                      |
+| -------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------ |
+| `provider`     | `string`   | required | Model provider, resolved against Pi's model registry (must have credentials configured in Pi).   |
+| `model`        | `string`   | required | Model id within that provider.                                                                   |
+| `instructions` | `string`   | required | The model's system prompt: describe what a typo path is and the correct-location reason to give. |
+| `typoPatterns` | `string[]` | `[]`     | Regular expressions matched against the candidate path; only a match reaches the model.          |
+| `timeoutMs`    | `integer`  | `5000`   | Per-review model-call budget in milliseconds. A timeout defers.                                  |
+
+### `provider` and `model`
+
+The reviewer resolves `provider` / `model` against the session's model registry at review time.
+If the model does not resolve (wrong id, no credentials), the reviewer logs a warning and defers — it never blocks an ask because the judge is misconfigured.
+
+### `instructions`
+
+This is the model's system prompt.
+Describe the typo shape you care about and instruct the model to reply with the wrong segment and the correct location, so the invoking agent can self-correct.
+The reviewer expects the model to answer with strict JSON — `{"verdict":"deny","reason":"…"}` to reject, `{"verdict":"defer"}` otherwise — and any other reply defers.
+
+### `typoPatterns`
+
+Each string is compiled with `new RegExp(pattern)` (no flags) and tested against the candidate path.
+Only a path that matches at least one pattern is sent to the model — this is the cost gate that keeps the reviewer from calling the model on every ask.
+An invalid regular expression is skipped with a warning.
+An empty list (the default) matches nothing, so the reviewer defers everything.
+
+### `timeoutMs`
+
+The model call is aborted after this many milliseconds, and an aborted call defers.
+Keep it short — the reviewer sits in front of an interactive prompt.
+
+## Fail-safe behavior
+
+Every uncertain outcome defers, which sends the ask to the normal permission prompt:
+
+- no config, or an invalid config;
+- a surface other than `external_directory`;
+- a path matching no `typoPatterns`;
+- an unresolved model, a timeout, an unparseable reply, or an unsure verdict.
+
+Deferring never grants access — this extension emits no `allow` verdict.

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@gotgenes/pi-permission-model-judge",
+  "version": "1.0.0",
+  "description": "Deny-first typo-path model judge — a pi-permission-system Authorizer chain link",
+  "type": "module",
+  "imports": {
+    "#src/*": "./src/*",
+    "#test/*": "./test/*"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "permissions",
+    "authorizer",
+    "model-judge",
+    "policy",
+    "access-control"
+  ],
+  "author": {
+    "name": "Chris Lasher"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gotgenes/pi-packages.git",
+    "directory": "packages/pi-permission-model-judge"
+  },
+  "bugs": {
+    "url": "https://github.com/gotgenes/pi-packages/issues"
+  },
+  "homepage": "https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-model-judge#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "src",
+    "schemas",
+    "config/config.example.json",
+    "docs/*.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.79.0",
+    "@earendil-works/pi-coding-agent": ">=0.79.0",
+    "@gotgenes/pi-permission-system": ">=20.9.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.16",
+    "@earendil-works/pi-ai": "0.79.1",
+    "@earendil-works/pi-coding-agent": "0.79.1",
+    "@gotgenes/pi-permission-system": "20.9.0",
+    "@types/node": "^22.15.3",
+    "rumdl": "^0.2.10",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "gen:schema": "node --experimental-strip-types scripts/generate-schema.ts && biome format --write schemas/model-judge.schema.json",
+    "lint:md": "rumdl check *.md docs/**/*.md",
+    "lint": "biome check . && eslint . && pnpm run lint:md"
+  }
+}

package/schemas/model-judge.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/gotgenes/pi-packages/main/packages/pi-permission-model-judge/schemas/model-judge.schema.json",
+  "type": "object",
+  "properties": {
+    "provider": {
+      "type": "string",
+      "minLength": 1
+    },
+    "model": {
+      "type": "string",
+      "minLength": 1
+    },
+    "instructions": {
+      "type": "string",
+      "minLength": 1
+    },
+    "typoPatterns": {
+      "default": [],
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "timeoutMs": {
+      "default": 5000,
+      "type": "integer",
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991
+    }
+  },
+  "required": ["provider", "model", "instructions"]
+}

package/src/config-loader.ts

@@ -0,0 +1,136 @@
+/**
+ * Layered config loader: global then project `config.json`, project overriding
+ * global, validated once against the zod source of truth.
+ *
+ * Fail-safe by construction: a malformed file is skipped with a recorded issue
+ * (never fatal), and an invalid merged config yields `{ config: undefined }` so
+ * the extension registers no link — a config error degrades to no auto-deny,
+ * never to a wrong deny.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import {
+  MODEL_JUDGE_EXTENSION_ID,
+  type ModelJudgeConfig,
+  modelJudgeConfigSchema,
+} from "./config-schema";
+
+const CONFIG_FILE_NAME = "config.json";
+
+/** A validation or read problem, tied to the file that produced it. */
+export interface ConfigIssue {
+  path: string;
+  message: string;
+  sourcePath?: string;
+}
+
+/** Outcome of a config load: a validated config (or `undefined`) plus issues. */
+export interface LoadConfigResult {
+  config: ModelJudgeConfig | undefined;
+  issues: ConfigIssue[];
+}
+
+function defaultAgentDir(): string {
+  return join(homedir(), ".pi", "agent");
+}
+
+/** Global scope: `<agentDir>/extensions/<id>/config.json`. */
+export function getGlobalConfigPath(agentDir = defaultAgentDir()): string {
+  return join(
+    agentDir,
+    "extensions",
+    MODEL_JUDGE_EXTENSION_ID,
+    CONFIG_FILE_NAME,
+  );
+}
+
+/** Project scope: `<cwd>/.pi/extensions/<id>/config.json`. */
+export function getProjectConfigPath(cwd: string): string {
+  return join(
+    cwd,
+    ".pi",
+    "extensions",
+    MODEL_JUDGE_EXTENSION_ID,
+    CONFIG_FILE_NAME,
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Read and JSON-parse a layer. Returns `undefined` when the file is absent;
+ * records an issue and returns `undefined` when it is present but malformed.
+ */
+function readLayer(
+  path: string,
+  issues: ConfigIssue[],
+): Record<string, unknown> | undefined {
+  if (!existsSync(path)) {
+    return undefined;
+  }
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    if (!isRecord(parsed)) {
+      issues.push({
+        path: "$",
+        message: "Expected a JSON object.",
+        sourcePath: path,
+      });
+      return undefined;
+    }
+    return parsed;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    issues.push({
+      path: "$",
+      message: `Failed to read config: ${message}`,
+      sourcePath: path,
+    });
+    return undefined;
+  }
+}
+
+/**
+ * Load the merged, validated model-judge config from the global and project
+ * scopes.
+ *
+ * When neither file exists, returns `{ config: undefined, issues: [] }` — the
+ * normal not-configured state, reported without noise. When a present config is
+ * invalid, returns `{ config: undefined }` with the validation issues.
+ */
+export function loadModelJudgeConfig(options?: {
+  cwd?: string;
+  agentDir?: string;
+}): LoadConfigResult {
+  const cwd = options?.cwd ?? process.cwd();
+  const agentDir = options?.agentDir ?? defaultAgentDir();
+  const issues: ConfigIssue[] = [];
+
+  const global = readLayer(getGlobalConfigPath(agentDir), issues);
+  const project = readLayer(getProjectConfigPath(cwd), issues);
+
+  if (global === undefined && project === undefined) {
+    return { config: undefined, issues };
+  }
+
+  // Shallow merge: project scalars and arrays replace global wholesale.
+  const merged = { ...(global ?? {}), ...(project ?? {}) };
+
+  const parsed = modelJudgeConfigSchema.safeParse(merged);
+  if (!parsed.success) {
+    for (const issue of parsed.error.issues) {
+      issues.push({
+        path: issue.path.join(".") || "$",
+        message: issue.message,
+      });
+    }
+    return { config: undefined, issues };
+  }
+
+  return { config: parsed.data, issues };
+}

package/src/config-schema.ts

@@ -0,0 +1,52 @@
+/**
+ * The zod source of truth for the model-judge extension config.
+ *
+ * The config carries the *model mechanism* half of ADR 0007's config split
+ * (provider / model / instructions / patterns / timeout); the *chain policy*
+ * half (`authorizerChain`, the delegation envelope) lives in
+ * `@gotgenes/pi-permission-system`. This package reads only what it uses.
+ */
+
+import { z } from "zod";
+
+/** Extension id — the `extensions/<id>/config.json` path segment. */
+export const MODEL_JUDGE_EXTENSION_ID = "pi-permission-model-judge";
+
+/** Canonical URL of the published config JSON Schema (the root `$id`). */
+export const MODEL_JUDGE_SCHEMA_URL =
+  "https://raw.githubusercontent.com/gotgenes/pi-packages/main/packages/pi-permission-model-judge/schemas/model-judge.schema.json";
+
+/** Default per-review model-call budget, in milliseconds. */
+export const DEFAULT_TIMEOUT_MS = 5000;
+
+/**
+ * Operator-owned config for the deny-first typo-path reviewer.
+ *
+ * An empty or absent `typoPatterns` makes the reviewer defer everything —
+ * installing the package and naming it in `authorizerChain` without configuring
+ * patterns is a safe no-op (nothing is auto-denied).
+ */
+export const modelJudgeConfigSchema = z.object({
+  provider: z.string().min(1),
+  model: z.string().min(1),
+  instructions: z.string().min(1),
+  typoPatterns: z.array(z.string().min(1)).default([]),
+  timeoutMs: z.number().int().positive().default(DEFAULT_TIMEOUT_MS),
+});
+
+export type ModelJudgeConfig = z.infer<typeof modelJudgeConfigSchema>;
+
+/**
+ * Derive the published JSON Schema (Draft 2020-12) from the zod source, so an
+ * editor can validate `config.json` against `$schema`. Regenerate the committed
+ * file via `pnpm run gen:schema`; a parity test fails on drift.
+ */
+export function buildModelJudgeJsonSchema(): Record<string, unknown> {
+  // `io: "input"` treats defaulted fields (`typoPatterns`, `timeoutMs`) as
+  // optional — the config file is the input, and zod fills omitted defaults.
+  const { $schema, ...rest } = z.toJSONSchema(modelJudgeConfigSchema, {
+    target: "draft-2020-12",
+    io: "input",
+  });
+  return { $schema, $id: MODEL_JUDGE_SCHEMA_URL, ...rest };
+}

package/src/extension.ts

@@ -0,0 +1,99 @@
+/**
+ * Extension wiring: load the config at `session_start`, register the
+ * `"model-judge"` link once the permission service is ready, and dispose on
+ * shutdown.
+ *
+ * Registration is attempted from both `session_start` and `permissions:ready`
+ * behind an idempotency guard, because the two orderings are both possible: the
+ * ready event fires inside pi-permission-system's own `session_start`, which may
+ * run before or after this extension's. Whichever completes the pair
+ * (config loaded here + service published there) triggers the single
+ * registration; the guard prevents a duplicate (which `registerAuthorizer`
+ * would reject).
+ */
+
+import { complete as realComplete } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  getPermissionsService,
+  PERMISSIONS_READY_CHANNEL,
+} from "@gotgenes/pi-permission-system";
+
+import { type LoadConfigResult, loadModelJudgeConfig } from "./config-loader";
+import {
+  MODEL_JUDGE_EXTENSION_ID,
+  type ModelJudgeConfig,
+} from "./config-schema";
+import type { CompleteFn, ModelRegistryLike } from "./model-review";
+import { createTypoReviewer } from "./typo-reviewer";
+
+/** The operator-facing chain-link name referenced from `authorizerChain`. */
+const LINK_NAME = "model-judge";
+
+/** Injectable seams; production defaults read the filesystem and call the model. */
+export interface ModelJudgeDependencies {
+  loadConfig?: (cwd: string) => LoadConfigResult;
+  complete?: CompleteFn;
+}
+
+function warn(message: string): void {
+  console.warn(`[${MODEL_JUDGE_EXTENSION_ID}] ${message}`);
+}
+
+export function createModelJudgeExtension(
+  pi: ExtensionAPI,
+  dependencies: ModelJudgeDependencies = {},
+): void {
+  const loadConfig =
+    dependencies.loadConfig ?? ((cwd: string) => loadModelJudgeConfig({ cwd }));
+  const complete: CompleteFn =
+    dependencies.complete ??
+    ((model, context, options) => realComplete(model, context, options));
+
+  let sessionStarted = false;
+  let config: ModelJudgeConfig | undefined;
+  let registry: ModelRegistryLike | undefined;
+  let dispose: (() => void) | undefined;
+
+  function tryRegister(): void {
+    if (dispose || !sessionStarted || !config) {
+      return;
+    }
+    const service = getPermissionsService();
+    if (!service) {
+      return;
+    }
+    const authorize = createTypoReviewer({
+      getConfig: () => config,
+      getRegistry: () => registry,
+      complete,
+      warn,
+    });
+    dispose = service.registerAuthorizer(LINK_NAME, authorize);
+  }
+
+  pi.on("session_start", (_event, ctx) => {
+    const result = loadConfig(ctx.cwd);
+    config = result.config;
+    registry = ctx.modelRegistry;
+    sessionStarted = true;
+    for (const issue of result.issues) {
+      warn(
+        `config issue at ${issue.sourcePath ?? "(merged)"} — ${issue.path}: ${issue.message}`,
+      );
+    }
+    tryRegister();
+  });
+
+  pi.events.on(PERMISSIONS_READY_CHANNEL, () => {
+    tryRegister();
+  });
+
+  pi.on("session_shutdown", () => {
+    dispose?.();
+    dispose = undefined;
+    sessionStarted = false;
+    config = undefined;
+    registry = undefined;
+  });
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { createModelJudgeExtension } from "./extension";
+
+/**
+ * Entry point: register the deny-first typo-path model judge as a
+ * pi-permission-system Authorizer chain link.
+ */
+export default function modelJudgeExtension(pi: ExtensionAPI): void {
+  createModelJudgeExtension(pi);
+}

package/src/model-review.ts

@@ -0,0 +1,123 @@
+/**
+ * The model call: ask a light model whether a candidate path is a typo, bounded
+ * by `timeoutMs`, and map its reply to a `deny | defer` verdict.
+ *
+ * Fail-safe throughout — an unparseable reply, an unrecognized verdict, a
+ * thrown or timed-out `complete`, all resolve to `defer` (more prompting, never
+ * less). This slice never emits `allow`.
+ */
+
+import type {
+  AssistantMessage,
+  Context,
+  Model,
+  TextContent,
+} from "@earendil-works/pi-ai";
+import type { AuthorizerVerdict } from "@gotgenes/pi-permission-system";
+
+import type { ModelJudgeConfig } from "./config-schema";
+
+/** The reason used for a deny when the model omits its own. */
+export const GENERIC_TEACHING_REASON =
+  "This looks like a mistyped path. Verify the correct location before retrying.";
+
+/**
+ * The injected model-completion seam — structurally the `complete` export of
+ * `@earendil-works/pi-ai`. Injected so tests substitute a fake.
+ */
+export type CompleteFn = (
+  model: Model<any>,
+  context: Context,
+  options?: { signal?: AbortSignal },
+) => Promise<AssistantMessage>;
+
+/** The narrow model-registry projection the reviewer needs (ISP). */
+export interface ModelRegistryLike {
+  find(provider: string, modelId: string): Model<any> | undefined;
+}
+
+/** Inputs for a single path review. */
+export interface ReviewPathInputs {
+  path: string;
+  config: ModelJudgeConfig;
+  model: Model<any>;
+  complete: CompleteFn;
+}
+
+/**
+ * Review one candidate path with the model and return its verdict.
+ *
+ * The call is aborted after `config.timeoutMs`; an abort, a rejection, or any
+ * non-`deny` reply yields `defer`.
+ */
+export async function reviewPath(
+  inputs: ReviewPathInputs,
+): Promise<AuthorizerVerdict> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => {
+    controller.abort();
+  }, inputs.config.timeoutMs);
+  try {
+    const context: Context = {
+      systemPrompt: inputs.config.instructions,
+      messages: [
+        {
+          role: "user",
+          content: renderReviewPrompt(inputs.path),
+          timestamp: Date.now(),
+        },
+      ],
+    };
+    const reply = await inputs.complete(inputs.model, context, {
+      signal: controller.signal,
+    });
+    return parseVerdict(reply);
+  } catch {
+    return { kind: "defer" };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** The user-turn prompt: hand the model the path and the required reply shape. */
+function renderReviewPrompt(path: string): string {
+  return [
+    "A tool is about to access this path outside the working directory:",
+    "",
+    path,
+    "",
+    'Reply with strict JSON. To reject a mistyped path: {"verdict":"deny","reason":"<why it is wrong and the correct location>"}.',
+    'Otherwise: {"verdict":"defer"}.',
+  ].join("\n");
+}
+
+/** Map the assistant reply to a verdict; anything but a clean `deny` defers. */
+function parseVerdict(reply: AssistantMessage): AuthorizerVerdict {
+  const text = extractText(reply).trim();
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { kind: "defer" };
+  }
+  if (!isRecord(parsed) || parsed.verdict !== "deny") {
+    return { kind: "defer" };
+  }
+  const reason =
+    typeof parsed.reason === "string" && parsed.reason.length > 0
+      ? parsed.reason
+      : GENERIC_TEACHING_REASON;
+  return { kind: "deny", reason };
+}
+
+/** Concatenate the text parts of an assistant reply. */
+function extractText(reply: AssistantMessage): string {
+  return reply.content
+    .filter((part): part is TextContent => part.type === "text")
+    .map((part) => part.text)
+    .join("");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/src/typo-patterns.ts

@@ -0,0 +1,42 @@
+/**
+ * The cost gate: compile the operator's `typoPatterns` to regexes and test a
+ * candidate path against them.
+ *
+ * Only a path that matches a configured pattern reaches the model — an empty or
+ * absent pattern list matches nothing, so the reviewer defers everything
+ * without a model call.
+ */
+
+/** Result of compiling a pattern list: usable regexes plus any that failed. */
+export interface CompiledTypoPatterns {
+  regexes: RegExp[];
+  invalidPatterns: string[];
+}
+
+/**
+ * Compile each pattern string to a `RegExp`, skipping any that `RegExp` rejects
+ * (recorded in `invalidPatterns` so the caller can warn). Patterns compile
+ * without flags, so `test` is stateless across calls.
+ */
+export function compileTypoPatterns(
+  patterns: readonly string[],
+): CompiledTypoPatterns {
+  const regexes: RegExp[] = [];
+  const invalidPatterns: string[] = [];
+  for (const pattern of patterns) {
+    try {
+      regexes.push(new RegExp(pattern));
+    } catch {
+      invalidPatterns.push(pattern);
+    }
+  }
+  return { regexes, invalidPatterns };
+}
+
+/** Whether any compiled pattern matches `path`. */
+export function matchesAnyTypoPattern(
+  path: string,
+  compiled: CompiledTypoPatterns,
+): boolean {
+  return compiled.regexes.some((regex) => regex.test(path));
+}

package/src/typo-reviewer.ts

@@ -0,0 +1,117 @@
+/**
+ * The deny-first typo-path reviewer: the `Authorizer` chain link this package
+ * registers as `"model-judge"`.
+ *
+ * The decision runs top to bottom, deferring at the first miss so the cheap
+ * gates short-circuit before any model call:
+ *   1. surface is `external_directory` (else defer),
+ *   2. a candidate path is present (else defer),
+ *   3. the path matches a configured typo pattern (else defer, no model call),
+ *   4. the model confirms the typo (deny with a teaching reason) or defers.
+ *
+ * Every failure path defers — more prompting, never less (ADR 0007 invariant 2).
+ * This slice never emits `allow`.
+ */
+
+import type {
+  Authorizer,
+  PromptPermissionDetails,
+} from "@gotgenes/pi-permission-system";
+
+import type { ModelJudgeConfig } from "./config-schema";
+import {
+  type CompleteFn,
+  type ModelRegistryLike,
+  reviewPath,
+} from "./model-review";
+import {
+  type CompiledTypoPatterns,
+  compileTypoPatterns,
+  matchesAnyTypoPattern,
+} from "./typo-patterns";
+
+const REVIEWED_SURFACE = "external_directory";
+
+/** Collaborators for the reviewer, injected so the extension and tests wire them. */
+export interface TypoReviewerDeps {
+  /** The loaded config, read live (absent until session config loads). */
+  getConfig: () => ModelJudgeConfig | undefined;
+  /** The session model registry, read live (captured at `session_start`). */
+  getRegistry: () => ModelRegistryLike | undefined;
+  /** The model-completion seam (production: `complete` from `@earendil-works/pi-ai`). */
+  complete: CompleteFn;
+  /** Optional warn sink for operational notices (unresolved model, bad patterns). */
+  warn?: (message: string) => void;
+}
+
+/**
+ * Build the `authorize` callback registered on the chain. The `query` argument
+ * is unused in this slice — the deny-first reviewer decides from the path
+ * pattern and the model, not from an engine re-query (slice 2 consumes it).
+ */
+export function createTypoReviewer(
+  deps: TypoReviewerDeps,
+): Authorizer["authorize"] {
+  const compiledFor = memoizeCompiledPatterns(deps.warn);
+
+  return async (details) => {
+    const config = deps.getConfig();
+    if (!config) {
+      return { kind: "defer" };
+    }
+    if (surfaceOf(details) !== REVIEWED_SURFACE) {
+      return { kind: "defer" };
+    }
+    const path = pathOf(details);
+    if (path === undefined) {
+      return { kind: "defer" };
+    }
+    if (!matchesAnyTypoPattern(path, compiledFor(config))) {
+      return { kind: "defer" };
+    }
+    const model = deps.getRegistry()?.find(config.provider, config.model);
+    if (!model) {
+      deps.warn?.(
+        `model "${config.provider}/${config.model}" did not resolve; deferring`,
+      );
+      return { kind: "defer" };
+    }
+    return reviewPath({ path, config, model, complete: deps.complete });
+  };
+}
+
+/** The gate-authoritative surface, falling back to the display surface. */
+function surfaceOf(details: PromptPermissionDetails): string | undefined {
+  return details.accessIntent?.surface ?? details.surface ?? undefined;
+}
+
+/** The candidate path — `path` for a local ask, `value` for a forwarded one. */
+function pathOf(details: PromptPermissionDetails): string | undefined {
+  return details.path ?? details.value ?? undefined;
+}
+
+/**
+ * Compile a config's patterns once and reuse the result while the same config
+ * object is in effect — the config is stable per session, so this avoids
+ * recompiling the regexes on every ask.
+ */
+function memoizeCompiledPatterns(
+  warn?: (message: string) => void,
+): (config: ModelJudgeConfig) => CompiledTypoPatterns {
+  let cache:
+    | { config: ModelJudgeConfig; compiled: CompiledTypoPatterns }
+    | undefined;
+  return (config) => {
+    if (cache?.config === config) {
+      return cache.compiled;
+    }
+    const compiled = compileTypoPatterns(config.typoPatterns);
+    if (compiled.invalidPatterns.length > 0) {
+      warn?.(
+        `ignoring invalid typoPatterns: ${compiled.invalidPatterns.join(", ")}`,
+      );
+    }
+    cache = { config, compiled };
+    return compiled;
+  };
+}