workspace-guard 0.1.0 → 0.2.0

package/README.md

@@ -3,13 +3,104 @@
 Decide whether a shell command or a file path would write outside a project
 root. It is the check you want in front of a coding agent you are not watching.
 
-`guard` answers one question and returns one bit. It does not run anything, it
-does not touch the filesystem beyond resolving symlinks, and it has no runtime
-dependencies — Node's standard library only.
+Two entry points, one decision:
 
-## Run it
+- **`guard-hook`** — a `PreToolUse` hook. It reads the tool call the agent is
+  about to make and denies it before it runs. Allowed calls are silent: no
+  prompt, no output, nothing added to your day.
+- **`guard`** — the same check as a CLI, for a wrapper or a script that wants
+  the verdict itself.
 
-Requires Node 18 or newer. There is nothing to install and nothing to build.
+Both answer one question and return one bit. Neither runs anything, neither
+touches the filesystem beyond resolving symlinks, and there are no runtime
+dependencies — Node's standard library only. Requires Node 18 or newer.
+
+The source, the test suite and the issue tracker live at
+<https://github.com/plainroot/workspace-guard>.
+
+## Use it as a hook
+
+```
+npm install -g workspace-guard
+```
+
+Then in `~/.claude/settings.json`, or a project's `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Write|Edit|MultiEdit|NotebookEdit",
+        "hooks": [{ "type": "command", "command": "guard-hook" }]
+      }
+    ]
+  }
+}
+```
+
+The root is the directory the hook process starts in. To pin it instead, set
+`WORKSPACE_GUARD_ROOT`. The command is run as a shell command, so an inline
+assignment works, and Claude Code puts the project directory in the environment
+as `CLAUDE_PROJECT_DIR`:
+
+```json
+{ "type": "command", "command": "WORKSPACE_GUARD_ROOT=\"$CLAUDE_PROJECT_DIR\" guard-hook" }
+```
+
+Without a global install, name the file:
+`"command": "node /abs/path/to/workspace-guard/bin/guard-hook.mjs"`.
+
+### What the first denial looks like
+
+The tool call does not run, and the agent is handed one sentence:
+
+```
+Blocked by workspace-guard: escapes the root through "..": ../notes.txt -> /Users/you/notes.txt. The project root is /Users/you/project.
+```
+
+That is the whole interface. There is no prompt to answer and no log to read —
+every call that is fine produces no output at all. The reason deliberately does
+not mention how the guard is configured or switched off, because an agent told
+where the off switch is will reach for it: issue #93602 on `anthropics/claude-code`
+records one reading a block and reasoning *"Remove-Item is blocked. Alternative
+approaches: robocopy /MOVE or cmd rmdir"*, then deleting 10,382 files with the
+alternative.
+
+### It fails open, on purpose
+
+A payload it cannot parse, a payload in a shape it does not recognise, a bug of
+ours — in all three cases the hook prints nothing, exits `0`, and the call
+proceeds.
+
+This is deliberate and it is a real cost. A `PreToolUse` hook sits in front of
+*every* tool call, so a hook that errors closed stops all work rather than
+dangerous work, and an agent wedged by a crash in a guardrail is how people
+learn to remove guardrails. The trade is stated so you can decide against it:
+if `guard-hook` does not understand a call, that call is not checked.
+
+Silence is not approval. Exiting `0` with no output means the hook has no
+decision to report, so the call continues through whatever permission rules you
+already have. `guard-hook` only ever denies; it never grants, and it cannot
+loosen a rule you set elsewhere.
+
+### It is still not a sandbox
+
+A hook is stronger than a CLI and weaker than a sandbox. Stronger, because it
+denies the action rather than returning a verdict for someone else to act on.
+Weaker, because it reads the command as text and is **not a shell parser** — a
+command constructed so the splitter cannot see the write goes through, and
+nothing stops a call it allowed from doing something it did not model. It is
+built for a capable agent that may be careless, not for one that is hostile.
+
+If you need the kernel to say no regardless of what the agent reasons its way
+into — bubblewrap, firejail, a container, a VM — use one of those. This is not
+a substitute for one, and the section ["What it is not"](#what-it-is-not) below
+applies to the hook exactly as it does to the CLI.
+
+## Run it as a CLI
+
+There is nothing to install and nothing to build.
 
 ```
 node bin/guard.mjs check --root <dir> --command "<shell command>"
@@ -41,30 +132,38 @@ it defaults to `--root`.
 It is also importable:
 
 ```js
-import { checkCommand, checkPath } from "./src/guard.mjs";
+import { checkCommand, checkPath } from "workspace-guard";
 
 checkCommand("rm -rf build", { root: process.cwd() });
 // { allowed: false, reason: "deletes recursively and without prompting: rm -rf build" }
 ```
 
+`workspace-guard/hook` exports `decide(payload, { root })` for wiring the same
+decision into a hook runner of your own.
+
 ## Verify it works
 
 ```
 npm test        # or: node --test test/
 ```
 
-18 tests, no network, no fixtures to install. The suite is table-driven: every
+26 tests, no network, no fixtures to install. The suite is table-driven: every
 threat below has a case, and so does every ordinary command that must keep
 working. A guard that denies everything is not a guard, so the allow table is
 the half worth reading — an ordinary build, a write inside the root, a plain
 `git push origin <branch>`, a recursive delete of `build/`, and a copy that
 *reads* from outside the root while writing inside it are all allowed.
 
+The hook has its own table, fed real `PreToolUse` payloads, including eleven
+malformed ones that must each fail open with empty output, and a case asserting
+that a deny reason never names the environment variable or the settings file.
+
 To satisfy yourself by hand, without trusting the suite:
 
 ```
 node bin/guard.mjs check --root . --path /etc/hosts     # prints deny, exits 1
 node bin/guard.mjs check --root . --path src/index.js   # prints allow, exits 0
+echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf ../"}}' | WORKSPACE_GUARD_ROOT=$PWD node bin/guard-hook.mjs
 ```
 
 ## What it denies
@@ -88,11 +187,40 @@ Destination-aware commands (`cp`, `mv`, `rsync`, `install`, `tee`, `touch`,
 `mkdir`, `dd`, `sed -i`, …) are judged on where they *write*, not on every path
 they mention, so reading a file from outside the root into the project is fine.
 
+## It also watches git
+
+Everything above is about the filesystem, which is where the attention goes.
+The other way an unattended agent does something you cannot take back is git,
+and the same check covers it:
+
+| Denied | Why |
+| --- | --- |
+| `git push --force …`, `git push -uf origin main` | discards commits that exist only on the remote |
+| `git push upstream main` | sends your work to a remote you did not nominate |
+| `git -C /elsewhere push` | drives a repository outside the root |
+
+A plain `git push origin <branch>` is allowed, as is `git push -u origin main`,
+and so is every read-only git command.
+
+This is the less-covered half. Agents committing, pushing and force-pushing
+without approval — sometimes overriding a rule written down for them — is a
+filed and repeated complaint: `anthropics/claude-code` issue #30475, *"Claude
+Code often commits and pushes without showing the changes first and waiting for
+user approval… even when the project has explicit guidelines (in CLAUDE.md)"*,
+and a Tell HN, *"Cursor agent force-pushed despite explicit 'ask for permission'
+rules"* ([46728766](https://news.ycombinator.com/item?id=46728766)). A container
+or a VM contains the filesystem damage and does nothing about this: it has the
+repository and the network, so the push leaves the sandbox exactly as intended.
+
 ## What it is not
 
-Not a sandbox. `guard` is a judgement, not an enforcement mechanism: it returns
-a verdict and something else has to act on it. Nothing stops a command it
-approved from doing something it did not model.
+Not a sandbox. The CLI is a judgement and not an enforcement mechanism at all:
+it returns a verdict and something else has to act on it. The hook does act —
+it denies the call — but it is still not confinement. Both see only what the
+agent declares it is about to do, the hook lets through anything it cannot
+read, and nothing stops a call either of them approved from doing something it
+did not model. Enforcement that holds against an agent working around it lives in
+the kernel, not in a package like this one.
 
 Not a shell parser. Commands are split on `;`, `|`, `&&` and `||` and one layer
 of quotes is stripped — enough to judge the patterns above without choking on
@@ -108,3 +236,5 @@ runtime state the tool does not have.
 ## License
 
 MIT — the manifest declares it and [`LICENSE`](LICENSE) is the text.
+
+Written with AI assistance.

package/bin/guard-hook.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { runHook } from "../src/hook.mjs";
+
+let raw = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("error", () => process.exit(0));
+process.stdin.on("data", (d) => { raw += d; });
+process.stdin.on("end", () => {
+  const out = runHook(raw);
+  // No process.exit here: stdout is a pipe, writes to it are asynchronous, and
+  // exiting would truncate the deny decision. Nothing else holds the loop open,
+  // so the process ends with status 0 once the write drains.
+  if (out) process.stdout.write(out);
+});

package/package.json

@@ -1,23 +1,35 @@
 {
   "name": "workspace-guard",
-  "version": "0.1.0",
-  "description": "Guardrail for running a coding agent unattended: decides whether a shell command or file path would write outside a project root, before you let it run.",
+  "version": "0.2.0",
+  "description": "Guardrail for running a coding agent unattended: a PreToolUse hook that denies a command or file write leaving the project root, and the same check as a CLI. No prompts, no dependencies.",
   "keywords": [
     "agent",
     "coding-agent",
     "claude",
+    "hook",
+    "pretooluse",
     "sandbox",
     "confinement",
     "guardrails",
     "unattended"
   ],
+  "homepage": "https://github.com/plainroot/workspace-guard#readme",
+  "bugs": {
+    "url": "https://github.com/plainroot/workspace-guard/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/plainroot/workspace-guard.git"
+  },
   "type": "module",
   "license": "MIT",
   "bin": {
-    "guard": "bin/guard.mjs"
+    "guard": "bin/guard.mjs",
+    "guard-hook": "bin/guard-hook.mjs"
   },
   "exports": {
-    ".": "./src/guard.mjs"
+    ".": "./src/guard.mjs",
+    "./hook": "./src/hook.mjs"
   },
   "files": [
     "bin",

package/src/hook.mjs

@@ -0,0 +1,65 @@
+import { checkCommand, checkPath } from "./guard.mjs";
+
+export const ROOT_ENV = "WORKSPACE_GUARD_ROOT";
+
+const WRITE_TOOLS = {
+  Write: ["file_path"],
+  Edit: ["file_path"],
+  MultiEdit: ["file_path"],
+  NotebookEdit: ["notebook_path", "file_path"],
+};
+
+const open = (reason) => ({ allowed: true, reason });
+
+// Total by construction: anything this cannot make sense of becomes an allow,
+// because a hook that throws on an unexpected payload would block every tool
+// call the agent makes until someone notices. The verdicts themselves still
+// come from guard.mjs, so the hook and the CLI cannot drift apart.
+export function decide(payload, { root, home } = {}) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload))
+    return open("payload is not an object");
+
+  const tool = payload.tool_name;
+  const input = payload.tool_input;
+  if (typeof tool !== "string" || !input || typeof input !== "object")
+    return open("payload carries no tool name or no tool input");
+
+  const opts = { root, home, cwd: typeof payload.cwd === "string" && payload.cwd ? payload.cwd : root };
+
+  const fields = WRITE_TOOLS[tool];
+  if (fields) {
+    const target = fields.map((f) => input[f]).find((v) => typeof v === "string" && v !== "");
+    return target ? checkPath(target, opts) : open(`${tool} carries no file path`);
+  }
+
+  if (tool === "Bash") {
+    const command = input.command;
+    if (typeof command !== "string" || !command.trim()) return open("Bash carries no command");
+    return checkCommand(command, opts);
+  }
+
+  return open(`${tool} does not write`);
+}
+
+// The reason is read back by the agent that was denied, so it says what was
+// denied and nothing about how the hook is configured or removed: an agent
+// told where the off switch is will reach for it (claude-code#93602).
+export function denyPayload(reason, root) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: `Blocked by workspace-guard: ${reason}. The project root is ${root}.`,
+    },
+  };
+}
+
+export function runHook(raw, { env = process.env, cwd = process.cwd() } = {}) {
+  const root = env[ROOT_ENV] || cwd;
+  try {
+    const decision = decide(JSON.parse(raw), { root });
+    return decision.allowed ? "" : JSON.stringify(denyPayload(decision.reason, root));
+  } catch {
+    return "";
+  }
+}