@wyattjoh/demur 0.3.2 → 0.4.0

package/README.md

@@ -92,7 +92,7 @@ Pin a specific release when reproducibility matters:
 
 <!-- x-release-please-start-version -->
 ```sh
-pi install npm:@wyattjoh/demur@0.3.2
+pi install npm:@wyattjoh/demur@0.4.0
 ```
 <!-- x-release-please-end -->
 
@@ -109,6 +109,24 @@ command request and resulting verdict cross its local stdio pipes. `ask` opens
 an interactive confirmation dialog; without an interactive UI, demur blocks the
 command.
 
+Use `/demur` to open the extension menu. It can enable or disable demur and
+change what Pi does when demur cannot obtain a trustworthy judgment because of
+a missing credential, timeout, API error, malformed worker response, or
+unexpected guard failure:
+
+- `block` (default) fails closed.
+- `ask` requests interactive confirmation and blocks when no UI is available.
+- `allow` fails open without confirmation.
+
+Disabling demur bypasses the worker and allows Bash calls without judgment. Pi's
+bottom status bar always shows `demur: enabled` or `demur: disabled` so this
+bypass remains visible.
+
+Both settings are stored globally at `$XDG_CONFIG_HOME/demur/config.json`, or
+`~/.config/demur/config.json` when `XDG_CONFIG_HOME` is unset, and apply to
+future Pi sessions. While demur is enabled, the failure policy never changes a
+completed `deny` policy judgment; those commands remain blocked.
+
 After each run, Pi's interactive UI prints the decision, submitted input-token
 count, the run's estimated input cost, the accumulated global estimate, and the
 wall-clock evaluation time in human-readable units. The
@@ -186,13 +204,20 @@ From a development checkout, `bun run judge "<command>"` remains available.
 
 ## Failure posture
 
-demur fails closed. A missing key, credential-store failure, timeout, API
-failure, malformed response, or unexpected guard error returns `deny` with a
-reason that identifies the guard failure rather than presenting it as a policy
-judgment.
+demur's core guard fails closed. A missing key, credential-store failure,
+timeout, API failure, malformed response, or unexpected guard error returns
+`deny` with a reason that identifies the guard failure rather than presenting it
+as a policy judgment. The Claude Code adapter and CLI preserve that verdict.
+
+The Pi extension defaults to enabled with the same fail-closed behavior, but
+its explicit `/demur` menu can globally change how Pi handles guard failures or
+disable the extension entirely. The failure-policy override applies only when
+no trustworthy judgment was produced; it cannot loosen a completed policy
+denial while demur is enabled. The bottom status bar makes the enabled state
+visible.
 
-`DEMUR_DISABLE=1` is an explicit emergency bypass. It disables all protection
-and should remain unset during normal use.
+`DEMUR_DISABLE=1` remains the cross-host emergency bypass. It disables judgment
+and protection entirely and should remain unset during normal use.
 
 ## Known limitations
 
@@ -203,7 +228,8 @@ and should remain unset during normal use.
 - Attacker-controlled command text can influence the model.
 - Shell expansion, obfuscation, aliases, wrappers, and runtime environment can
   make a command behave differently from its text.
-- Network outages block commands unless the emergency bypass is enabled.
+- Network outages block commands by default; Pi can override that failure
+  handling from the `/demur` menu.
 - Every decision adds remote-call latency and may incur provider cost.
 - The integrations guard agent-issued Bash tool calls only. They do not guard
   user shells, other process-launching tools, or commands run outside the host.

package/extensions/demur/index.ts

@@ -12,6 +12,15 @@ import {
   estimateInputCostUsd,
   recordInputCost,
 } from "./cost-tracker.ts";
+import {
+  DEFAULT_DEMUR_SETTINGS,
+  FAILURE_POLICIES,
+  loadDemurSettings,
+  parseFailurePolicy,
+  saveDemurSettings,
+  type DemurSettings,
+  type FailurePolicy,
+} from "./settings.ts";
 
 const WORKER_PATH = fileURLToPath(
   new URL("../../src/adapters/pi-worker.ts", import.meta.url),
@@ -26,13 +35,16 @@ const MAX_WORKER_OUTPUT_BYTES = 64 * 1024;
  *
  * @param event - The tool call Pi is about to execute
  * @param ctx - Extension context, used for the working directory and prompts
+ * @param settings - Current global Pi extension settings
  * @returns A block result when the command is denied, otherwise nothing
  */
 export async function handleToolCall(
   event: ToolCallEvent,
   ctx: ExtensionContext,
+  settings: DemurSettings = DEFAULT_DEMUR_SETTINGS,
 ): Promise<ToolCallEventResult | undefined> {
   if (!isToolCallEventType("bash", event)) return undefined;
+  if (!settings.enabled) return undefined;
 
   const command = event.input.command ?? "";
   if (command.trim() === "") return undefined;
@@ -43,16 +55,79 @@ export async function handleToolCall(
     verdict = await runGuardWorker(command, ctx.cwd, ctx.signal);
   } catch (error: unknown) {
     const evaluationMs = performance.now() - evaluationStartedAt;
-    notifyRun(ctx, "ERROR", undefined, undefined, evaluationMs, "warning");
-    return {
-      block: true,
-      reason: `demur: guard worker crashed — ${errorDetail(error)} Blocking because demur fails closed. Set DEMUR_DISABLE=1 to bypass.`,
-    };
+    if (ctx.signal?.aborted) {
+      notifyRun(
+        ctx,
+        "CANCELLED → BLOCK",
+        undefined,
+        undefined,
+        evaluationMs,
+        "warning",
+      );
+      return {
+        block: true,
+        reason: "demur: guard request cancelled, so blocking the command.",
+      };
+    }
+
+    return handleGuardFailure(
+      `demur: guard worker crashed — ${errorDetail(error)}`,
+      command,
+      ctx,
+      settings.failurePolicy,
+      undefined,
+      undefined,
+      evaluationMs,
+    );
   }
 
   const evaluationMs = performance.now() - evaluationStartedAt;
   const inputTokens = verdict.usage?.inputTokens;
   const accumulatedCostUsd = await recordAccumulatedCost(inputTokens);
+  return resolveVerdict(
+    verdict,
+    command,
+    ctx,
+    settings.failurePolicy,
+    accumulatedCostUsd,
+    evaluationMs,
+  );
+}
+
+/**
+ * Apply the Pi extension's host policy to one completed guard verdict.
+ *
+ * A configured failure policy is consulted only when `verdict.failure` is set.
+ * Ordinary model and deterministic-policy denials always remain blocked.
+ *
+ * @param verdict - Completed demur guard result
+ * @param command - Shell command awaiting execution
+ * @param ctx - Pi extension context used for prompts and notifications
+ * @param failurePolicy - Host action to take when the guard failed
+ * @param accumulatedCostUsd - Persisted global estimate after this run
+ * @param evaluationMs - Wall-clock time spent obtaining the guard verdict
+ * @returns A block result when Pi must stop the command, otherwise nothing
+ */
+export async function resolveVerdict(
+  verdict: Verdict,
+  command: string,
+  ctx: ExtensionContext,
+  failurePolicy: FailurePolicy,
+  accumulatedCostUsd: number | undefined,
+  evaluationMs: number,
+): Promise<ToolCallEventResult | undefined> {
+  const inputTokens = verdict.usage?.inputTokens;
+  if (verdict.failure !== undefined) {
+    return handleGuardFailure(
+      stripFailClosedSuffix(verdict.reason),
+      command,
+      ctx,
+      failurePolicy,
+      inputTokens,
+      accumulatedCostUsd,
+      evaluationMs,
+    );
+  }
 
   if (verdict.decision === "allow") {
     notifyRun(
@@ -240,7 +315,166 @@ export function runGuardWorker(
  * @param pi - The extension API provided by Pi
  */
 export default function demur(pi: ExtensionAPI): void {
-  pi.on("tool_call", handleToolCall);
+  let settings = { ...DEFAULT_DEMUR_SETTINGS };
+
+  pi.registerCommand("demur", {
+    description: "Configure the demur guard",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("The /demur menu requires an interactive UI.", "warning");
+        return;
+      }
+
+      const toggleLabel = settings.enabled ? "Disable demur" : "Enable demur";
+      const policyLabel = `Change failure policy (current: ${settings.failurePolicy})`;
+      const action = await ctx.ui.select("demur", [toggleLabel, policyLabel]);
+      if (action === undefined) return;
+
+      if (action === toggleLabel) {
+        await persistSettings(
+          { ...settings, enabled: !settings.enabled },
+          ctx,
+        );
+        return;
+      }
+
+      const selection = await ctx.ui.select(
+        `demur failure policy (current: ${settings.failurePolicy})`,
+        [...FAILURE_POLICIES],
+      );
+      if (selection === undefined) return;
+
+      const failurePolicy = parseFailurePolicy(selection);
+      if (failurePolicy === undefined) return;
+      await persistSettings({ ...settings, failurePolicy }, ctx);
+    },
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    try {
+      settings = await loadDemurSettings();
+    } catch (error: unknown) {
+      settings = { ...DEFAULT_DEMUR_SETTINGS };
+      ctx.ui.notify(
+        `Could not load demur settings; using enabled/block: ${errorDetail(error)}`,
+        "warning",
+      );
+    }
+    updateStatus(ctx, settings);
+  });
+
+  pi.on("tool_call", (event, ctx) =>
+    handleToolCall(event, ctx, settings),
+  );
+
+  async function persistSettings(
+    nextSettings: DemurSettings,
+    ctx: ExtensionContext,
+  ): Promise<void> {
+    try {
+      await saveDemurSettings(nextSettings);
+      settings = nextSettings;
+      updateStatus(ctx, settings);
+      ctx.ui.notify(settingsNotification(settings), "info");
+    } catch (error: unknown) {
+      ctx.ui.notify(
+        `Could not save demur settings: ${errorDetail(error)}`,
+        "error",
+      );
+    }
+  }
+}
+
+function updateStatus(
+  ctx: ExtensionContext,
+  settings: DemurSettings,
+): void {
+  const status = settings.enabled ? "enabled" : "disabled";
+  const color = settings.enabled ? "success" : "warning";
+  ctx.ui.setStatus("demur", ctx.ui.theme.fg(color, `demur: ${status}`));
+}
+
+function settingsNotification(settings: DemurSettings): string {
+  const status = settings.enabled ? "enabled" : "disabled";
+  return `demur ${status} globally; failure policy: ${settings.failurePolicy}.`;
+}
+
+async function handleGuardFailure(
+  reason: string,
+  command: string,
+  ctx: ExtensionContext,
+  failurePolicy: FailurePolicy,
+  inputTokens: number | undefined,
+  accumulatedCostUsd: number | undefined,
+  evaluationMs: number,
+): Promise<ToolCallEventResult | undefined> {
+  if (failurePolicy === "allow") {
+    notifyRun(
+      ctx,
+      "FAILURE → ALLOW",
+      inputTokens,
+      accumulatedCostUsd,
+      evaluationMs,
+      "warning",
+    );
+    return undefined;
+  }
+
+  if (failurePolicy === "block") {
+    notifyRun(
+      ctx,
+      "FAILURE → BLOCK",
+      inputTokens,
+      accumulatedCostUsd,
+      evaluationMs,
+      "warning",
+    );
+    return {
+      block: true,
+      reason: `${reason} Blocking because the Pi failure policy is block.`,
+    };
+  }
+
+  if (!ctx.hasUI) {
+    notifyRun(
+      ctx,
+      "FAILURE → BLOCK",
+      inputTokens,
+      accumulatedCostUsd,
+      evaluationMs,
+      "warning",
+    );
+    return {
+      block: true,
+      reason: `${reason} The Pi failure policy is ask, but no interactive UI is available, so blocking.`,
+    };
+  }
+
+  const approved = await ctx.ui.confirm(
+    "demur guard failure",
+    `${reason}\n\n${command}\n\nThe guard could not validate this command. Run it anyway?`,
+  );
+  notifyRun(
+    ctx,
+    approved ? "FAILURE → ALLOW" : "FAILURE → BLOCK",
+    inputTokens,
+    accumulatedCostUsd,
+    evaluationMs,
+    "warning",
+  );
+  if (approved) return undefined;
+
+  return {
+    block: true,
+    reason: `${reason} Execution declined after the guard failure.`,
+  };
+}
+
+function stripFailClosedSuffix(reason: string): string {
+  return reason.replace(
+    / Blocking because demur fails closed\. Set DEMUR_DISABLE=1 to bypass\.$/,
+    "",
+  );
 }
 
 function notifyRun(

package/extensions/demur/settings.ts

@@ -0,0 +1,155 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/**
+ * How the Pi extension handles guard failures that produce no trustworthy
+ * policy judgment.
+ */
+export type FailurePolicy = "block" | "ask" | "allow";
+
+/**
+ * Failure policies accepted by the Pi extension command.
+ */
+export const FAILURE_POLICIES: readonly FailurePolicy[] = [
+  "block",
+  "ask",
+  "allow",
+];
+
+/**
+ * Globally persisted settings for the Pi extension.
+ */
+export type DemurSettings = {
+  /**
+   * Whether Bash calls are routed through demur.
+   */
+  enabled: boolean;
+  /**
+   * Host action to take when demur cannot obtain a trustworthy judgment.
+   */
+  failurePolicy: FailurePolicy;
+};
+
+/**
+ * Safe settings used when no persisted Pi configuration exists.
+ */
+export const DEFAULT_DEMUR_SETTINGS: DemurSettings = {
+  enabled: true,
+  failurePolicy: "block",
+};
+
+type DemurConfig = DemurSettings & {
+  version: 1;
+};
+
+/**
+ * Resolve the global demur configuration file according to the XDG config
+ * convention.
+ *
+ * @param environment - Process environment used to resolve `XDG_CONFIG_HOME`
+ * @param homeDirectory - Home directory used when the XDG override is absent
+ * @returns Absolute path to demur's global configuration file
+ */
+export function getDemurConfigPath(
+  environment: NodeJS.ProcessEnv = process.env,
+  homeDirectory: string = homedir(),
+): string {
+  const configDirectory =
+    environment.XDG_CONFIG_HOME || join(homeDirectory, ".config");
+  return join(configDirectory, "demur", "config.json");
+}
+
+/**
+ * Load the globally persisted Pi settings.
+ *
+ * A missing file uses the enabled, fail-closed defaults. Version 1 files from
+ * before the enabled toggle omit that field and are treated as enabled.
+ * Invalid or unreadable files are rejected so the extension can warn the user
+ * while still falling back safely.
+ *
+ * @param configPath - Configuration file to read
+ * @returns Persisted settings, or safe defaults when no file exists
+ */
+export async function loadDemurSettings(
+  configPath: string = getDemurConfigPath(),
+): Promise<DemurSettings> {
+  let content: string;
+  try {
+    content = await readFile(configPath, "utf8");
+  } catch (error: unknown) {
+    if (isErrorCode(error, "ENOENT")) return { ...DEFAULT_DEMUR_SETTINGS };
+    throw error;
+  }
+
+  const value: unknown = JSON.parse(content);
+  if (value === null || typeof value !== "object") {
+    throw new Error(`invalid demur config in ${configPath}: expected an object`);
+  }
+
+  const { version, enabled, failurePolicy } = value as Record<string, unknown>;
+  if (
+    version !== 1 ||
+    (enabled !== undefined && typeof enabled !== "boolean") ||
+    !isFailurePolicy(failurePolicy)
+  ) {
+    throw new Error(`invalid demur config in ${configPath}: unsupported values`);
+  }
+
+  return {
+    enabled: enabled ?? true,
+    failurePolicy,
+  };
+}
+
+/**
+ * Atomically persist the global Pi settings.
+ *
+ * @param settings - Settings to persist
+ * @param configPath - Configuration file to replace
+ */
+export async function saveDemurSettings(
+  settings: DemurSettings,
+  configPath: string = getDemurConfigPath(),
+): Promise<void> {
+  const config: DemurConfig = { version: 1, ...settings };
+  const temporaryPath = `${configPath}.${process.pid}.${randomUUID()}.tmp`;
+
+  await mkdir(dirname(configPath), { recursive: true, mode: 0o700 });
+  try {
+    await writeFile(temporaryPath, `${JSON.stringify(config, null, 2)}\n`, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 0o600,
+    });
+    await rename(temporaryPath, configPath);
+  } finally {
+    try {
+      await unlink(temporaryPath);
+    } catch (error: unknown) {
+      if (!isErrorCode(error, "ENOENT")) throw error;
+    }
+  }
+}
+
+/**
+ * Parse a command argument as a Pi failure policy.
+ *
+ * @param value - Raw slash-command argument
+ * @returns Normalized policy, or `undefined` when the argument is invalid
+ */
+export function parseFailurePolicy(value: string): FailurePolicy | undefined {
+  const normalized = value.trim().toLowerCase();
+  return isFailurePolicy(normalized) ? normalized : undefined;
+}
+
+function isFailurePolicy(value: unknown): value is FailurePolicy {
+  return FAILURE_POLICIES.some((policy) => policy === value);
+}
+
+function isErrorCode(error: unknown, code: string): boolean {
+  return error instanceof Error &&
+    "code" in error &&
+    (error as NodeJS.ErrnoException).code === code;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wyattjoh/demur",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "type": "module",
   "description": "A proof-of-concept destructive-command guard for coding agents.",
   "license": "MIT",
@@ -23,6 +23,7 @@
   ],
   "files": [
     "extensions/demur/cost-tracker.ts",
+    "extensions/demur/settings.ts",
     "extensions/demur/index.ts",
     "src/adapters/claude-code.ts",
     "src/adapters/pi-worker.ts",