@czottmann/pi-automode 1.0.0 → 1.2.0

package/README.md

@@ -66,6 +66,7 @@ Example:
       "Trusted internal domains: *.corp.example.com"
     ],
     "allow": ["$defaults"],
+    "protectedPaths": ["$defaults"],
     "soft_deny": ["$defaults"],
     "hard_deny": [
       "$defaults",
@@ -106,6 +107,16 @@ Example:
 
 These are exceptions to `soft_deny`, not to `hard_deny`.
 
+#### `protectedPaths`
+
+`$defaults` expands to paths where writes are never auto-approved — they always go to the classifier, regardless of `allow` rules. This matches Claude Code's protected-paths behavior.
+
+Protected directories: `.git`, `.config/git`, `.vscode`, `.idea`, `.husky`, `.cargo`, `.devcontainer`, `.yarn`, `.mvn`, `.pi`.
+
+Protected files: `.gitconfig`, `.gitmodules`, `.gitignore`, `.gitattributes`, shell profiles (`.bashrc`, `.zshrc`, `.profile`, etc.), `.envrc`, package manager configs (`.npmrc`, `.yarnrc`, `.yarnrc.yml`, `.pnp.cjs`, `bunfig.toml`, etc.), Bazel configs (`.bazelrc`, `.bazelversion`, `.bazeliskrc`), hook configs (`.pre-commit-config.yaml`, `lefthook.yml`), Gradle/Maven wrappers, `.devcontainer.json`, `.ripgreprc`, `pyrightconfig.json`, `.mcp.json`.
+
+Read-only tools (`read`, `grep`, `find`, `ls`) bypass this check — reads to protected paths are always allowed. Only `write` and `edit` are affected.
+
 #### `soft_deny`
 
 `$defaults` expands to soft blocks for:
@@ -167,7 +178,7 @@ If you omit `$defaults`, you replace the built-ins for that section:
 }
 ```
 
-That means: use only that one `allow` entry. The built-in `allow` entries are not used. Replacing `allow` does not replace `soft_deny`, `hard_deny`, or `environment`.
+That means: use only that one `allow` entry. The built-in `allow` entries are not used. Replacing `allow` does not replace `soft_deny`, `hard_deny`, `protectedPaths`, or `environment`.
 
 `$defaults` is not used in `permissions.deny` or `permissions.ask`. Those lists contain only explicit Pi tool patterns.
 
@@ -190,6 +201,8 @@ The extension blocks these before any allow or classifier decision:
 
 Read-only Pi tools (`read`, `grep`, `find`, `ls`) are allowed after those checks.
 
+Writes to [protected paths](#protectedpaths) (shell profiles, tool configs, `.git`, `.vscode`, `.pi`, etc.) always go to the classifier, even if an `allow` rule matches. The classifier decides whether to permit the write.
+
 Everything else goes to the classifier. If the classifier is missing, fails, or returns invalid JSON, the action is blocked.
 
 ## Examples
@@ -204,7 +217,7 @@ npm test
 npm pack --dry-run
 ```
 
-The tests cover the risky parts: scoped permission matching, config-source precedence, `$defaults` behavior, config diagnostics, deterministic hard-deny checks, shell parsing for risky bash fragments, classifier JSON parsing, hook-level blocking/allowing, and classifier mocking.
+The tests cover the risky parts: scoped permission matching, config-source precedence, `$defaults` behavior, config diagnostics, deterministic hard-deny checks, shell parsing for risky bash fragments, classifier JSON parsing, hook-level blocking/allowing, classifier mocking, and protected-path enforcement.
 
 ## Known limits
 

package/extensions/auto-mode/classifier.ts

@@ -0,0 +1,152 @@
+import { complete } from "@earendil-works/pi-ai";
+import type {
+  AssistantMessage,
+  Model,
+  UserMessage,
+} from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { CLASSIFIER_SYSTEM_PROMPT } from "./constants.ts";
+import { parseModelSpec } from "./model.ts";
+import { buildTranscript } from "./transcript.ts";
+import type {
+  ClassificationDecision,
+  ClassifyAction,
+  EffectiveConfig,
+} from "./types.ts";
+
+export function buildClassifierPrompt(config: EffectiveConfig): string {
+  return CLASSIFIER_SYSTEM_PROMPT.replace(
+    "<ENVIRONMENT>",
+    config.environment.map((line) => `- ${line}`).join("\n"),
+  )
+    .replace(
+      "<ALLOW_RULES>",
+      config.allow.map((line) => `- ${line}`).join("\n"),
+    )
+    .replace(
+      "<SOFT_DENY_RULES>",
+      config.softDeny.map((line) => `- ${line}`).join("\n"),
+    )
+    .replace(
+      "<HARD_DENY_RULES>",
+      config.hardDeny.map((line) => `- ${line}`).join("\n"),
+    );
+}
+
+async function resolveClassifier(
+  ctx: ExtensionContext,
+  config: EffectiveConfig,
+): Promise<
+  | { model: Model<any>; apiKey?: string; headers?: Record<string, string> }
+  | undefined
+> {
+  const configured = config.classifierModel;
+  const model = configured
+    ? (() => {
+      const parsed = parseModelSpec(configured);
+      return parsed
+        ? ctx.modelRegistry.find(parsed.provider, parsed.id)
+        : undefined;
+    })()
+    : ctx.model;
+  if (!model) return undefined;
+  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+  if (!auth.ok) return undefined;
+  return { model, apiKey: auth.apiKey, headers: auth.headers };
+}
+
+/** Parse the classifier's JSON-only response. Invalid output is handled fail-closed by the caller. */
+export function parseClassifierDecision(
+  message: AssistantMessage,
+): ClassificationDecision | undefined {
+  const text = message.content
+    .filter(
+      (block): block is { type: "text"; text: string } => block.type === "text",
+    )
+    .map((block) => block.text)
+    .join("\n")
+    .trim();
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i)?.[1];
+  const candidates = [fenced, text, text.match(/\{[\s\S]*\}/)?.[0]].filter(
+    Boolean,
+  ) as string[];
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(candidate) as Partial<ClassificationDecision>;
+      if (
+        (parsed.decision === "allow" || parsed.decision === "block") &&
+        typeof parsed.reason === "string"
+      ) {
+        return {
+          decision: parsed.decision,
+          tier: parsed.tier ?? "none",
+          reason: parsed.reason,
+        };
+      }
+    } catch {
+      // Try next candidate.
+    }
+  }
+  return undefined;
+}
+
+export const defaultClassifyAction: ClassifyAction = async (
+  ctx,
+  config,
+  action,
+  loadedContext,
+): Promise<ClassificationDecision> => {
+  const classifier = await resolveClassifier(ctx, config);
+  if (!classifier) {
+    return {
+      decision: "block",
+      tier: "none",
+      reason: "No classifier model/API key available; auto mode fails closed.",
+    };
+  }
+
+  const userMessage: UserMessage = {
+    role: "user",
+    content: [
+      {
+        type: "text",
+        text: `<loaded-project-instructions>\n${
+          loadedContext || "(none)"
+        }\n</loaded-project-instructions>\n\n<transcript>\n${
+          buildTranscript(ctx, config.maxTranscriptLines) || "(none)"
+        }\n</transcript>\n\nLatest action to classify:\n${action}`,
+      },
+    ],
+    timestamp: Date.now(),
+  };
+
+  try {
+    const response = await complete(
+      classifier.model,
+      { systemPrompt: buildClassifierPrompt(config), messages: [userMessage] },
+      {
+        apiKey: classifier.apiKey,
+        headers: classifier.headers,
+        signal: ctx.signal,
+        maxTokens: 700,
+        temperature: 0,
+      },
+    );
+    return (
+      parseClassifierDecision(response) ?? {
+        decision: "block",
+        tier: "none",
+        reason:
+          "Classifier response was not valid decision JSON; auto mode fails closed.",
+      }
+    );
+  } catch (error) {
+    return {
+      decision: "block",
+      tier: "none",
+      reason: `Classifier failed; auto mode fails closed: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    };
+  }
+};

package/extensions/auto-mode/config.ts

@@ -0,0 +1,399 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  DEFAULT_ALLOW,
+  DEFAULT_ENVIRONMENT,
+  DEFAULT_HARD_DENY,
+  DEFAULT_MAX_TRANSCRIPT_LINES,
+  DEFAULT_PROTECTED_PATHS,
+  DEFAULT_SOFT_DENY,
+  PI_GLOBAL_SETTINGS,
+  PI_PROJECT_LOCAL_SETTINGS,
+  PI_PROJECT_SHARED_SETTINGS,
+} from "./constants.ts";
+import { parseToolPattern } from "./permissions.ts";
+import type {
+  AutoModeSettings,
+  ConfigLoadResult,
+  EffectiveConfig,
+  LoadedSettingsFile,
+  SettingsFile,
+  SettingsSources,
+  ToolPattern,
+} from "./types.ts";
+import { hasOwn, stringArray } from "./utils.ts";
+
+function readSettingsFile(path: string): LoadedSettingsFile | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    const settings = JSON.parse(readFileSync(path, "utf8")) as SettingsFile;
+    return {
+      path,
+      settings,
+      diagnostics: validateSettingsFile(settings, path),
+    };
+  } catch (error) {
+    return {
+      path,
+      diagnostics: [
+        `${path}: invalid JSON (${
+          error instanceof Error ? error.message : String(error)
+        })`,
+      ],
+    };
+  }
+}
+
+function validateStringArraySetting(
+  value: unknown,
+  source: string,
+  key: string,
+  diagnostics: string[],
+): void {
+  if (value === undefined) return;
+  if (!Array.isArray(value)) {
+    diagnostics.push(`${source}: ${key} must be an array of strings`);
+    return;
+  }
+  for (const [index, entry] of value.entries()) {
+    if (typeof entry !== "string" || entry.trim() === "") {
+      diagnostics.push(
+        `${source}: ${key}[${index}] must be a non-empty string`,
+      );
+    }
+  }
+  if (value.length > 0 && !value.includes("$defaults")) {
+    diagnostics.push(
+      `${source}: ${key} omits "$defaults" and replaces the built-in ${key} rules`,
+    );
+  }
+}
+
+/** Validate config shape and emit human-readable diagnostics for `/automode config`. */
+export function validateSettingsFile(
+  settings: SettingsFile,
+  source: string,
+): string[] {
+  const diagnostics: string[] = [];
+  const root = settings as Record<string, unknown>;
+  for (const key of Object.keys(root)) {
+    if (key !== "autoMode" && key !== "permissions") {
+      diagnostics.push(`${source}: unknown top-level key ${key}`);
+    }
+  }
+
+  if (settings.autoMode !== undefined) {
+    if (
+      !settings.autoMode ||
+      typeof settings.autoMode !== "object" ||
+      Array.isArray(settings.autoMode)
+    ) {
+      diagnostics.push(`${source}: autoMode must be an object`);
+    } else {
+      const autoMode = settings.autoMode as Record<string, unknown>;
+      const knownAutoMode = new Set([
+        "enabled",
+        "classifierModel",
+        "maxTranscriptLines",
+        "environment",
+        "allow",
+        "protectedPaths",
+        "soft_deny",
+        "softDeny",
+        "hard_deny",
+        "hardDeny",
+      ]);
+      for (const key of Object.keys(autoMode)) {
+        if (!knownAutoMode.has(key)) {
+          diagnostics.push(`${source}: unknown autoMode key ${key}`);
+        }
+      }
+      if (
+        hasOwn(autoMode, "enabled") && typeof autoMode.enabled !== "boolean"
+      ) {
+        diagnostics.push(`${source}: autoMode.enabled must be a boolean`);
+      }
+      if (
+        hasOwn(autoMode, "classifierModel") &&
+        typeof autoMode.classifierModel !== "string"
+      ) {
+        diagnostics.push(
+          `${source}: autoMode.classifierModel must be a provider/model string`,
+        );
+      }
+      if (
+        hasOwn(autoMode, "maxTranscriptLines") &&
+        (!Number.isInteger(autoMode.maxTranscriptLines) ||
+          Number(autoMode.maxTranscriptLines) <= 0)
+      ) {
+        diagnostics.push(
+          `${source}: autoMode.maxTranscriptLines must be a positive integer`,
+        );
+      }
+      validateStringArraySetting(
+        autoMode.environment,
+        source,
+        "autoMode.environment",
+        diagnostics,
+      );
+      validateStringArraySetting(
+        autoMode.allow,
+        source,
+        "autoMode.allow",
+        diagnostics,
+      );
+      validateStringArraySetting(
+        autoMode.protectedPaths,
+        source,
+        "autoMode.protectedPaths",
+        diagnostics,
+      );
+      validateStringArraySetting(
+        autoMode.soft_deny ?? autoMode.softDeny,
+        source,
+        "autoMode.soft_deny",
+        diagnostics,
+      );
+      validateStringArraySetting(
+        autoMode.hard_deny ?? autoMode.hardDeny,
+        source,
+        "autoMode.hard_deny",
+        diagnostics,
+      );
+    }
+  }
+
+  if (settings.permissions !== undefined) {
+    if (
+      !settings.permissions ||
+      typeof settings.permissions !== "object" ||
+      Array.isArray(settings.permissions)
+    ) {
+      diagnostics.push(`${source}: permissions must be an object`);
+    } else {
+      const permissions = settings.permissions as Record<string, unknown>;
+      for (const key of Object.keys(permissions)) {
+        if (key !== "deny" && key !== "ask") {
+          diagnostics.push(`${source}: unknown permissions key ${key}`);
+        }
+      }
+      for (const key of ["deny", "ask"] as const) {
+        const value = permissions[key];
+        if (value === undefined) continue;
+        if (!Array.isArray(value)) {
+          diagnostics.push(
+            `${source}: permissions.${key} must be an array of tool patterns`,
+          );
+          continue;
+        }
+        for (const [index, entry] of value.entries()) {
+          if (typeof entry !== "string" || !parseToolPattern(entry)) {
+            diagnostics.push(
+              `${source}: permissions.${key}[${index}] must be a tool pattern string`,
+            );
+          }
+        }
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+type RuleAccumulator = {
+  defaults: string[];
+  includeDefaults: boolean;
+  seen: boolean;
+  entries: string[];
+};
+
+function createRuleAccumulator(defaults: string[]): RuleAccumulator {
+  return { defaults, includeDefaults: true, seen: false, entries: [] };
+}
+
+function applyRuleSetting(accumulator: RuleAccumulator, value: unknown): void {
+  const entries = stringArray(value);
+  if (!entries) return;
+  accumulator.seen = true;
+  accumulator.includeDefaults = entries.includes("$defaults");
+  for (const entry of entries) {
+    if (entry !== "$defaults") accumulator.entries.push(entry);
+  }
+}
+
+function finalizeRuleSetting(accumulator: RuleAccumulator): string[] {
+  const base = accumulator.includeDefaults || !accumulator.seen
+    ? accumulator.defaults
+    : [];
+  return [...new Set([...base, ...accumulator.entries])];
+}
+
+function applyAutoModeScalars(
+  base: EffectiveConfig,
+  settings: AutoModeSettings | undefined,
+): EffectiveConfig {
+  if (!settings) return base;
+  return {
+    ...base,
+    enabled: settings.enabled ?? base.enabled,
+    classifierModel: settings.classifierModel ?? base.classifierModel,
+    maxTranscriptLines: settings.maxTranscriptLines ?? base.maxTranscriptLines,
+  };
+}
+
+function appendPermissionPatterns(
+  target: ToolPattern[],
+  settings: SettingsFile | undefined,
+  key: "deny" | "ask",
+): void {
+  const values = stringArray(settings?.permissions?.[key]);
+  if (!values) return;
+  for (const value of values) {
+    const pattern = parseToolPattern(value);
+    if (pattern) target.push(pattern);
+  }
+}
+
+/**
+ * Merge settings with Claude Code-style precedence using Pi-owned config files.
+ *
+ * Important details:
+ * - shared project `.pi/automode.json` contributes `permissions.*` but not `autoMode`,
+ *   so a checked-in repo cannot weaken classifier rules;
+ * - global, project-local, and inline `autoMode` settings combine additively across scopes;
+ * - omitting `$defaults` in any scope for a rule list means "replace built-ins" for that list.
+ */
+export function buildEffectiveConfigFromSources(
+  sources: SettingsSources = {},
+): EffectiveConfig {
+  let config: EffectiveConfig = {
+    enabled: true,
+    maxTranscriptLines: DEFAULT_MAX_TRANSCRIPT_LINES,
+    environment: [...DEFAULT_ENVIRONMENT],
+    allow: [...DEFAULT_ALLOW],
+    protectedPaths: [...DEFAULT_PROTECTED_PATHS],
+    softDeny: [...DEFAULT_SOFT_DENY],
+    hardDeny: [...DEFAULT_HARD_DENY],
+    permissionDeny: [],
+    permissionAsk: [],
+  };
+
+  const globalSettings = sources.globalSettings ?? [];
+  const projectLocalSettings = sources.projectLocalSettings ?? [];
+  const projectSharedSettings = sources.projectSharedSettings ?? [];
+  const inlineSettings = sources.inlineSettings ?? [];
+
+  const configurableSettings = [
+    ...globalSettings,
+    ...projectLocalSettings,
+    ...inlineSettings,
+  ];
+  const environment = createRuleAccumulator(DEFAULT_ENVIRONMENT);
+  const allow = createRuleAccumulator(DEFAULT_ALLOW);
+  const protectedPaths = createRuleAccumulator(DEFAULT_PROTECTED_PATHS);
+  const softDeny = createRuleAccumulator(DEFAULT_SOFT_DENY);
+  const hardDeny = createRuleAccumulator(DEFAULT_HARD_DENY);
+
+  for (const settings of configurableSettings) {
+    config = applyAutoModeScalars(config, settings.autoMode);
+    applyRuleSetting(environment, settings.autoMode?.environment);
+    applyRuleSetting(allow, settings.autoMode?.allow);
+    applyRuleSetting(protectedPaths, settings.autoMode?.protectedPaths);
+    applyRuleSetting(
+      softDeny,
+      settings.autoMode?.soft_deny ?? settings.autoMode?.softDeny,
+    );
+    applyRuleSetting(
+      hardDeny,
+      settings.autoMode?.hard_deny ?? settings.autoMode?.hardDeny,
+    );
+  }
+
+  config = {
+    ...config,
+    environment: finalizeRuleSetting(environment),
+    allow: finalizeRuleSetting(allow),
+    protectedPaths: finalizeRuleSetting(protectedPaths),
+    softDeny: finalizeRuleSetting(softDeny),
+    hardDeny: finalizeRuleSetting(hardDeny),
+  };
+
+  for (
+    const settings of [
+      ...globalSettings,
+      ...projectSharedSettings,
+      ...projectLocalSettings,
+      ...inlineSettings,
+    ]
+  ) {
+    appendPermissionPatterns(config.permissionDeny, settings, "deny");
+    appendPermissionPatterns(config.permissionAsk, settings, "ask");
+  }
+
+  return config;
+}
+
+function loadedSettingsToSettings(
+  files: Array<LoadedSettingsFile | undefined>,
+): SettingsFile[] {
+  return files.flatMap((file) => (file?.settings ? [file.settings] : []));
+}
+
+function loadedSettingsDiagnostics(
+  files: Array<LoadedSettingsFile | undefined>,
+): string[] {
+  return files.flatMap((file) => file?.diagnostics ?? []);
+}
+
+/** Load config from disk and environment variables, including diagnostics for `/automode config`. */
+export function loadEffectiveConfigWithDiagnostics(
+  cwd: string,
+): ConfigLoadResult {
+  const inlineSettings: SettingsFile[] = [];
+  const diagnostics: string[] = [];
+  if (process.env.PI_AUTOMODE_SETTINGS_JSON) {
+    try {
+      const parsed = JSON.parse(
+        process.env.PI_AUTOMODE_SETTINGS_JSON,
+      ) as SettingsFile;
+      inlineSettings.push(parsed);
+      diagnostics.push(
+        ...validateSettingsFile(parsed, "PI_AUTOMODE_SETTINGS_JSON"),
+      );
+    } catch (error) {
+      diagnostics.push(
+        `PI_AUTOMODE_SETTINGS_JSON: invalid JSON (${
+          error instanceof Error ? error.message : String(error)
+        })`,
+      );
+    }
+  }
+
+  const globalFiles = PI_GLOBAL_SETTINGS.map(readSettingsFile);
+  const projectLocalFiles = PI_PROJECT_LOCAL_SETTINGS.map((file) =>
+    readSettingsFile(resolve(cwd, file))
+  );
+  const projectSharedFiles = PI_PROJECT_SHARED_SETTINGS.map((file) =>
+    readSettingsFile(resolve(cwd, file))
+  );
+  const fileDiagnostics = loadedSettingsDiagnostics([
+    ...globalFiles,
+    ...projectLocalFiles,
+    ...projectSharedFiles,
+  ]);
+
+  return {
+    config: buildEffectiveConfigFromSources({
+      globalSettings: loadedSettingsToSettings(globalFiles),
+      projectLocalSettings: loadedSettingsToSettings(projectLocalFiles),
+      projectSharedSettings: loadedSettingsToSettings(projectSharedFiles),
+      inlineSettings,
+    }),
+    diagnostics: [...fileDiagnostics, ...diagnostics],
+  };
+}
+
+/** Load config from disk and environment variables. Exported for tests and diagnostics. */
+export function loadEffectiveConfig(cwd: string): EffectiveConfig {
+  return loadEffectiveConfigWithDiagnostics(cwd).config;
+}