@czottmann/pi-automode 1.11.0 → 1.12.0

package/extensions/auto-mode/paths.ts

@@ -1,35 +1,119 @@
-import { lstatSync, readlinkSync, realpathSync } from "node:fs";
+import {
+  accessSync,
+  constants,
+  lstatSync,
+  readlinkSync,
+  realpathSync,
+} from "node:fs";
 import {
   basename,
   dirname,
   isAbsolute,
+  join,
   normalize,
   relative,
   resolve,
 } from "node:path";
+import { fileURLToPath } from "node:url";
 import { HOME, PATH_BEARING_TOOLS, PROFILE_FILES } from "./constants.ts";
 
-function stripLeadingAt(value: string): string {
-  return value.startsWith("@") ? value.slice(1) : value;
+const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+
+/** Convert Git Bash, MSYS, Cygwin, and WSL drive paths for Windows APIs. */
+function normalizeWindowsShellPath(path: string): string {
+  if (
+    process.platform !== "win32" ||
+    !path.startsWith("/") ||
+    path.startsWith("//") ||
+    path.includes("\\")
+  ) {
+    return path;
+  }
+  const match = path.match(/^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i);
+  if (!match) return path;
+  const suffix = match[2]?.replaceAll("/", "\\");
+  return `${match[1]?.toUpperCase()}:\\${suffix ?? ""}`;
+}
+
+/** Mirror Pi's path normalization options. */
+function normalizeInputPath(
+  value: string,
+  options: { normalizeUnicodeSpaces?: boolean; stripAtPrefix?: boolean } = {},
+): string {
+  let normalized = options.normalizeUnicodeSpaces
+    ? value.replace(UNICODE_SPACES, " ")
+    : value;
+  if (options.stripAtPrefix && normalized.startsWith("@")) {
+    normalized = normalized.slice(1);
+  }
+  normalized = normalizeWindowsShellPath(normalized);
+  if (normalized === "~") return HOME;
+  if (
+    normalized.startsWith("~/") ||
+    (process.platform === "win32" && normalized.startsWith("~\\"))
+  ) {
+    return join(HOME, normalized.slice(2));
+  }
+  if (/^file:\/\//.test(normalized)) return fileURLToPath(normalized);
+  return normalized;
 }
 
 export function resolveInputPath(
   cwd: string,
   value: unknown,
 ): string | undefined {
-  if (typeof value !== "string" || value.trim() === "") return undefined;
-  const raw = stripLeadingAt(value.trim());
-  return isAbsolute(raw) ? resolve(raw) : resolve(cwd, raw);
+  if (typeof value !== "string") return undefined;
+  const normalized = normalizeInputPath(value, {
+    normalizeUnicodeSpaces: true,
+    stripAtPrefix: true,
+  });
+  return isAbsolute(normalized)
+    ? resolve(normalized)
+    : resolve(normalizeInputPath(cwd), normalized);
 }
 
-/** The target path a file tool operates on, from `input.path` (or undefined). */
+function existingReadVariant(path: string): string {
+  const candidates = [
+    path,
+    path.replace(/ (AM|PM)\./gi, "\u202F$1."),
+    path.normalize("NFD"),
+    path.replace(/'/g, "\u2019"),
+    path.normalize("NFD").replace(/'/g, "\u2019"),
+  ];
+  for (const candidate of candidates) {
+    try {
+      accessSync(candidate, constants.F_OK);
+      return candidate;
+    } catch {
+      // Try the next Pi-compatible read fallback.
+    }
+  }
+  return path;
+}
+
+/** Resolve the path that the named Pi file tool will operate on. */
+export function resolveToolInputPath(
+  toolName: string,
+  cwd: string,
+  value: unknown,
+): string | undefined {
+  const resolved = resolveInputPath(cwd, value);
+  if (!resolved || toolName !== "read") return resolved;
+  return existingReadVariant(resolved);
+}
+
+/** The effective target path of a file tool, including Pi's `.` defaults. */
 export function extractInputPath(
   toolName: string,
   input: Record<string, unknown>,
 ): string | undefined {
   if (!PATH_BEARING_TOOLS.has(toolName)) return undefined;
   const value = input.path;
-  return typeof value === "string" && value.trim() !== "" ? value : undefined;
+  if (typeof value === "string" && value !== "") return value;
+  if (toolName === "grep" || toolName === "find" || toolName === "ls") {
+    return ".";
+  }
+  return typeof value === "string" ? value : undefined;
 }
 
 /** Expand a leading `~`, `$HOME`, or `${HOME}` in a path-denial pattern. */

package/extensions/auto-mode/permissions.ts

@@ -2,9 +2,31 @@ import type { ToolPattern } from "./types.ts";
 import {
   expandHomePattern,
   normalizePathForMatch,
-  resolveInputPath,
+  resolvePathForPolicy,
+  resolveToolInputPath,
 } from "./paths.ts";
 
+export const MAX_WILDCARD_PATTERN_LENGTH = 4096;
+export const MAX_WILDCARD_INPUT_LENGTH = 1024 * 1024;
+
+/** Preserve the previous non-Unicode RegExp `/i` case-equivalence rules. */
+function canonicalizeCase(value: string): string {
+  let canonical = "";
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index] ?? "";
+    const uppercase = character.toUpperCase();
+    if (
+      uppercase.length !== 1 ||
+      (character.charCodeAt(0) >= 128 && uppercase.charCodeAt(0) < 128)
+    ) {
+      canonical += character;
+    } else {
+      canonical += uppercase;
+    }
+  }
+  return canonical;
+}
+
 function normalizeToolName(name: string): string {
   const lower = name.trim().replace(/^@/, "").toLowerCase();
   const aliases: Record<string, string> = {
@@ -40,11 +62,108 @@ export function parseToolPattern(value: unknown): ToolPattern | undefined {
   };
 }
 
-function wildcardToRegExp(pattern: string): RegExp {
-  const escaped = pattern
-    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
-    .replace(/\*/g, ".*");
-  return new RegExp(`^${escaped}$`, "i");
+function literalPrefixTable(value: string): number[] {
+  const table = new Array<number>(value.length).fill(0);
+  let prefixLength = 0;
+  for (let index = 1; index < value.length; index += 1) {
+    while (
+      prefixLength > 0 && value[index] !== value[prefixLength]
+    ) {
+      prefixLength = table[prefixLength - 1] ?? 0;
+    }
+    if (value[index] === value[prefixLength]) prefixLength += 1;
+    table[index] = prefixLength;
+  }
+  return table;
+}
+
+function findLiteral(
+  value: string,
+  literal: string,
+  start: number,
+  end: number,
+): number {
+  const prefixTable = literalPrefixTable(literal);
+  let matched = 0;
+  for (let index = start; index < end; index += 1) {
+    while (matched > 0 && value[index] !== literal[matched]) {
+      matched = prefixTable[matched - 1] ?? 0;
+    }
+    if (value[index] === literal[matched]) matched += 1;
+    if (matched === literal.length) return index - literal.length + 1;
+  }
+  return -1;
+}
+
+export type WildcardOverflowPolicy = "match" | "no-match";
+
+/**
+ * Match a case-insensitive `*` wildcard pattern in linear time.
+ *
+ * `*` matches zero or more characters, including newlines and path separators.
+ * Denial callers use `match` for over-limit values so they fail closed. Allow
+ * callers use `no-match` so an oversized input cannot broaden an allow rule.
+ */
+export function matchesWildcardPattern(
+  pattern: string,
+  value: string,
+  overflowPolicy: WildcardOverflowPolicy = "match",
+): boolean {
+  if (
+    pattern.length > MAX_WILDCARD_PATTERN_LENGTH ||
+    value.length > MAX_WILDCARD_INPUT_LENGTH
+  ) {
+    return overflowPolicy === "match";
+  }
+
+  const normalizedPattern = canonicalizeCase(pattern);
+  const normalizedValue = canonicalizeCase(value);
+  if (!normalizedPattern.includes("*")) {
+    return normalizedPattern === normalizedValue;
+  }
+
+  const startsWithWildcard = normalizedPattern.startsWith("*");
+  const endsWithWildcard = normalizedPattern.endsWith("*");
+  const literals = normalizedPattern.split("*").filter(Boolean);
+  if (literals.length === 0) return true;
+
+  let literalIndex = 0;
+  let valueIndex = 0;
+  let lastLiteralIndex = literals.length;
+
+  if (!startsWithWildcard) {
+    const prefix = literals[0] ?? "";
+    if (!normalizedValue.startsWith(prefix)) return false;
+    valueIndex = prefix.length;
+    literalIndex = 1;
+  }
+
+  let searchEnd = normalizedValue.length;
+  if (!endsWithWildcard) {
+    const suffix = literals[literals.length - 1] ?? "";
+    searchEnd -= suffix.length;
+    if (
+      searchEnd < valueIndex ||
+      !normalizedValue.endsWith(suffix)
+    ) {
+      return false;
+    }
+    lastLiteralIndex -= 1;
+  }
+
+  for (; literalIndex < lastLiteralIndex; literalIndex += 1) {
+    const literal = literals[literalIndex] ?? "";
+    const found = findLiteral(
+      normalizedValue,
+      literal,
+      valueIndex,
+      searchEnd,
+    );
+    if (found < 0) return false;
+    valueIndex = found + literal.length;
+  }
+
+  return true;
 }
 
 function getPrimaryArgument(
@@ -60,7 +179,7 @@ function getPrimaryArgument(
     typeof input.path === "string"
   ) {
     return normalizePathForMatch(
-      resolveInputPath(cwd, input.path) ?? input.path,
+      resolveToolInputPath(toolName, cwd, input.path) ?? input.path,
       cwd,
     );
   }
@@ -72,7 +191,7 @@ function getPrimaryArgument(
     typeof input.path === "string"
   ) {
     return normalizePathForMatch(
-      resolveInputPath(cwd, input.path) ?? input.path,
+      resolveToolInputPath(toolName, cwd, input.path) ?? input.path,
       cwd,
     );
   }
@@ -89,10 +208,80 @@ export function matchesDeniedPath(
   resolvedPath: string,
   deniedPaths: string[],
 ): boolean {
-  const normalized = resolvedPath.replace(/\\/g, "/");
+  const normalized = resolvedPath.replace(/\\/g, "/").normalize("NFC");
+  return deniedPaths.some((pattern) =>
+    deniedPatternVariants(pattern).some((variant) =>
+      matchesWildcardPattern(variant.normalize("NFC"), normalized)
+    )
+  );
+}
+
+function deniedPatternVariants(pattern: string): string[] {
+  const expanded = expandHomePattern(pattern).replace(/\\/g, "/");
+  const wildcardIndex = expanded.indexOf("*");
+  if (wildcardIndex === -1) {
+    const canonical = resolvePathForPolicy(expanded)?.replace(/\\/g, "/");
+    return canonical && canonical !== expanded
+      ? [expanded, canonical]
+      : [expanded];
+  }
+
+  const fixedPrefix = expanded.slice(0, wildcardIndex);
+  const lastSlash = fixedPrefix.lastIndexOf("/");
+  if (lastSlash < 0) return [expanded];
+  const fixedScope = fixedPrefix.slice(0, lastSlash) || "/";
+  const canonicalScope = resolvePathForPolicy(fixedScope)?.replace(/\\/g, "/");
+  if (!canonicalScope || canonicalScope === fixedScope) return [expanded];
+  const suffix = expanded.slice(lastSlash).replace(/^\/+/, "");
+  const canonicalPattern = canonicalScope === "/"
+    ? `/${suffix}`
+    : `${withoutTrailingSlash(canonicalScope)}/${suffix}`;
+  return canonicalPattern === expanded
+    ? [expanded]
+    : [expanded, canonicalPattern];
+}
+
+function withoutTrailingSlash(path: string): string {
+  if (path === "/" || /^[A-Za-z]:\/$/.test(path)) return path;
+  return path.replace(/\/+$/, "");
+}
+
+function wildcardCanMatchDescendant(root: string, pattern: string): boolean {
+  const normalizedRoot = withoutTrailingSlash(
+    canonicalizeCase(root.replace(/\\/g, "/").normalize("NFC")),
+  );
+  const prefix = normalizedRoot === "/" || /^[A-Za-z]:\/$/.test(normalizedRoot)
+    ? normalizedRoot
+    : `${normalizedRoot}/`;
+  const normalizedPattern = canonicalizeCase(pattern.normalize("NFC"));
+  const wildcardIndex = normalizedPattern.indexOf("*");
+  if (wildcardIndex < 0) {
+    return normalizedPattern.length > prefix.length &&
+      normalizedPattern.startsWith(prefix);
+  }
+
+  const fixedPrefix = normalizedPattern.slice(0, wildcardIndex);
+  return prefix.startsWith(fixedPrefix) || fixedPrefix.startsWith(prefix);
+}
+
+/**
+ * Whether a recursive search scope can contain a path matched by `deniedPaths`.
+ *
+ * The check asks whether the wildcard pattern can match any path beginning
+ * with the search-root prefix. It does not scan the search tree.
+ */
+export function recursiveSearchMayReachDeniedPath(
+  resolvedRoot: string,
+  deniedPaths: string[],
+): boolean {
+  if (resolvedRoot.length > MAX_WILDCARD_INPUT_LENGTH) {
+    return deniedPaths.length > 0;
+  }
   return deniedPaths.some((pattern) => {
-    const expanded = expandHomePattern(pattern).replace(/\\/g, "/");
-    return wildcardToRegExp(expanded).test(normalized);
+    if (pattern.length > MAX_WILDCARD_PATTERN_LENGTH) return true;
+    return deniedPatternVariants(pattern).some((expanded) =>
+      wildcardCanMatchDescendant(resolvedRoot, expanded)
+    );
   });
 }
 
@@ -102,10 +291,11 @@ export function matchesToolPattern(
   toolName: string,
   input: Record<string, unknown>,
   cwd: string,
+  overflowPolicy: WildcardOverflowPolicy = "match",
 ): boolean {
   if (!pattern.toolName) return false;
   if (pattern.toolName !== normalizeToolName(toolName)) return false;
-  if (!pattern.argumentPattern || pattern.argumentPattern === "*") return true;
+  if (!pattern.argumentPattern) return true;
   const primary = getPrimaryArgument(toolName, input, cwd);
-  return wildcardToRegExp(pattern.argumentPattern).test(primary);
+  return matchesWildcardPattern(pattern.argumentPattern, primary, overflowPolicy);
 }

package/extensions/auto-mode/state.ts

@@ -37,6 +37,7 @@ export function statusText(
     `classifier denied: ${state.classifierDenied}`,
     `permissions.deny rules: ${config.permissionDeny.length}`,
     `permissions.ask rules: ${config.permissionAsk.length}`,
+    `permissions.allow rules: ${config.permissionAllow.length}`,
     `environment entries: ${config.environment.length}`,
     `allow entries: ${config.allow.length}`,
     `soft_deny entries: ${config.softDeny.length}`,

package/extensions/auto-mode/types.ts

@@ -44,6 +44,8 @@ export type AutoModeSettings = {
   classifyReadOnlyTools?: boolean;
   /** Override the fast-stage completion token budget (default 512). */
   fastClassifierMaxTokens?: number;
+  /** Per-request timeout for classifier completions in milliseconds (default 20000). */
+  classifierTimeoutMs?: number;
   /** When true, file tools whose resolved path is inside the working directory are allowed deterministically (no classifier), and outside-CWD file access is classified. */
   allowInsideWorkingDirectory?: boolean;
   /** Path glob patterns (file tools) that are always denied before the classifier. Supports `~` and `*` (matches any characters, including `/`). */
@@ -65,6 +67,11 @@ export type SettingsFile = {
   permissions?: {
     deny?: unknown;
     ask?: unknown;
+    /**
+     * Deterministic allow tier: matching calls skip the classifier only. Read
+     * from user-owned config sources, never shared project config.
+     */
+    allow?: unknown;
   };
 };
 
@@ -86,6 +93,7 @@ export type EffectiveConfig = {
   classifierReasoningLevel?: ClassifierReasoningLevel;
   classifyReadOnlyTools: boolean;
   fastClassifierMaxTokens: number;
+  classifierTimeoutMs: number;
   allowInsideWorkingDirectory: boolean;
   deniedPaths: string[];
   maxUserTranscriptTokens: number;
@@ -97,6 +105,7 @@ export type EffectiveConfig = {
   hardDeny: string[];
   permissionDeny: ToolPattern[];
   permissionAsk: ToolPattern[];
+  permissionAllow: ToolPattern[];
   log: LogConfig;
 };
 
@@ -128,6 +137,7 @@ export type DenialRecord = {
 /** Denial kind plus the deterministic allow fast paths, used for decision log entries. */
 export type DecisionKind =
   | DenialRecord["kind"]
+  | "permissions.allow"
   | "read-only"
   | "inside-working-directory";
 
@@ -161,6 +171,7 @@ export type ClassifierIo = {
   prompt: {
     system: string;
     context: string;
+    action: string;
     fastInstruction: string;
     detailedInstruction: string;
   };

package/extensions/auto-mode/utils.ts

@@ -30,7 +30,15 @@ export function safeJson(value: unknown, maxLength = 4000): string {
             Math.max(200, Math.floor(maxLength / 4)),
           );
         }
-        if (Array.isArray(current)) return current.slice(0, 30);
+        if (Array.isArray(current)) {
+          if (current.length <= 30) return current;
+          return {
+            $truncatedArray: true,
+            items: current.slice(0, 30),
+            omittedEntries: current.length - 30,
+            totalEntries: current.length,
+          };
+        }
         if (current && typeof current === "object") {
           if (seen.has(current)) return "[Circular]";
           seen.add(current);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@czottmann/pi-automode",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Claude Code-style auto mode guardrail for pi.",
   "repository": {
     "url": "https://github.com/czottmann/pi-automode"
@@ -25,20 +25,26 @@
     "test": "node --import tsx --test tests/*.test.ts"
   },
   "files": [
+    "CHANGELOG.md",
     "docs",
     "extensions",
     "examples",
+    "skills",
     "README.md"
   ],
   "pi": {
     "extensions": [
       "./extensions/auto-mode.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "^0.84.1",
@@ -46,6 +52,7 @@
     "@earendil-works/pi-tui": "^0.84.1",
     "@types/node": "^24.0.0",
     "tsx": "^4.22.4",
+    "typebox": "^1.3.10",
     "typescript": "^5.8.0"
   }
 }

package/skills/automode-diagnostics/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: automode-diagnostics
+description: Diagnose unexpected pi-automode decisions from active state, effective rules, and observability logs. Use when auto mode blocks a safe action, allows an unsafe action, or needs a narrowly scoped rule correction.
+---
+
+# Automode diagnostics
+
+Use this skill to investigate a pi-automode decision. Read [Agent diagnostics](../../docs/diagnostics.md), [Classifier flow](../../docs/automode-classifier-flow.md), [Defaults](../../docs/defaults.md), and [Observability logging](../../docs/observability-logging.md) before you change configuration.
+
+## Safety rules
+
+- Investigate before you edit configuration.
+- Do not evade a denial with another tool, path, or disabled safety control.
+- Do not weaken a rule only to make one action pass.
+- Do not print credentials, tokens, private keys, signed URLs, or sensitive tool input.
+- Preserve unrelated working-tree and configuration changes.
+- Do not run an unsafe rejected action because auto mode is off.
+
+`automode_inspect` is read-only. It cannot change auto mode or configuration. Its output is model-visible and omits denial reasons and action payloads. Treat truncated output as incomplete.
+
+## Investigation
+
+1. Call `automode_inspect` with `status`, `config`, and `denials`.
+2. Read the reported log path only when observability logging is enabled.
+3. Use the denial timestamp, enforcement kind, and tool name to locate the relevant decision entry.
+4. Inspect a decision reason only after you verify that it cannot contain sensitive input.
+5. Identify the enforcement layer before you propose a change:
+   - `permissions.deny` and `permissions.ask` are local rules.
+   - `deterministic-hard-deny` is extension code.
+   - `read-only` is a local allow.
+   - `classifier` is a model decision.
+6. Do not tune classifier rules to solve a permission or deterministic denial.
+
+For a classifier decision, use the effective configuration and the logged classifier metadata when available. Do not dump full prompts or raw responses. They can contain session context and tool input.
+
+## Configuration correction
+
+Only change configuration when the user explicitly requests a correction.
+
+1. Explain the proposed narrow change.
+2. Ask the user to run `/automode off`.
+3. Wait for confirmation.
+4. While auto mode is off, edit only the requested automode configuration and related evidence files.
+5. Validate JSON syntax and the exact diff.
+6. Ask the user to run `/automode reload` and then `/automode on`.
+7. Call `automode_inspect` with `status` and `config` to confirm that auto mode is enabled and the new configuration is active.
+8. Retry an action only when the user requested it and the action is safe.
+
+When a correction replaces a rule list, check whether it retains `$defaults`. Keep unrelated protections. Test the corrected non-secret case, the secret-bearing variant, an unapproved destination, and an unrelated hard-deny case.
+
+## Report
+
+Report:
+
+- the active configuration and log paths;
+- the decision timestamp, ID, and enforcement layer;
+- the evidence for the decision;
+- the proposed or applied narrow change;
+- validation performed and expected regression cases;
+- remaining uncertainty; and
+- whether auto mode is enabled.
+
+If the session ends while auto mode is off, tell the user to run `/automode on`.