@hank-warren/pi-auto-permissions 0.12.0 → 0.13.0

package/default-rules.ts

@@ -0,0 +1,265 @@
+import type { Gate } from "./gates.js";
+
+/**
+ * The built-in ruleset.
+ *
+ * Active when the config file has no `rules` key at all, and spliceable into
+ * an authored `rules` array with the literal string `"$defaults"` (see
+ * `expandRules` in config.ts). An authored array without the token fully
+ * replaces this list; an explicit `[]` gates nothing.
+ *
+ * Content is derived from Claude Code auto mode's blocked-by-default list
+ * (the mechanically matchable rows), adapted to this extension's levels:
+ *
+ * - `deny` — the analogue of CC's deterministic pre-classifier circuit
+ *   breaker: oversight bypasses and critical-path destruction that no agent
+ *   session should ever perform. Not overridable, not bypassed by trusted
+ *   groups, never sent to the guardian.
+ * - `guarded` — operations where a human judgment call is legitimate; the
+ *   guardian reviews them against the conversation evidence.
+ *
+ * Design constraints, enforced by test/default-rules.test.ts:
+ * - A normal dev session (build, test, commit, push a feature branch) must
+ *   trigger zero gates. Plain `git commit` and `git push` are deliberately
+ *   not gated; only force pushes, history rewrites, deploy-branch pushes and
+ *   remote reconfiguration are.
+ * - Every rule ships with commands that must match and near-misses that must
+ *   not. Rules match raw shell text, so quoting and variable indirection can
+ *   evade them — the guardian and the system prompt are the semantic layer;
+ *   these rules are the deterministic prefilter.
+ */
+
+/** Shell-write prefix: redirection or a write verb, then no command separator. */
+const WRITE = String.raw`(?:>>?|\btee\b|\bsed\s+-i\b|\bcp\b|\bmv\b)[^|&;]*`;
+
+const OVERSIGHT_RULES: readonly Gate[] = [
+  {
+    pattern: /--dangerously-skip-permissions\b|--dangerously-bypass-approvals-and-sandbox\b|--yes-always\b|\b(?:pi|claude|codex)\b[^|&;]*--no-sandbox\b/i,
+    level: "deny",
+    group: "oversight",
+    label: "Agent oversight bypass",
+    message: "Launching an agent with approvals or sandboxing disabled removes the oversight this session runs under. Run the agent with its normal approval flow instead.",
+  },
+  {
+    pattern: /\btmux\s+send-keys\b(?![^|&;]*\s-t)|\btmux\s+send-keys\b[^|&;]*\s-t[= ]?\s*['"]?\$\{?TMUX_PANE/i,
+    level: "deny",
+    group: "oversight",
+    label: "Self-driving keystrokes",
+    message: "Sending keystrokes to this agent's own terminal pane drives its own interface, which amounts to changing its own permissions or oversight. Target an explicit other pane with -t if you are automating a different process.",
+  },
+  {
+    pattern: /(?:>>?|\btee\b|\bsed\s+-i\b|\bcp\b|\bmv\b|\brm\b|\btruncate\b)[^|&;]*(?:\$\{?PI_CODING_AGENT_DIR\}?|\.pi\/agent)\/sessions\b/i,
+    level: "deny",
+    group: "oversight",
+    label: "Session transcript write",
+    message: "Session transcripts are the audit record of agent behavior; writing to them from a session is never allowed. Reading them is fine.",
+  },
+];
+
+const DESTRUCTIVE_RULES: readonly Gate[] = [
+  {
+    pattern: /\b(?:rm|rmdir)\b[^|&;]*\s['"]?\/[^/\s'"]*\/?['"]?(?=\s|$|[;|&])/i,
+    level: "deny",
+    group: "destructive",
+    label: "Delete of a critical path",
+    message: "Deleting the filesystem root or a top-level directory is irreversible system destruction. Name the specific deeper path you actually mean.",
+  },
+  {
+    pattern: /\b(?:rm|rmdir)\b[^|&;]*\s['"]?(?:~|\$\{?HOME\}?)\/?['"]?(?=\s|$|[;|&])/i,
+    level: "deny",
+    group: "destructive",
+    label: "Delete of the home directory",
+    message: "Deleting the home directory is irreversible. Name the specific path under it you actually mean.",
+  },
+  {
+    pattern: /\b(?:rm|rmdir)\b[^|&;]*\s['"]?\.\.?\/?['"]?(?=\s|$|[;|&])/i,
+    level: "deny",
+    group: "destructive",
+    label: "Delete of the working directory or a parent",
+    message: "Deleting the current directory or a parent destroys the workspace this session runs in. Name the specific entry inside it you actually mean.",
+  },
+  {
+    pattern: /\brm\b[^|&;]*\s['"]?\$\{?[A-Za-z_]\w*\}?['"]?\/\*/i,
+    level: "deny",
+    group: "destructive",
+    label: "Glob delete under a shell variable",
+    message: "A glob rooted at a shell variable becomes a root delete when the variable is empty or unset. Re-run the delete with the resolved literal path written into the command.",
+  },
+  {
+    pattern: /\brm\b[^|&;]*\s(?:['"]?\/tmp\/|['"]?\$\{?TMPDIR\}?[/'"]?)[^|&;]*\*/i,
+    level: "guarded",
+    group: "destructive",
+    label: "Wildcard delete in shared temp",
+  },
+  {
+    pattern: /\bfind\b[^|&;]*\s(?:-delete\b|-exec\s+rm\b)/i,
+    level: "guarded",
+    group: "destructive",
+    label: "Filesystem sweep via find",
+  },
+  {
+    pattern: /\brm\b[^|&;]*\s['"]?\$\{?[A-Za-z_]\w*\}?\/?['"]?(?=\s|$|[;|&])/i,
+    level: "guarded",
+    group: "destructive",
+    label: "Delete of a shell-variable target",
+  },
+];
+
+const GIT_RULES: readonly Gate[] = [
+  {
+    pattern: /\bgit\s+push\b[^|&;]*(?:\s--force\b|\s--force-with-lease\b|\s-f\b)/i,
+    level: "guarded",
+    group: "git",
+    label: "Force push",
+  },
+  {
+    pattern: /\bgit\s+(?:reset\s+--hard\b|checkout\s+--\s+\.(?=\s|$)|restore\s+\.(?=\s|$)|clean\s+-[a-z]*f|stash\s+(?:drop|clear)\b)/i,
+    level: "guarded",
+    group: "git",
+    label: "Uncommitted-work destruction",
+  },
+  {
+    pattern: /\bgit\s+commit\b[^|&;]*--amend\b/i,
+    level: "guarded",
+    group: "git",
+    label: "Commit amend",
+  },
+  {
+    pattern: /\bgit\s+remote\s+(?:add|set-url)\b/i,
+    level: "guarded",
+    group: "git",
+    label: "Remote reconfiguration",
+  },
+  {
+    pattern: /\bgit\s+push\b[^|&;]*[\s:](?:production|release|gh-pages)(?=\s|$|[:;|&])/i,
+    level: "guarded",
+    group: "git",
+    label: "Push to a deploy branch",
+  },
+];
+
+const IAC_RULES: readonly Gate[] = [
+  {
+    pattern: /\b(?:terraform|pulumi|cdk|terragrunt)\b[^|&;]*\bdestroy\b/i,
+    level: "guarded",
+    group: "iac",
+    label: "Infrastructure destroy",
+  },
+  {
+    pattern: /\bkubectl\b[^|&;]*\s(?:drain|delete\s+node|exec|port-forward)\b/i,
+    level: "guarded",
+    group: "iac",
+    label: "Cluster node or pod intrusion",
+  },
+  {
+    pattern: /\bkubectl\b[^|&;]*\s(?:delete|scale|patch|label|annotate|cordon|uncordon|taint)\b[^|&;]*(?:\s--all\b|\s-l[= ]|\s--selector[= ])/i,
+    level: "guarded",
+    group: "iac",
+    label: "Cluster-wide write",
+  },
+];
+
+const NET_EXEC_RULES: readonly Gate[] = [
+  {
+    pattern: /\b(?:curl|wget)\b[^|&;]*\|\s*(?:sudo\s+)?(?:bash|sh|zsh|python3?|perl|node)\b/i,
+    level: "guarded",
+    group: "net-exec",
+    label: "Piped remote code execution",
+  },
+  {
+    pattern: /\bngrok\b|\bcloudflared\s+tunnel\b|\bssh\b[^|&;]*\s-R\b|\/dev\/tcp\//i,
+    level: "guarded",
+    group: "net-exec",
+    label: "Tunnel or reverse shell",
+  },
+];
+
+const SECRETS_RULES: readonly Gate[] = [
+  {
+    pattern: /\baws\s+secretsmanager\s+(?:put|create|update|delete|rotate)|\bvault\s+kv\s+(?:put|patch|destroy|delete)|\bgcloud\s+dns\b|\bcertbot\b|\baz\s+keyvault\b[^|&;]*\s(?:set|import|delete)\b/i,
+    level: "guarded",
+    group: "secrets",
+    label: "Secret store, DNS, or certificate write",
+  },
+  {
+    pattern: /\benv\b\s*\|\s*grep\b[^|&;]*(?:key|token|secret|pass)|\bcat\b[^|&;]*\.env['"]?\s*[|>]|\bprintenv\b[^|&;]*(?:key|token|secret)/i,
+    level: "guarded",
+    group: "secrets",
+    label: "Credential print",
+  },
+  {
+    pattern: /\b(?:cat|cp|scp|rsync|curl|tar|base64|grep|head|tail)\b[^|&;]*(?:~|\$\{?HOME\}?)\/\.(?:ssh|aws|config\/gcloud)\b|\b(?:cat|grep|head|tail)\b[^|&;]*\.(?:bash_history|zsh_history)\b/i,
+    level: "guarded",
+    group: "secrets",
+    label: "Credential store read",
+  },
+];
+
+const SUPPLY_CHAIN_RULES: readonly Gate[] = [
+  {
+    pattern: /\b(?:npm|yarn|pnpm|bun)\b[^|&;]*\s--registry\b|\bpip3?\b[^|&;]*\s(?:-i|--index-url)[= ]/i,
+    level: "guarded",
+    group: "supply-chain",
+    label: "Registry override install",
+  },
+  {
+    pattern: /\bgh\s+repo\s+fork\b|\bgh\s+pr\s+create\b[^|&;]*\s(?:--repo|-R)[= ]/i,
+    level: "guarded",
+    group: "supply-chain",
+    label: "Cross-repo contribution",
+  },
+];
+
+const REVIEW_RULES: readonly Gate[] = [
+  {
+    pattern: /\bgh\s+pr\s+merge\b|\bgh\s+pr\s+review\b[^|&;]*--approve\b/i,
+    level: "guarded",
+    group: "review",
+    label: "Merge or approve a pull request",
+  },
+  {
+    pattern: /\bgit\s+(?:commit|push|merge)\b[^|&;]*--no-verify\b|\b(?:curl|wget)\b[^|&;]*(?:\s-k\b|\s--insecure\b)|--skip-checks\b/i,
+    level: "guarded",
+    group: "review",
+    label: "Safety guard bypass flag",
+  },
+];
+
+const PROTECTED_PATH_RULES: readonly Gate[] = [
+  {
+    pattern: new RegExp(WRITE + String.raw`['"]?(?:\S*\/)?\.(?:git\/|gitconfig\b|gitmodules\b)`, "i"),
+    level: "guarded",
+    group: "protected-paths",
+    label: "Shell write to git internals",
+  },
+  {
+    pattern: new RegExp(WRITE + String.raw`['"]?(?:\S*\/)?(?:\.(?:husky\/|pre-commit-config\.ya?ml\b)|\.?lefthook\.ya?ml\b)`, "i"),
+    level: "guarded",
+    group: "protected-paths",
+    label: "Shell write to hook config",
+  },
+  {
+    pattern: new RegExp(WRITE + String.raw`['"]?(?:\S*\/)?\.(?:bashrc\b|bash_profile\b|bash_aliases\b|bash_login\b|bash_logout\b|zshrc\b|zprofile\b|zshenv\b|zlogin\b|zlogout\b|profile\b|envrc\b|npmrc\b|yarnrc\b|cargo\/)`, "i"),
+    level: "guarded",
+    group: "protected-paths",
+    label: "Shell write to shell or tool dotfiles",
+  },
+  {
+    pattern: new RegExp(WRITE + String.raw`['"]?(?:\S*\/)?\.pi\/(?!agent\/sessions)`, "i"),
+    level: "guarded",
+    group: "protected-paths",
+    label: "Shell write to project agent config",
+  },
+];
+
+export const DEFAULT_RULES: readonly Gate[] = [
+  ...OVERSIGHT_RULES,
+  ...DESTRUCTIVE_RULES,
+  ...GIT_RULES,
+  ...IAC_RULES,
+  ...NET_EXEC_RULES,
+  ...SECRETS_RULES,
+  ...SUPPLY_CHAIN_RULES,
+  ...REVIEW_RULES,
+  ...PROTECTED_PATH_RULES,
+];

package/denial-log.ts

@@ -0,0 +1,111 @@
+import { appendFileSync, chmodSync, mkdirSync, readFileSync, renameSync, statSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+
+/** Rotate once the sidecar grows past this size; one previous generation is kept. */
+export const DENIAL_LOG_ROTATE_BYTES = 16 * 1024 * 1024;
+
+/** The two ways a review can end without the command running. */
+export type DenialVerdict = "revise" | "block";
+
+/**
+ * What produced the denial:
+ * - `deny` / `convention` — a rule blocked mechanically, no reviewer involved
+ * - `guardian` — the reviewer's own verdict (a revise, or an ask_user with no
+ *   interactive user to ask)
+ * - `user` — the user chose Block at the approval prompt
+ * - `loop` — a guardian verdict delivered as a bounded block because an
+ *   unattended loop cannot answer a prompt
+ * - `review_failure` — review infrastructure failed and the command was
+ *   blocked rather than waved through
+ */
+export type DenialSource = "deny" | "convention" | "guardian" | "user" | "loop" | "review_failure";
+
+export interface DenialRecord {
+  v: 1;
+  id: string;
+  ts: string;
+  sessionId: string;
+  cwd: string;
+  tool: string;
+  gate: { label: string; group: string };
+  command: string;
+  verdict: DenialVerdict;
+  reason: string;
+  decisionSource: DenialSource;
+}
+
+export function buildDenialRecord(input: {
+  sessionId: string;
+  cwd: string;
+  tool: string;
+  gate: { label: string; group: string };
+  command: string;
+  verdict: DenialVerdict;
+  reason: string;
+  decisionSource: DenialSource;
+}): DenialRecord {
+  return {
+    v: 1,
+    id: randomUUID(),
+    ts: new Date().toISOString(),
+    sessionId: input.sessionId,
+    cwd: input.cwd,
+    tool: input.tool,
+    gate: { label: input.gate.label, group: input.gate.group },
+    command: input.command,
+    verdict: input.verdict,
+    reason: input.reason,
+    decisionSource: input.decisionSource,
+  };
+}
+
+function rotateIfLarge(path: string): void {
+  try {
+    if (statSync(path).size < DENIAL_LOG_ROTATE_BYTES) return;
+    renameSync(path, `${path}.1`);
+  } catch {
+    // A missing or unrotatable sidecar simply keeps appending.
+  }
+}
+
+export function appendDenialRecord(path: string, record: DenialRecord): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  rotateIfLarge(path);
+  appendFileSync(path, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
+  chmodSync(path, 0o600);
+}
+
+/**
+ * The newest `limit` denials, newest first, for the `/auto-permissions`
+ * Recent denials view. Malformed lines are skipped, a missing file is an
+ * empty history, and only the live generation is read — the rotated `.1`
+ * file is archival.
+ */
+export function readRecentDenials(path: string, limit: number): DenialRecord[] {
+  let content: string;
+  try {
+    content = readFileSync(path, "utf8");
+  } catch {
+    return [];
+  }
+  const records: DenialRecord[] = [];
+  for (const line of content.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const value = JSON.parse(line) as DenialRecord;
+      if (
+        value && typeof value === "object" && value.v === 1
+        && typeof value.command === "string"
+        && typeof value.reason === "string"
+        && (value.verdict === "revise" || value.verdict === "block")
+        && value.gate && typeof value.gate.label === "string" && typeof value.gate.group === "string"
+      ) {
+        records.push(value);
+      }
+    } catch {
+      // Skip unparsable lines; the log is append-only best effort.
+    }
+  }
+  return records.slice(-limit).reverse();
+}

package/evaluation-log.ts

@@ -45,6 +45,32 @@ export interface PromptEvaluationRecord {
   expectedDecision: Extract<PermissionDecision, "approve" | "ask_user">;
 }
 
+/**
+ * A prefilter SAFE approval, recorded so false negatives are measurable: no
+ * prompt opened, so there is no user label yet — the record carries the
+ * command and compact evidence for offline labelling against the same
+ * criteria as prompted records.
+ */
+export interface PrefilterEvaluationRecord {
+  version: 2;
+  timestamp: string;
+  sessionId: string;
+  cwd: string;
+  tool: string;
+  gate: {
+    label: string;
+    group: string;
+  };
+  userRequest: string;
+  command: string;
+  relevantContext: ReviewEvidenceRecord[];
+  actualDecision: "approve";
+  actualReason: "prefilter";
+  decisionSource: "prefilter";
+}
+
+export type EvaluationRecord = PromptEvaluationRecord | PrefilterEvaluationRecord;
+
 export function classifyPromptChoice(choice: string | undefined): PromptChoiceClassification | undefined {
   if (choice === "Allow") return { allowsExecution: true };
   // Plain "Block" is still live: the logging-disabled prompt offers
@@ -69,7 +95,7 @@ export function expectedDecisionForChoice(
   return choice === "allow_unnecessary" ? "approve" : "ask_user";
 }
 
-export function appendPromptEvaluation(path: string, record: PromptEvaluationRecord): void {
+export function appendPromptEvaluation(path: string, record: EvaluationRecord): void {
   mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
   appendFileSync(path, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
   chmodSync(path, 0o600);

package/gates.ts

@@ -1,4 +1,18 @@
-export type GateLevel = "guarded" | "convention";
+/**
+ * Rule severity levels, in decision order:
+ * - `deny`: blocks immediately with the rule's required `message`. A hard
+ *   policy boundary — not clearable by `request_override`, not bypassed by
+ *   `.pi/trusted-ops` groups, never shown to the guardian. The mechanical
+ *   analogue of Claude Code's pre-classifier circuit breaker.
+ * - `convention`: blocks directly with the rule's required `message`, but the
+ *   agent may ask the user for a one-session exception via `request_override`.
+ * - `guarded`: sends the command to the guardian reviewer.
+ *
+ * When several rules match one command, the effective level is the most
+ * severe across *all* matches (deny > convention > guarded), never the first
+ * match in config order.
+ */
+export type GateLevel = "deny" | "guarded" | "convention";
 
 export interface Gate {
   pattern: RegExp;
@@ -9,6 +23,20 @@ export interface Gate {
   suggest?: (command: string) => string;
 }
 
+/**
+ * The fallback gate used when `reviewAllShell` is enabled and a bash command
+ * matches no configured rule: everything the ruleset does not name is still
+ * reviewed under this generic gate (the analogue of Claude Code's
+ * `classifyAllShell`). Its group participates in `.pi/trusted-ops` like any
+ * other, so a trusted project can opt back out of blanket review.
+ */
+export const ALL_SHELL_GATE: Gate = {
+  pattern: /(?:)/,
+  level: "guarded",
+  group: "all-shell",
+  label: "shell command",
+};
+
 export function findGates(command: string, rules: readonly Gate[]): Gate[] {
   return rules.filter((gate) => {
     gate.pattern.lastIndex = 0;

package/guardian-transport.ts

@@ -22,12 +22,12 @@ import { completeSimple } from "@earendil-works/pi-ai/compat";
  * future pi release renames the seam — degrading to the historical behavior
  * instead of crashing.
  *
- * THIS FILE IS DUPLICATED VERBATIM across packages/pi-auto-permissions and
- * packages/pi-herdr-auto-title, and `scripts/validate.py` fails if the copies
- * differ by a single byte. The duplication is deliberate: sharing it made a
- * pane-titling extension depend on an entire permissions engine to reuse a
- * dozen lines. Edit one copy, then copy it over the other. Every
- * package-specific detail must stay behind a parameter — hence `packageLabel`.
+ * This file was duplicated verbatim into packages/pi-herdr-auto-title until
+ * that package was removed; `DUPLICATED_SOURCES` in `scripts/validate.py`
+ * policed the copies. It has one home again. If a second extension package
+ * ever needs it, copy it rather than importing across packages by relative
+ * path, and register the pair in `DUPLICATED_SOURCES` — which is why every
+ * package-specific detail stays behind a parameter (`packageLabel`).
  * The "guardian" in the names is historical: pi-auto-permissions' guardian
  * reviewer was the first caller.
  */