@wyattjoh/demur 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wyatt Johnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+# demur
+
+A proof-of-concept destructive-command guard for coding agents. demur sends a
+shell command and limited execution context to TypeSafe System One, then turns
+four model judgments into an `allow`, `ask`, or `deny` decision.
+
+> [!WARNING]
+> demur is experimental and is not a security boundary. A model can
+> misclassify, behave nondeterministically, or be influenced by attacker-controlled
+> command text. Use it as an additional confirmation layer, not as your only
+> protection against destructive commands.
+
+## How it works
+
+For each agent-initiated Bash tool call, demur:
+
+1. Collects the command, working directory, host name, and bounded Git facts.
+2. Requests four judgments in one TypeSafe System One call:
+   - whether the command executes a destructive operation;
+   - whether its effects are recoverable;
+   - whether it targets shared infrastructure; and
+   - its expected blast radius.
+3. Applies deterministic thresholds from [`src/policy.ts`](src/policy.ts).
+4. Escalates an otherwise allowed destructive command to `ask` when variables,
+   globs, or command substitutions make its real target statically uncertain.
+5. Maps the decision into Pi or Claude Code's permission protocol.
+
+Environment access, Git queries, and network calls are Effect services. The
+policy and shell analysis remain pure functions, while `src/guard.ts` exposes a
+Promise boundary for host integrations.
+
+## Data disclosure
+
+Every judged command makes a request to TypeSafe. demur sends:
+
+- the complete command string;
+- the working directory;
+- the requesting host (`pi` or `claude-code`);
+- the repository root and current branch, when inside Git; and
+- counts of modified, untracked, and unpushed changes plus whether an upstream
+  branch exists.
+
+demur does not send file contents, environment-variable values, remote URLs, or
+its static-analysis result. Command strings and paths can still contain secrets
+or sensitive names. Review TypeSafe's service terms and data-handling policy
+before enabling demur in a sensitive repository. Do not run secrets directly in
+shell arguments when the guard is active.
+
+## Requirements
+
+- [Bun](https://bun.sh/) 1.4 or newer
+- A TypeSafe System One API key from <https://console.typesafe.ai/settings/keys>
+- Network access to TypeSafe for every judged command
+- Pi 0.85.x and/or Claude Code
+
+## Install
+
+Export the API key before launching the host agent. You can use your shell,
+`.env.local` with a compatible environment loader, or any secret manager:
+
+```sh
+export TYPESAFE_API_KEY="..."
+```
+
+Never commit the key. [`.env.schema`](.env.schema) documents the accepted
+configuration, and local environment files are ignored by Git.
+
+### Pi
+
+Install the npm package:
+
+```sh
+pi install npm:@wyattjoh/demur
+```
+
+Pin a specific release when reproducibility matters:
+
+```sh
+pi install npm:@wyattjoh/demur@0.1.0
+```
+
+Launch Pi from an environment that already contains `TYPESAFE_API_KEY`:
+
+```sh
+pi
+```
+
+The extension intercepts `bash` tool calls. `ask` opens an interactive
+confirmation dialog; without an interactive UI, demur blocks the command.
+
+Pi packages execute with the user's full system permissions. Review this
+repository before installing it.
+
+For development, clone the repository and install it by local path:
+
+```sh
+git clone https://github.com/wyattjoh/demur.git
+cd demur
+bun install --frozen-lockfile
+pi install "$PWD"
+```
+
+### Claude Code
+
+Register the source adapter in `~/.claude/settings.json`, replacing the path
+with the absolute path to your clone:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun /absolute/path/to/demur/src/adapters/claude-code.ts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Launch Claude Code from an environment that already contains
+`TYPESAFE_API_KEY`. The adapter emits Claude Code's
+`hookSpecificOutput.permissionDecision` response.
+
+### CLI
+
+Judge a single command without installing a host integration:
+
+```sh
+bun run judge "git reset --hard HEAD~3"
+```
+
+## Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `TYPESAFE_API_KEY` | required | TypeSafe API credential. Missing keys fail closed. |
+| `DEMUR_TIMEOUT_MS` | `4000` | Per-attempt model timeout in milliseconds. |
+| `DEMUR_DISABLE` | unset | Emergency bypass. `1` or `true` allows every command. |
+
+## Failure posture
+
+demur fails closed. A missing key, 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_DISABLE=1` is an explicit emergency bypass. It disables all protection
+and should remain unset during normal use.
+
+## Known limitations
+
+- Model decisions are probabilistic and may vary between identical requests.
+- The hard-coded `jev-latest` model alias may change without a demur release.
+- 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.
+- 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.
+- Other Pi extensions loaded after demur can mutate a tool call after it has been
+  judged.
+
+Use operating-system permissions, backups, repository protections, sandboxing,
+and deterministic policy controls alongside demur.
+
+## Project layout
+
+- `src/questions.ts` — the four model judgments
+- `src/policy.ts` — thresholds and `allow` / `ask` / `deny` composition
+- `src/analyze.ts` — deterministic shell analysis for the static uncertainty gate
+- `src/state.ts` — bounded environment and Git context collection
+- `src/guard.internal.ts` — Effect-native orchestration and fail-closed recovery
+- `src/guard.ts` — managed runtime and Promise boundary
+- `extensions/demur/` — Pi `tool_call` integration
+- `src/adapters/claude-code.ts` — Claude Code `PreToolUse` integration
+
+## Development
+
+```sh
+bun install --frozen-lockfile
+bun run check
+bun run test
+bun run build
+```
+
+All three checks run together with `bun run ci`.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) before proposing changes and
+[RELEASING.md](RELEASING.md) for the automated release process. Report security
+issues through [SECURITY.md](SECURITY.md), not a public issue.
+
+## License
+
+[MIT](LICENSE)

package/extensions/demur/index.ts

@@ -0,0 +1,63 @@
+import {
+  isToolCallEventType,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type ToolCallEvent,
+  type ToolCallEventResult,
+} from "@earendil-works/pi-coding-agent";
+import { guard } from "../../src/guard.ts";
+
+/**
+ * Handle one `tool_call` event, guarding shell commands only.
+ *
+ * Exported separately from the extension factory so it can be exercised
+ * directly in tests without standing up a Pi runtime.
+ *
+ * @param event - The tool call Pi is about to execute
+ * @param ctx - Extension context, used for the working directory and prompts
+ * @returns A block result when the command is denied, otherwise nothing
+ */
+export async function handleToolCall(
+  event: ToolCallEvent,
+  ctx: ExtensionContext,
+): Promise<ToolCallEventResult | undefined> {
+  if (!isToolCallEventType("bash", event)) return undefined;
+
+  const command = event.input.command ?? "";
+  if (command.trim() === "") return undefined;
+
+  const verdict = await guard(command, ctx.cwd, "pi", ctx.signal);
+
+  if (verdict.decision === "allow") return undefined;
+
+  if (verdict.decision === "deny") {
+    return { block: true, reason: verdict.reason };
+  }
+
+  // "ask": Pi can put the decision in front of the user, which is strictly
+  // better than the agent guessing. Without a UI there is nobody to ask, so the
+  // fail-closed posture applies and the command is blocked.
+  if (!ctx.hasUI) {
+    return {
+      block: true,
+      reason: `${verdict.reason} No interactive UI available to confirm, so blocking.`,
+    };
+  }
+
+  const approved = await ctx.ui.confirm("demur", `${verdict.reason}\n\n${command}\n\nRun it anyway?`);
+  if (approved) return undefined;
+
+  return { block: true, reason: `${verdict.reason} Declined by the user.` };
+}
+
+/**
+ * Pi extension entry point.
+ *
+ * Routes every bash tool call through a TypeSafe System One judgment before Pi
+ * is allowed to execute it.
+ *
+ * @param pi - The extension API provided by Pi
+ */
+export default function demur(pi: ExtensionAPI): void {
+  pi.on("tool_call", handleToolCall);
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@wyattjoh/demur",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A proof-of-concept destructive-command guard for coding agents.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wyattjoh/demur.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wyattjoh/demur/issues"
+  },
+  "homepage": "https://github.com/wyattjoh/demur#readme",
+  "keywords": [
+    "coding-agent",
+    "pi-package",
+    "security"
+  ],
+  "files": [
+    "extensions/demur/index.ts",
+    "src/adapters/claude-code.ts",
+    "src/analyze.ts",
+    "src/cli.ts",
+    "src/guard.internal.ts",
+    "src/guard.ts",
+    "src/judge.ts",
+    "src/key.ts",
+    "src/policy.ts",
+    "src/questions.ts",
+    "src/state.ts",
+    "src/types.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "bun@1.4.2",
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "vitest run",
+    "build:pi": "bun build extensions/demur/index.ts --target=bun --outfile=dist/demur-guard.ts --format=esm --external @earendil-works/pi-coding-agent",
+    "build:claude": "bun build src/adapters/claude-code.ts --target=bun --outfile=dist/demur-hook.js --format=esm",
+    "build": "bun run build:pi && bun run build:claude",
+    "ci": "bun run check && bun run test && bun run build",
+    "judge": "bun run src/cli.ts",
+    "prepublishOnly": "bun run ci"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "dependencies": {
+    "@effect/ai-typesafe": "4.0.0-rc.116",
+    "effect": "4.0.0-rc.116"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@effect/vitest": "4.0.0-rc.116",
+    "@types/bun": "1.4.2",
+    "typescript": "5.9.3",
+    "vitest": "5.0.1"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}

package/src/adapters/claude-code.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env bun
+import { Option, Schema } from "effect";
+import { guard } from "../guard.ts";
+
+const PreToolUsePayload = Schema.Struct({
+  cwd: Schema.optionalKey(Schema.String),
+  tool_name: Schema.optionalKey(Schema.String),
+  tool_input: Schema.optionalKey(
+    Schema.Struct({ command: Schema.optionalKey(Schema.String) }),
+  ),
+});
+
+const decodePayload = Schema.decodeUnknownOption(PreToolUsePayload);
+
+/**
+ * Emit a `PreToolUse` decision on stdout in Claude Code's hook protocol.
+ *
+ * The hook always exits 0: the decision is carried by the JSON body, not the
+ * exit code, and a non-zero exit would be read as a hook malfunction rather
+ * than a policy result.
+ *
+ * @param decision - What Claude Code should do with the tool call
+ * @param reason - Text shown to the model and the user
+ */
+function emit(decision: "allow" | "deny" | "ask", reason: string): void {
+  process.stdout.write(
+    `${JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: decision,
+        permissionDecisionReason: reason,
+      },
+    })}\n`,
+  );
+}
+
+/**
+ * Read the hook payload, judge the command, and print the decision.
+ *
+ * Only `Bash` tool calls are judged; everything else is passed through
+ * untouched so the hook can be registered broadly without cost.
+ */
+async function main(): Promise<void> {
+  let input: unknown;
+  try {
+    input = JSON.parse(await Bun.stdin.text());
+  } catch {
+    // A malformed envelope is a guard failure, and demur fails closed.
+    emit("deny", "demur: could not parse the PreToolUse payload.");
+    return;
+  }
+
+  const payload = Option.getOrUndefined(decodePayload(input));
+  if (payload === undefined) {
+    emit("deny", "demur: invalid PreToolUse payload.");
+    return;
+  }
+
+  if (payload.tool_name !== "Bash") {
+    emit("allow", "demur: not a Bash call.");
+    return;
+  }
+
+  const command = payload.tool_input?.command ?? "";
+  const cwd = payload.cwd ?? process.cwd();
+  const verdict = await guard(command, cwd, "claude-code");
+
+  emit(verdict.decision, verdict.reason);
+}
+
+await main();