@erichll/pi-auto-review 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.14.0 - 2026-08-28
+
+- Upgrade `/auto-review-policy-audit` from redacted statistics to an
+  evidence-driven permission-configuration optimizer. Reports now separate
+  suggested allow rules, keep-ask rules, and insufficient evidence, and emit a
+  copyable JSON fragment targeting the selected project or global
+  permission-system configuration. Suggestions remain advisory and never read
+  or modify permission configuration.
+- Discover candidates from actual audit data without built-in tool, executable,
+  Git, RTK, package-manager, or read-only command catalogs. Valid observed
+  surfaces and sanitized Bash templates—including unknown tools and write
+  operations—can qualify after the configured minimum number of successful
+  ask-path approvals. Denials, gate failures, unavailable confirmations,
+  forwarded requests, and structurally unsafe Bash variants block a suggestion.
+- Migrate the policy-audit database transactionally to schema v2. Existing
+  aggregate counts and `collecting_since` are preserved, while the new
+  `recommendations_since` boundary prevents pre-migration data from producing
+  allow suggestions. Valid custom tool names and sanitized Bash templates are
+  retained for reporting. Templates replace paths, URLs, assignments, quoted
+  values, and option values with wildcards; raw commands and non-Bash tool
+  arguments or inputs remain excluded.
+
 ## 0.13.0 - 2026-08-28
 
 - Add compatibility with `@gotgenes/pi-permission-system` 27.1 directional

package/README.md

@@ -334,11 +334,18 @@ only daily, redacted aggregates. Collection is enabled by default and retains
 180 days. It starts when this version first initializes successfully; no
 permission-system JSONL or RTK history is read or imported.
 
-Before storage, Bash values become fixed signatures such as `git:push`,
-`rtk:git:status`, `npm:test`, or `<path-command>`. Paths become only
+Before storage, Bash values become observed command templates such as
+`git status --short`, `cat *`, or `npm test * --token *`. URLs, paths,
+assignments, quoted values, and option values are replaced with `*`; safe bare
+command words remain in plaintext so the report can emit a matching rule.
+Paths used for path-surface statistics become only
 `workspace`, `temp`, `home`, `external`, `sensitive`, or `unknown`. Request IDs,
-project locations, and matched-rule patterns are HMACed. The database never
-stores raw commands, paths, URLs, credentials, tool inputs, or project names.
+project locations, and matched-rule patterns are HMACed. Syntactically valid
+custom tool names are also retained in plaintext; invalid names stay anonymous
+as `<custom-tool>`. The database never stores raw commands, raw paths,
+URLs, credentials, or non-Bash tool arguments and inputs. Because safe bare Bash
+words are retained, command templates can contain non-secret filenames or
+project-specific labels; inspect suggestions before copying them.
 
 Data lives at
 `~/.pi/agent/extensions/pi-auto-review/policy-audit.sqlite`, beside an
@@ -357,6 +364,31 @@ Run `/auto-review-policy-audit` for a durable TUI report that is not sent to the
 LLM. Options are `--days 1..retention`, `--top 1..50`, `--min-count >=1`, and
 `--scope current|all`; defaults are `30`, `20`, `5`, and `current`.
 
+In addition to the redacted statistics, the report proposes copyable
+permission-system fragments. `--scope current` targets
+`.pi/extensions/pi-permission-system/config.json`; `--scope all` targets
+`~/.pi/agent/extensions/pi-permission-system/config.json`. The extension never
+reads, edits, or rewrites either file. Merge suggested Bash patterns into the
+existing `permission.bash` map and place the narrow allow entries after broader
+matching ask entries, because permission-system uses last-match-wins.
+
+Suggestions are discovered entirely from observed audit data; there is no
+built-in tool, executable, Git action, package-manager action, or read-only
+command catalog. Every valid observed permission surface and reliably templated
+Bash command can qualify, including previously unknown tools and write
+operations. Environment prefixes, compound syntax, pipelines, redirection,
+path executables, and unreliable parsing block that Bash template. Forwarded
+requests are statistics-only because the requester's cwd is not available. A
+candidate needs at least `--min-count` successful ask-path approvals and no
+denial, gate error, unavailable confirmation, blocked structural variant, or
+forwarded-only evidence in the selected window. Existing policy/infrastructure
+allows do not count as evidence of user friction. Repeated approval is evidence
+of user preference, not independent proof that a capability is safe.
+
+Schema v2 migrates v1 aggregates transactionally. Old totals remain visible,
+`collecting_since` is preserved, and `recommendations_since` records when safe
+recommendation evidence began; pre-migration data cannot produce a suggestion.
+
 The report is an extension-owned custom entry. It is deliberately not exposed
 as an Agent tool or packaged skill, so neither a tool schema nor skill metadata
 is added to the model context. Permission changes remain a separate, explicit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erichll/pi-auto-review",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Fail-closed, model-backed approval broker for Pi: deterministically hard-denies dangerous operations, reviews dangerous boundaries with a reviewer model, and issues one-shot expiring grants that OS sandbox adapters must consume before retrying.",
   "type": "module",
   "license": "MIT",

package/src/policy-audit/classifier.ts

@@ -23,8 +23,18 @@ export type PolicyAuditCommandFeature =
   | "env_prefix"
   | "compound"
   | "pipeline"
+  | "redirection"
   | "relative_executable";
 
+export type PolicyConfigCandidate = {
+  surface: string;
+  pattern?: string;
+  action: "allow";
+  safetyClass: "observed_bash_template" | "observed_surface";
+  eligible: boolean;
+  blocker?: string;
+};
+
 export type ClassifiedPermission = {
   surface: string;
   signature: string;
@@ -32,49 +42,12 @@ export type ClassifiedPermission = {
   risk: PolicyAuditRisk;
   pathClass: PolicyAuditPathClass;
   features: readonly PolicyAuditCommandFeature[];
+  candidate?: PolicyConfigCandidate;
 };
 
-const KNOWN_SURFACES = new Set([
-  "bash",
-  "bash_escalated",
-  "read",
-  "write",
-  "edit",
-  "grep",
-  "find",
-  "ls",
-  "path",
-  "external_directory",
-  "path_read",
-  "path_write",
-  "external_directory_read",
-  "external_directory_write",
-  "skill",
-  "mcp",
-  "network",
-]);
-
+const SAFE_SURFACE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+const SAFE_COMMAND_WORD = /^[A-Za-z0-9][A-Za-z0-9+._:-]{0,63}$/;
 const SENSITIVE_PATH = /(?:^|[/\\])(?:\.ssh|\.aws|\.gnupg|\.kube|\.azure|\.npmrc|\.netrc|\.env(?:\.[^/\\]+)?|auth\.json|credentials?)(?:[/\\]|$)/i;
-const READ_ONLY_COMMANDS = new Set([
-  "cat", "find", "grep", "head", "ls", "pwd", "rg", "sed", "sort",
-  "stat", "tail", "wc", "which",
-]);
-const MUTATING_COMMANDS = new Set([
-  "chmod", "chown", "cp", "install", "ln", "mkdir", "mv", "rm", "rmdir",
-  "touch", "truncate",
-]);
-const NETWORK_COMMANDS = new Set(["curl", "dig", "host", "nc", "ping", "ssh", "wget"]);
-const SHELL_COMMANDS = new Set(["bash", "dash", "fish", "sh", "zsh"]);
-const GIT_ACTIONS = new Set([
-  "add", "branch", "checkout", "clean", "clone", "commit", "diff", "fetch",
-  "log", "merge", "pull", "push", "rebase", "remote", "reset", "restore",
-  "send-pack", "show", "status", "switch", "tag",
-]);
-const RTK_ACTIONS = new Set(["diff", "find", "grep", "ls", "read", "rg", "smart", "wc"]);
-const PACKAGE_ACTIONS = new Set([
-  "add", "build", "check", "coverage", "dev", "format", "install", "lint",
-  "publish", "start", "test", "typecheck", "uninstall", "update", "upgrade",
-]);
 
 function within(path: string, parent: string): boolean {
   const rel = relative(parent, path);
@@ -90,12 +63,8 @@ export function classifyPath(
   if (typeof value !== "string" || !value.trim()) return "unknown";
   const raw = value.trim();
   if (SENSITIVE_PATH.test(raw)) return "sensitive";
-  if (!raw.startsWith("/") && !raw.startsWith("~") && !raw.startsWith(".")) {
-    return "unknown";
-  }
-  const expanded = raw === "~" || raw.startsWith("~/")
-    ? resolve(home, raw.slice(2))
-    : resolve(cwd, raw);
+  if (!raw.startsWith("/") && !raw.startsWith("~") && !raw.startsWith(".")) return "unknown";
+  const expanded = raw === "~" || raw.startsWith("~/") ? resolve(home, raw.slice(2)) : resolve(cwd, raw);
   if (within(expanded, resolve(cwd))) return "workspace";
   if (within(expanded, resolve(temp))) return "temp";
   if (within(expanded, resolve(home))) return "home";
@@ -103,138 +72,145 @@ export function classifyPath(
 }
 
 function shellTokens(command: string): string[] {
-  return command
-    .trim()
-    .split(/\s+/u)
-    .map((token) => token.replace(/^["']|["']$/g, ""));
+  return command.trim().split(/\s+/u);
 }
 
 function executableIndex(tokens: readonly string[]): number {
   let index = 0;
   if (tokens[index] === "env") index++;
-  while (index < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=.*/.test(tokens[index])) {
-    index++;
-  }
+  while (index < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=.*/.test(tokens[index])) index++;
   return index;
 }
 
-function safeCommandName(token: string | undefined): string {
-  if (!token) return "unknown";
-  const name = token.split(/[\\/]/).at(-1)?.toLowerCase() || "unknown";
-  return /^[a-z0-9][a-z0-9+._-]{0,31}$/.test(name) ? name : "unknown";
+function safeExecutable(token: string | undefined): string | undefined {
+  if (!token || token.includes("/") || token.startsWith(".")) return undefined;
+  const unquoted = token.replace(/^["']|["']$/g, "");
+  return SAFE_COMMAND_WORD.test(unquoted) ? unquoted : undefined;
 }
 
-function knownSignature(tokens: readonly string[], index: number): string {
-  const executable = safeCommandName(tokens[index]);
-  const sub = safeCommandName(tokens[index + 1]);
-  const third = safeCommandName(tokens[index + 2]);
-  if (executable === "rtk") {
-    if (sub === "git") return `rtk:git:${GIT_ACTIONS.has(third) ? third : "other"}`;
-    return `rtk:${RTK_ACTIONS.has(sub) ? sub : "other"}`;
-  }
-  if (executable === "git") return `git:${GIT_ACTIONS.has(sub) ? sub : "other"}`;
-  if (["npm", "pnpm", "yarn", "bun"].includes(executable)) {
-    const action = sub === "run" ? third : sub;
-    return `${executable}:${PACKAGE_ACTIONS.has(action) ? action : "custom-script"}`;
-  }
-  if (READ_ONLY_COMMANDS.has(executable) || MUTATING_COMMANDS.has(executable) ||
-      NETWORK_COMMANDS.has(executable) || SHELL_COMMANDS.has(executable)) {
-    return executable;
-  }
-  if (tokens[index]?.includes("/") || tokens[index]?.startsWith(".")) {
-    return "<path-command>";
-  }
-  return "<other-command>";
+function reliableShellText(command: string): boolean {
+  let quote = "";
+  let escaped = false;
+  for (const character of command) {
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (character === "\\" && quote !== "'") {
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      if (character === quote) quote = "";
+    } else if (character === "'" || character === '"') {
+      quote = character;
+    }
+  }
+  return !quote && !escaped;
 }
 
-function commandRisk(signature: string, executable: string, command: string): PolicyAuditRisk {
-  if (/&&|\|\||;|\n|`|\$\(|(^|[^|])\|([^|]|$)/.test(command)) return "arbitrary_shell";
-  if (["git:push", "git:send-pack", "rtk:git:push", "rtk:git:send-pack"].includes(signature)) return "network_mutation";
-  if (/^(?:npm|pnpm|yarn|bun):(install|publish|add|upgrade|update)$/.test(signature)) {
-    return signature.endsWith(":publish") ? "network_mutation" : "project_code_execution";
-  }
-  if (/^(?:npm|pnpm|yarn|bun):/.test(signature)) return "project_code_execution";
-  if (NETWORK_COMMANDS.has(executable)) {
-    return /(?:^|\s)(?:--upload-file|-T|-X\s*(?:POST|PUT|PATCH|DELETE)|--data|-d)(?:\s|=|$)/i.test(command)
-      ? "network_mutation"
-      : "network";
-  }
-  if (MUTATING_COMMANDS.has(executable) || ["git:add", "git:commit", "git:reset", "git:clean", "git:checkout", "git:restore", "git:rebase", "rtk:git:add", "rtk:git:commit"].includes(signature)) {
-    return "workspace_mutation";
-  }
-  if (READ_ONLY_COMMANDS.has(executable) || /^(?:rtk:)?git:(?:status|diff|log|show|branch)$/.test(signature)) {
-    return "read_only";
-  }
-  if (SHELL_COMMANDS.has(executable) || signature === "<path-command>") {
-    return "arbitrary_shell";
-  }
-  return "unknown";
+function sanitizedTemplateToken(token: string, followsOption: boolean): string {
+  if (!token || /^['"]/.test(token) || /[/\\@]/.test(token) || /:\/\//.test(token)) return "*";
+  if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(token)) return "*";
+  if (token.startsWith("--") && token.includes("=")) {
+    const name = token.slice(0, token.indexOf("="));
+    return /^--[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name) ? `${name}=*` : "*";
+  }
+  if (/^--?[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(token)) return token;
+  if (followsOption) return "*";
+  return SAFE_COMMAND_WORD.test(token) ? token : "*";
+}
+
+function observedBashTemplate(tokens: readonly string[], index: number): string | undefined {
+  const executable = safeExecutable(tokens[index]);
+  if (!executable) return undefined;
+  const template = [executable];
+  let followsOption = false;
+  for (const rawToken of tokens.slice(index + 1)) {
+    const token = sanitizedTemplateToken(rawToken, followsOption);
+    if (template.at(-1) !== "*" || token !== "*") template.push(token);
+    followsOption = /^--?[A-Za-z0-9]/.test(rawToken) && !rawToken.includes("=");
+  }
+  return template.join(" ");
 }
 
 export function classifyBash(command: unknown, cwd: string): ClassifiedPermission {
   if (typeof command !== "string" || !command.trim()) {
-    return { surface: "bash", signature: "<other-command>", bashCategory: "unknown", risk: "unknown", pathClass: "unknown", features: [] };
+    return { surface: "bash", signature: "<command>", bashCategory: "unknown", risk: "unknown", pathClass: "unknown", features: [] };
   }
   const tokens = shellTokens(command);
   const index = executableIndex(tokens);
-  const executable = safeCommandName(tokens[index]);
-  const signature = knownSignature(tokens, index);
   const features: PolicyAuditCommandFeature[] = [];
   if (index > 0) features.push("env_prefix");
   if (/&&|\|\||;|\n|`|\$\(/.test(command)) features.push("compound");
   if (/(^|[^|])\|([^|]|$)/.test(command)) features.push("pipeline");
+  if (/[<>]/.test(command)) features.push("redirection");
   if (tokens[index]?.includes("/") || tokens[index]?.startsWith(".")) features.push("relative_executable");
-  const bashCategory = /^(?:rtk:)?git:/.test(signature)
-    ? "version_control"
-    : /^(?:npm|pnpm|yarn|bun):/.test(signature)
-      ? "package_script"
-      : NETWORK_COMMANDS.has(executable)
-        ? "network"
-        : READ_ONLY_COMMANDS.has(executable) || MUTATING_COMMANDS.has(executable)
-          ? "filesystem"
-          : "shell";
+  const uniqueFeatures = [...new Set(features)].sort();
+  const structuralBoundary = command.search(/&&|\|\||[;|<>\n]|`|\$\(/);
+  const templateTokens = shellTokens(structuralBoundary >= 0 ? command.slice(0, structuralBoundary) : command);
+  const template = observedBashTemplate(templateTokens, executableIndex(templateTokens));
+  let blocker: string | undefined;
+  if (!reliableShellText(command) || !template) blocker = "command could not be templated reliably";
+  else if (uniqueFeatures.length > 0) blocker = `unsafe command feature: ${uniqueFeatures.join(", ")}`;
+  const candidate: PolicyConfigCandidate | undefined = template ? {
+    surface: "bash",
+    pattern: template,
+    action: "allow",
+    safetyClass: "observed_bash_template",
+    eligible: blocker === undefined,
+    ...(blocker ? { blocker } : {}),
+  } : undefined;
   const pathToken = tokens.slice(index + 1)
-    .map((token) => token.includes("=") ? token.slice(token.indexOf("=") + 1) : token.replace(/^@/, ""))
+    .map((token) => token.replace(/^@/, ""))
     .find((token) => token.startsWith("/") || token.startsWith("./") || token.startsWith("../") || token.startsWith("~/"));
   return {
     surface: "bash",
-    signature,
-    bashCategory,
-    risk: commandRisk(signature, executable, command),
+    signature: template ?? "<command>",
+    bashCategory: uniqueFeatures.length === 0 ? "simple" : "structured",
+    risk: uniqueFeatures.includes("compound") || uniqueFeatures.includes("pipeline")
+      ? "arbitrary_shell"
+      : uniqueFeatures.includes("redirection") ? "workspace_mutation" : "unknown",
     pathClass: classifyPath(pathToken, cwd),
-    features: [...new Set(features)].sort(),
+    features: uniqueFeatures,
+    ...(candidate ? { candidate } : {}),
   };
 }
 
 export function classifyPermission(surfaceValue: unknown, value: unknown, cwd: string): ClassifiedPermission {
-  const rawSurface = typeof surfaceValue === "string" ? surfaceValue.trim().toLowerCase() : "";
-  if (rawSurface === "bash" || rawSurface === "bash_escalated") {
+  const suppliedSurface = typeof surfaceValue === "string" ? surfaceValue.trim() : "";
+  const normalizedSurface = suppliedSurface.toLowerCase();
+  if (normalizedSurface === "bash" || normalizedSurface === "bash_escalated") {
     const classified = classifyBash(value, cwd);
-    return { ...classified, surface: rawSurface || "bash" };
-  }
-  const surface = KNOWN_SURFACES.has(rawSurface) ? rawSurface : "custom_tool";
-  const pathSurface = pathSurfaceInfo(surface);
-  if (pathSurface || ["read", "write", "edit"].includes(surface)) {
-    const pathClass = classifyPath(value, cwd);
-    const risk = pathSurface?.effect === "read" || surface === "read"
-      ? "read_only"
-      : pathSurface?.effect === "write" || surface === "write" || surface === "edit"
-        ? "workspace_mutation"
-        : "unknown";
-    return { surface, signature: `<${surface}>`, bashCategory: "not_bash", risk, pathClass, features: [] };
-  }
-  if (["grep", "find", "ls"].includes(surface)) {
-    return { surface, signature: `<${surface}>`, bashCategory: "not_bash", risk: "read_only", pathClass: "unknown", features: [] };
-  }
-  if (surface === "network") {
-    return { surface, signature: "<network>", bashCategory: "not_bash", risk: "network", pathClass: "unknown", features: [] };
+    if (normalizedSurface === "bash_escalated") {
+      const { candidate: _candidate, ...statisticsOnly } = classified;
+      return { ...statisticsOnly, surface: normalizedSurface };
+    }
+    return classified;
   }
+
+  const validSurface = SAFE_SURFACE.test(suppliedSurface) ? suppliedSurface : undefined;
+  const pathSurface = pathSurfaceInfo(normalizedSurface);
+  const pathLike = pathSurface !== undefined || normalizedSurface === "read" || normalizedSurface === "write" || normalizedSurface === "edit";
+  const pathClass = pathLike ? classifyPath(value, cwd) : "unknown";
+  const risk = pathSurface?.effect === "read" || normalizedSurface === "read"
+    ? "read_only"
+    : pathSurface?.effect === "write" || normalizedSurface === "write" || normalizedSurface === "edit"
+      ? "workspace_mutation"
+      : "unknown";
+  const candidate: PolicyConfigCandidate | undefined = validSurface ? {
+    surface: validSurface,
+    action: "allow",
+    safetyClass: "observed_surface",
+    eligible: true,
+  } : undefined;
   return {
-    surface,
-    signature: surface === "custom_tool" ? "<custom-tool>" : `<${surface}>`,
+    surface: validSurface ?? "custom_tool",
+    signature: validSurface ?? "<custom-tool>",
     bashCategory: "not_bash",
-    risk: "unknown",
-    pathClass: "unknown",
+    risk,
+    pathClass,
     features: [],
+    ...(candidate ? { candidate } : {}),
   };
 }

package/src/policy-audit/report.ts

@@ -1,20 +1,33 @@
 import type { PolicyAuditAggregateRow, PolicyAuditQueryResult } from "./store.ts";
 
-export const POLICY_AUDIT_REPORT_VERSION = 1 as const;
+export const POLICY_AUDIT_REPORT_VERSION = 2 as const;
 
 export type PolicyAuditReportItem = { name: string; count: number; denied: number; denialRate: number };
+export type SuggestedAllowRule = {
+  surface: string; pattern?: string; action: "allow"; safetyClass: string;
+  successfulEvidence: number; denied: 0; rationale: string;
+};
+export type PolicyRecommendationItem = {
+  surface: string; pattern?: string; successfulEvidence: number; denied: number; reason: string;
+};
 
 export type PolicyAuditReport = {
   version: typeof POLICY_AUDIT_REPORT_VERSION;
   scope: "current" | "all";
   days: number;
   collectingSince: string;
+  recommendationsSince: string;
   fromDay: string;
   throughDay: string;
   total: number;
   allowed: number;
   denied: number;
   denialRate: number;
+  configTarget: string;
+  configFragment: string;
+  suggestedAllowRules: SuggestedAllowRule[];
+  keepAskRules: PolicyRecommendationItem[];
+  insufficientEvidence: PolicyRecommendationItem[];
   surfaces: PolicyAuditReportItem[];
   tools: PolicyAuditReportItem[];
   bashCategories: PolicyAuditReportItem[];
@@ -26,21 +39,21 @@ export type PolicyAuditReport = {
 };
 
 export type PolicyAuditReportOptions = {
-  scope: "current" | "all";
-  days: number;
-  top: number;
-  minCount: number;
+  scope: "current" | "all"; days: number; top: number; minCount: number;
 };
 
+const SUCCESS_RESOLUTIONS = new Set([
+  "user_approved", "user_approved_for_session", "session_approved", "auto_approved",
+]);
+const FAILURE_RESOLUTIONS = new Set(["confirmation_unavailable", "gate_error"]);
+
 function rate(denied: number, total: number): number {
   return total === 0 ? 0 : Math.round((denied / total) * 10_000) / 100;
 }
 
 function rank(
-  rows: readonly PolicyAuditAggregateRow[],
-  key: (row: PolicyAuditAggregateRow) => string,
-  top: number,
-  minCount: number,
+  rows: readonly PolicyAuditAggregateRow[], key: (row: PolicyAuditAggregateRow) => string,
+  top: number, minCount: number,
 ): PolicyAuditReportItem[] {
   const grouped = new Map<string, { count: number; denied: number }>();
   for (const row of rows) {
@@ -61,16 +74,128 @@ function reviewed(row: PolicyAuditAggregateRow): boolean {
   return ["user_approved", "user_approved_for_session", "user_denied", "auto_approved"].includes(row.resolution);
 }
 
+type CandidateGroup = {
+  surface: string; pattern?: string; safetyClass: string; successfulEvidence: number;
+  denied: number; blockers: Set<string>;
+};
+
+function recommendationGroups(rows: readonly PolicyAuditAggregateRow[]): CandidateGroup[] {
+  const groups = new Map<string, CandidateGroup>();
+  for (const row of rows) {
+    if (!row.candidateSurface) continue;
+    // Forwarded evidence is reported separately: it cannot prove either the
+    // current project's cwd or a safe global scope, and must not poison local
+    // evidence for the same observed candidate.
+    const key = `${row.candidateSurface}\0${row.candidatePattern}\0${row.forwarded ? "forwarded" : "local"}`;
+    const group = groups.get(key) ?? {
+      surface: row.candidateSurface,
+      ...(row.candidatePattern ? { pattern: row.candidatePattern } : {}),
+      safetyClass: row.candidateSafetyClass,
+      successfulEvidence: 0,
+      denied: 0,
+      blockers: new Set<string>(),
+    };
+    if (row.result === "allow" && SUCCESS_RESOLUTIONS.has(row.resolution)) group.successfulEvidence += row.count;
+    if (row.result === "deny") group.denied += row.count;
+    if (row.forwarded) group.blockers.add("forwarded requests lack the requesting cwd");
+    if (!row.candidateEligible) group.blockers.add(row.candidateBlocker || "unsafe or unparseable variant observed");
+    if (FAILURE_RESOLUTIONS.has(row.resolution)) group.blockers.add(`authorization failure: ${row.resolution}`);
+    groups.set(key, group);
+  }
+  return [...groups.values()].sort((a, b) =>
+    b.successfulEvidence - a.successfulEvidence || a.surface.localeCompare(b.surface) ||
+      (a.pattern ?? "").localeCompare(b.pattern ?? "")
+  );
+}
+
+function displayRule(item: { surface: string; pattern?: string }): string {
+  return item.pattern ? `${item.surface}[${JSON.stringify(item.pattern)}]` : item.surface;
+}
+
+function buildConfigFragment(rules: readonly SuggestedAllowRule[]): string {
+  const bash: Record<string, "allow"> = {};
+  const permission: Record<string, "allow" | Record<string, "allow">> = {};
+  for (const rule of rules) {
+    if (rule.surface === "bash" && rule.pattern) bash[rule.pattern] = "allow";
+  }
+  if (Object.keys(bash).length > 0) permission.bash = bash;
+  for (const rule of rules) {
+    if (rule.surface !== "bash") permission[rule.surface] = "allow";
+  }
+  return JSON.stringify({ permission }, null, 2);
+}
+
+function genericKeepAskRules(
+  rows: readonly PolicyAuditAggregateRow[], minCount: number, top: number,
+): PolicyRecommendationItem[] {
+  const grouped = new Map<string, { surface: string; risk: string; total: number; successful: number; denied: number }>();
+  for (const row of rows) {
+    if (row.candidateSurface) continue;
+    const surface = row.surface === "custom_tool" ? row.signature : `${row.surface}:${row.signature}`;
+    const key = `${surface}\0${row.risk}`;
+    const group = grouped.get(key) ?? { surface, risk: row.risk, total: 0, successful: 0, denied: 0 };
+    group.total += row.count;
+    if (row.result === "allow" && SUCCESS_RESOLUTIONS.has(row.resolution)) group.successful += row.count;
+    if (row.result === "deny") group.denied += row.count;
+    grouped.set(key, group);
+  }
+  return [...grouped.values()]
+    .filter((group) => group.total >= minCount)
+    .sort((a, b) => b.total - a.total || a.surface.localeCompare(b.surface))
+    .slice(0, top)
+    .map((group) => ({
+      surface: group.surface,
+      successfulEvidence: group.successful,
+      denied: group.denied,
+      reason: `${group.total} observed but no valid copyable permission rule could be derived (${group.risk})`,
+    }));
+}
+
 export function buildPolicyAuditReport(
-  result: PolicyAuditQueryResult,
-  options: PolicyAuditReportOptions,
+  result: PolicyAuditQueryResult, options: PolicyAuditReportOptions,
 ): PolicyAuditReport {
   const total = result.rows.reduce((sum, row) => sum + row.count, 0);
   const denied = result.rows.filter((row) => row.result === "deny").reduce((sum, row) => sum + row.count, 0);
   const lowRisk = result.rows.filter((row) => row.risk === "read_only" && reviewed(row));
-  const keepAsk = result.rows.filter((row) =>
-    ["workspace_mutation", "project_code_execution", "network", "network_mutation", "arbitrary_shell", "unknown"].includes(row.risk)
-  );
+  const keepAsk = result.rows.filter((row) => !row.candidateSurface);
+  const groups = recommendationGroups(result.rows);
+  const suggestedAllowRules: SuggestedAllowRule[] = groups
+    .filter((group) => group.successfulEvidence >= options.minCount && group.denied === 0 && group.blockers.size === 0)
+    .slice(0, options.top)
+    .map((group) => ({
+      surface: group.surface,
+      ...(group.pattern ? { pattern: group.pattern } : {}),
+      action: "allow",
+      safetyClass: group.safetyClass,
+      successfulEvidence: group.successfulEvidence,
+      denied: 0,
+      rationale: group.safetyClass === "observed_bash_template"
+        ? "observed Bash template; zero denials, failures, and structurally unsafe variants"
+        : "observed permission surface; zero denials and authorization failures",
+    }));
+  const candidateKeepAskRules: PolicyRecommendationItem[] = groups
+    .filter((group) => group.denied > 0 || group.blockers.size > 0)
+    .map((group) => ({
+      surface: group.surface,
+      ...(group.pattern ? { pattern: group.pattern } : {}),
+      successfulEvidence: group.successfulEvidence,
+      denied: group.denied,
+      reason: [group.denied ? `${group.denied} denied` : "", ...group.blockers].filter(Boolean).join("; "),
+    }));
+  const keepAskRules = [
+    ...candidateKeepAskRules,
+    ...genericKeepAskRules(keepAsk, options.minCount, options.top),
+  ].slice(0, options.top);
+  const insufficientEvidence: PolicyRecommendationItem[] = groups
+    .filter((group) => group.successfulEvidence > 0 && group.successfulEvidence < options.minCount && group.denied === 0 && group.blockers.size === 0)
+    .slice(0, options.top)
+    .map((group) => ({
+      surface: group.surface,
+      ...(group.pattern ? { pattern: group.pattern } : {}),
+      successfulEvidence: group.successfulEvidence,
+      denied: 0,
+      reason: `needs ${options.minCount - group.successfulEvidence} more successful ask-path sample(s)`,
+    }));
   const fingerprintCounts = new Map<string, number>();
   for (const row of result.rows) {
     if (row.ruleFingerprint === "none") continue;
@@ -78,8 +203,10 @@ export function buildPolicyAuditReport(
   }
   const warnings = [
     "Counts begin at first successful enablement; no historical logs are imported.",
+    "Suggestions are evidence-based decision aids and never modify permission configuration.",
+    "Migrated pre-v2 counts remain in statistics but cannot contribute recommendation evidence.",
     "Rule fingerprints are anonymous hit indicators, not proof that unlisted rules are unused.",
-    "High frequency alone must not be used to relax mutation, network, arbitrary-shell, unknown, or custom-tool policy.",
+    "A suggestion reflects repeated approval history, not an independent proof that the capability is safe.",
   ];
   if (total === 0) warnings.unshift("No matching permission decisions were collected for this window and scope.");
   return {
@@ -87,12 +214,20 @@ export function buildPolicyAuditReport(
     scope: options.scope,
     days: options.days,
     collectingSince: result.collectingSince,
+    recommendationsSince: result.recommendationsSince,
     fromDay: result.fromDay,
     throughDay: result.throughDay,
     total,
     allowed: total - denied,
     denied,
     denialRate: rate(denied, total),
+    configTarget: options.scope === "current"
+      ? ".pi/extensions/pi-permission-system/config.json"
+      : "~/.pi/agent/extensions/pi-permission-system/config.json",
+    configFragment: buildConfigFragment(suggestedAllowRules),
+    suggestedAllowRules,
+    keepAskRules,
+    insufficientEvidence,
     surfaces: rank(result.rows, (row) => row.surface, options.top, options.minCount),
     tools: rank(result.rows, (row) => row.signature, options.top, options.minCount),
     bashCategories: rank(result.rows.filter((row) => row.bashCategory !== "not_bash"), (row) => row.bashCategory, options.top, options.minCount),
@@ -114,26 +249,38 @@ function itemLines(items: readonly PolicyAuditReportItem[]): string[] {
     : items.map((item) => `- ${item.name}: ${item.count} (${item.denied} denied, ${item.denialRate}% denial)`);
 }
 
+function recommendationLines(items: readonly PolicyRecommendationItem[]): string[] {
+  return items.length === 0
+    ? ["- None."]
+    : items.map((item) => `- ${displayRule(item)}: ${item.successfulEvidence} successful, ${item.denied} denied — ${item.reason}`);
+}
+
 export function renderPolicyAuditMarkdown(report: PolicyAuditReport): string {
+  const suggested = report.suggestedAllowRules.length === 0
+    ? ["- None."]
+    : report.suggestedAllowRules.map((item) =>
+      `- ${displayRule(item)} = allow: ${item.successfulEvidence} successful ask-path samples, zero denials — ${item.rationale}`
+    );
   const fingerprints = report.ruleFingerprints.length === 0
     ? ["- None above the minimum count."]
     : report.ruleFingerprints.map((item) => `- ${item.fingerprint}: ${item.count}`);
   return [
-    "# Permission policy audit",
-    "",
-    `Scope: **${report.scope}** · Window: **${report.fromDay}–${report.throughDay}** · Collecting since: **${report.collectingSince}**`,
-    `Decisions: **${report.total}** · Allowed: **${report.allowed}** · Denied: **${report.denied}** · Denial rate: **${report.denialRate}%**`,
-    "",
+    "# Permission policy audit", "",
+    `Scope: **${report.scope}** · Window: **${report.fromDay}–${report.throughDay}** · Collecting since: **${report.collectingSince}** · Recommendations since: **${report.recommendationsSince}**`,
+    `Decisions: **${report.total}** · Allowed: **${report.allowed}** · Denied: **${report.denied}** · Denial rate: **${report.denialRate}%**`, "",
+    "## Suggested allow rules", "", ...suggested, "",
+    "## Copyable permission config", "", `Target: \`${report.configTarget}\``, "",
+    "```json", report.configFragment, "```", "",
+    "Merge Bash patterns into the existing `permission.bash` map at this same scope. Permission-system uses last-match-wins, so place these narrow allow patterns after any broader ask rule that would match them.", "",
+    "## Keep ask", "",
+    "Denied candidates, authorization failures, structurally unsafe Bash variants, forwarded requests, and values without a valid rule remain ask-by-default.",
+    ...recommendationLines(report.keepAskRules), ...itemLines(report.keepAskRecommendations), "",
+    "## Insufficient evidence", "", ...recommendationLines(report.insufficientEvidence), "",
     "## Surface hotspots", "", ...itemLines(report.surfaces), "",
     "## Tool and command signatures", "", ...itemLines(report.tools), "",
     "## Bash semantic categories", "", ...itemLines(report.bashCategories), "",
     "## Approval sources", "", ...itemLines(report.approvalSources), "",
-    "## Low-risk review candidates", "",
-    "These read-only requests were still reviewed; inspect them before considering a narrower allow rule.",
-    ...itemLines(report.lowRiskReviewCandidates), "",
-    "## Keep-ask recommendations", "",
-    "These mutation, execution, network, shell, or unknown requests should remain ask-by-default.",
-    ...itemLines(report.keepAskRecommendations), "",
+    "## Low-risk review candidates", "", ...itemLines(report.lowRiskReviewCandidates), "",
     "## Anonymous rule-hit fingerprints", "", ...fingerprints, "",
     "## Warnings", "", ...report.warnings.map((warning) => `- ${warning}`),
   ].join("\n");

package/src/policy-audit/store.ts

@@ -12,7 +12,7 @@ import {
 import { dirname, join, resolve } from "node:path";
 import type { ClassifiedPermission } from "./classifier.ts";
 
-export const POLICY_AUDIT_SCHEMA_VERSION = 1;
+export const POLICY_AUDIT_SCHEMA_VERSION = 2;
 export const POLICY_AUDIT_DATABASE_NAME = "policy-audit.sqlite";
 export const POLICY_AUDIT_KEY_NAME = "policy-audit.key";
 
@@ -65,11 +65,17 @@ export type PolicyAuditAggregateRow = {
   forwarded: boolean;
   features: string;
   ruleFingerprint: string;
+  candidateSurface: string;
+  candidatePattern: string;
+  candidateSafetyClass: string;
+  candidateEligible: boolean;
+  candidateBlocker: string;
   count: number;
 };
 
 export type PolicyAuditQueryResult = {
   collectingSince: string;
+  recommendationsSince: string;
   fromDay: string;
   throughDay: string;
   rows: PolicyAuditAggregateRow[];
@@ -149,6 +155,22 @@ export class PolicyAuditStore {
         request_hash TEXT PRIMARY KEY,
         seen_day TEXT NOT NULL
       ) STRICT;
+    `);
+    const version = this.db.prepare("SELECT value FROM meta WHERE key='schema_version'").get()?.value;
+    const now = this.now().toISOString();
+    if (version !== undefined && version !== "1" && version !== String(POLICY_AUDIT_SCHEMA_VERSION)) {
+      throw new Error("unsupported policy audit schema version");
+    }
+    if (version === "1") this.migrateV1(now);
+    else this.createV2Table();
+    this.db.prepare("INSERT OR IGNORE INTO meta(key,value) VALUES('schema_version',?)").run(String(POLICY_AUDIT_SCHEMA_VERSION));
+    this.db.prepare("INSERT OR IGNORE INTO meta(key,value) VALUES('collecting_since',?)").run(now);
+    this.db.prepare("INSERT OR IGNORE INTO meta(key,value) VALUES('recommendations_since',?)").run(now);
+    this.secureSidecars();
+  }
+
+  private createV2Table(): void {
+    this.db.exec(`
       CREATE TABLE IF NOT EXISTS daily_permission_stats (
         day TEXT NOT NULL,
         project_hash TEXT NOT NULL,
@@ -163,19 +185,45 @@ export class PolicyAuditStore {
         forwarded INTEGER NOT NULL,
         features TEXT NOT NULL,
         rule_fingerprint TEXT NOT NULL,
+        candidate_surface TEXT NOT NULL,
+        candidate_pattern TEXT NOT NULL,
+        candidate_safety_class TEXT NOT NULL,
+        candidate_eligible INTEGER NOT NULL,
+        candidate_blocker TEXT NOT NULL,
         count INTEGER NOT NULL,
-        PRIMARY KEY (day, project_hash, surface, signature, bash_category, risk, path_class, result, resolution, origin, forwarded, features, rule_fingerprint)
+        PRIMARY KEY (day, project_hash, surface, signature, bash_category, risk, path_class, result, resolution, origin, forwarded, features, rule_fingerprint, candidate_surface, candidate_pattern, candidate_safety_class, candidate_eligible, candidate_blocker)
       ) STRICT;
       CREATE INDEX IF NOT EXISTS daily_permission_stats_project_day ON daily_permission_stats(project_hash, day);
     `);
-    const version = this.db.prepare("SELECT value FROM meta WHERE key='schema_version'").get()?.value;
-    if (version !== undefined && version !== String(POLICY_AUDIT_SCHEMA_VERSION)) {
-      throw new Error("unsupported policy audit schema version");
+  }
+
+  private migrateV1(now: string): void {
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      this.db.exec(`
+        CREATE TABLE daily_permission_stats_v2 (
+          day TEXT NOT NULL, project_hash TEXT NOT NULL, surface TEXT NOT NULL, signature TEXT NOT NULL,
+          bash_category TEXT NOT NULL, risk TEXT NOT NULL, path_class TEXT NOT NULL, result TEXT NOT NULL,
+          resolution TEXT NOT NULL, origin TEXT NOT NULL, forwarded INTEGER NOT NULL, features TEXT NOT NULL,
+          rule_fingerprint TEXT NOT NULL, candidate_surface TEXT NOT NULL, candidate_pattern TEXT NOT NULL,
+          candidate_safety_class TEXT NOT NULL, candidate_eligible INTEGER NOT NULL, candidate_blocker TEXT NOT NULL,
+          count INTEGER NOT NULL,
+          PRIMARY KEY (day, project_hash, surface, signature, bash_category, risk, path_class, result, resolution, origin, forwarded, features, rule_fingerprint, candidate_surface, candidate_pattern, candidate_safety_class, candidate_eligible, candidate_blocker)
+        ) STRICT;
+        INSERT INTO daily_permission_stats_v2
+          SELECT day,project_hash,surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint,'','','',0,'',count
+          FROM daily_permission_stats;
+        DROP TABLE daily_permission_stats;
+        ALTER TABLE daily_permission_stats_v2 RENAME TO daily_permission_stats;
+        CREATE INDEX daily_permission_stats_project_day ON daily_permission_stats(project_hash, day);
+      `);
+      this.db.prepare("UPDATE meta SET value=? WHERE key='schema_version'").run(String(POLICY_AUDIT_SCHEMA_VERSION));
+      this.db.prepare("INSERT OR REPLACE INTO meta(key,value) VALUES('recommendations_since',?)").run(now);
+      this.db.exec("COMMIT");
+    } catch (error) {
+      try { this.db.exec("ROLLBACK"); } catch { /* preserve migration error */ }
+      throw error;
     }
-    const now = this.now().toISOString();
-    this.db.prepare("INSERT OR IGNORE INTO meta(key,value) VALUES('schema_version',?)").run(String(POLICY_AUDIT_SCHEMA_VERSION));
-    this.db.prepare("INSERT OR IGNORE INTO meta(key,value) VALUES('collecting_since',?)").run(now);
-    this.secureSidecars();
   }
 
   private hash(kind: string, value: string): string {
@@ -219,8 +267,9 @@ export class PolicyAuditStore {
         }
         this.db.prepare(`
           INSERT INTO daily_permission_stats(
-            day,project_hash,surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint,count
-          ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,1)
+            day,project_hash,surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint,
+            candidate_surface,candidate_pattern,candidate_safety_class,candidate_eligible,candidate_blocker,count
+          ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,1)
           ON CONFLICT DO UPDATE SET count=count+1
         `).run(
           day,
@@ -236,6 +285,11 @@ export class PolicyAuditStore {
           event.forwarded ? 1 : 0,
           event.features.join(","),
           this.ruleFingerprint(event.matchedPattern),
+          event.candidate?.surface ?? "",
+          event.candidate?.pattern ?? "",
+          event.candidate?.safetyClass ?? "",
+          event.candidate?.eligible ? 1 : 0,
+          event.candidate?.blocker ?? "",
         );
         this.db.exec("COMMIT");
         this.secureSidecars();
@@ -264,18 +318,24 @@ export class PolicyAuditStore {
       const params: unknown[] = [fromDay];
       if (input.scope === "current") params.push(this.projectHash(input.projectPath));
       const rows = this.db.prepare(`
-        SELECT surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint,SUM(count) AS count
+        SELECT surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint,
+          candidate_surface,candidate_pattern,candidate_safety_class,candidate_eligible,candidate_blocker,SUM(count) AS count
         FROM daily_permission_stats
         WHERE day >= ? ${projectClause}
-        GROUP BY surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint
+        GROUP BY surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint,
+          candidate_surface,candidate_pattern,candidate_safety_class,candidate_eligible,candidate_blocker
       `).all(...params).map((row) => ({
         surface: String(row.surface), signature: String(row.signature), bashCategory: String(row.bash_category),
         risk: String(row.risk), pathClass: String(row.path_class), result: String(row.result),
         resolution: String(row.resolution), origin: String(row.origin), forwarded: Number(row.forwarded) === 1,
         features: String(row.features), ruleFingerprint: String(row.rule_fingerprint), count: Number(row.count),
+        candidateSurface: String(row.candidate_surface), candidatePattern: String(row.candidate_pattern),
+        candidateSafetyClass: String(row.candidate_safety_class), candidateEligible: Number(row.candidate_eligible) === 1,
+        candidateBlocker: String(row.candidate_blocker),
       }));
       const collectingSince = String(this.db.prepare("SELECT value FROM meta WHERE key='collecting_since'").get()?.value ?? "unknown");
-      return { collectingSince, fromDay, throughDay, rows };
+      const recommendationsSince = String(this.db.prepare("SELECT value FROM meta WHERE key='recommendations_since'").get()?.value ?? "unknown");
+      return { collectingSince, recommendationsSince, fromDay, throughDay, rows };
     });
   }