@wyattjoh/demur 0.3.2 → 0.4.1

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.1
 ```
 <!-- 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.1",
   "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",

package/src/questions.ts

@@ -21,62 +21,60 @@ import { Decision } from "effect/unstable/ai";
 export const QUESTIONS = {
   executesDestruction: Decision.probability({
     instructions:
-      "Executing this command will actually carry out an operation that changes existing state, rather than only reading, searching, printing, or querying.",
+      "Will this command actually change existing state, rather than only read, search, print, list, query, or check?",
     criteria: {
-      true: "Running it performs a real operation on something that already exists: removing, overwriting, moving, resetting, or reconfiguring files, permissions, ownership, processes, containers, or remote resources. Judge what the command does when it runs, including anything it reaches through a shell, an interpreter, a wrapper such as `env` or `sudo`, command substitution, an alias, or a glob that expands to an executable.",
+      true: "It removes, overwrites, moves, resets, or reconfigures existing files, permissions, ownership, processes, containers, or remote resources, including through a shell, interpreter, wrapper, substitution, alias, or executable glob.",
       false:
-        "It only reads, searches, prints, lists, queries, or checks. Any destructive-looking text is inert: a search pattern, an argument to a read-only command, a string being printed or sent as data to a network service, quoted content inside a heredoc body that is payload rather than script, a comment, or documentation describing a command rather than running it.",
+        "It only reads or reports. Destructive-looking text is inert when used as search text, a read-only argument, printed or network payload, heredoc data, a comment, or documentation.",
     },
   }),
 
   exposesSensitiveData: Decision.probability({
     instructions:
-      "Executing this command will reveal or transmit the value of a secret, credential, authentication material, or personal data, including by printing it into the coding agent's command output.",
+      "Will this command disclose an actual secret, credential, authentication material, or personal-data value to the agent or another recipient?",
     criteria: {
-      true: "It reads sensitive values from environment variables, configuration files, credential stores, secret managers, databases, or remote systems and then prints, logs, copies, uploads, or otherwise discloses them. Output returned to the coding agent counts as disclosure, even when the command is read-only.",
+      true: "It reads a value from an environment variable, file, credential or secret store, database, or remote system and prints, logs, copies, or transmits it. Read-only output still counts.",
       false:
-        "It only names sensitive files, variables, or records; lists metadata; returns redacted values; rotates or revokes credentials without revealing them; or contains labels such as `secret` or `API_KEY` as inert search text, documentation, comments, or non-sensitive payload data rather than actual values.",
+        "It reveals only names, metadata, schema, attributes, or redacted values; rotates or revokes without revealing; or quotes or prints secret-looking names or commands as documentation, comments, or other inert payload.",
     },
   }),
 
   weakensSecurityBoundary: Decision.probability({
     instructions:
-      "Executing this command will actually disable, weaken, evade, or misrepresent a security boundary, or grant elevated access, rather than merely displaying or describing such an operation.",
+      "Will this command weaken or bypass a security control, conceal a bypass, grant elevated access, or make a sensitive resource more permissive?",
     criteria: {
-      true: "Running it defeats authentication, authorization, policy enforcement, auditing, MFA, SSO, a firewall, or another safeguard; grants administrator, root, sudo, or otherwise elevated access; hides that a control was bypassed; or makes a sensitive resource more permissive.",
+      true: "It disables or evades authentication, authorization, policy, auditing, MFA, SSO, or firewall controls; grants admin, root, or sudo access; hides a bypass; or broadens sensitive access.",
       false:
-        "It only inspects security state; enables or tightens a safeguard; revokes or narrows access; performs an ordinary scoped credential, role, permission, or membership change without elevating privileges; or changes non-security configuration. Dangerous-looking command text is inert when it is quoted, printed, searched, documented, commented, or sent as data rather than executed.",
+        "It only inspects controls; enables or strengthens them; revokes or narrows access; makes an ordinary non-elevating role, permission, or membership change; changes non-security configuration; or merely quotes, prints, searches, documents, comments on, or transmits dangerous text.",
     },
   }),
 
   unrecoverable: Decision.probability({
     instructions:
-      "Whatever this command destroys could not be recovered afterwards from the state described.",
+      "Could state destroyed by this command not be recovered from the described state?",
     criteria: {
-      true: "The affected data has no second copy. Uncommitted edits, untracked files, unpushed commits with no upstream, or remote resources with no backup.",
+      true: "It affects uncommitted edits, untracked files, unpushed commits without an upstream, or unbacked remote resources.",
       false:
-        "Everything it touches can be restored: it is committed and pushed to git, reinstallable, regenerable by re-running a build, or a cache that rebuilds on demand.",
+        "Affected state is committed and pushed, reinstallable, regenerable, temporary, self-created, a rebuildable cache, or a replaceable local container.",
     },
   }),
 
   targetsSharedInfrastructure: Decision.probability({
     instructions:
-      "This command acts on a shared, remote, or production system rather than on this machine's local checkout.",
+      "Does this command act on a shared, remote, or production system rather than only this machine?",
     criteria: {
-      true: "It operates on a production or shared database, a cloud account, a Kubernetes cluster, a remote host, a container registry, or a branch on a git remote.",
-      false:
-        "It operates only on local files, local containers, or the local git repository.",
+      true: "It affects a production or shared database, cloud account, Kubernetes cluster, remote host, container registry, or remote git branch.",
+      false: "It affects only local files, containers, or the local git repository.",
     },
   }),
 
   blastRadius: Decision.rate({
-    instructions:
-      "How much would be lost if this command ran and the outcome turned out to be unwanted.",
+    instructions: "Rate the unwanted loss if this command ran.",
     criteria: [
-      "Nothing of value. The command is read-only, or it touches only caches, build output, temporary files, or files it created itself.",
-      "Recoverable work inside this project: committed files, dependencies that can be reinstalled, or generated code that can be regenerated.",
-      "Irreplaceable local work: uncommitted edits, untracked files, unpushed commits, or unrelated files elsewhere on this machine.",
-      "Shared or production state: a branch other people depend on, a production database, cloud infrastructure, or a live service.",
+      "No valuable loss: read-only, cache, build output, temporary, or self-created files.",
+      "Recoverable project work: committed files, reinstallable dependencies, or regenerable output.",
+      "Irreplaceable local work: uncommitted edits, untracked files, unpushed commits, or unrelated local files.",
+      "Shared or production state: depended-on remote branches, production databases, cloud infrastructure, or live services.",
     ],
   }),
 } as const;