@odingard/guardian-hook 0.3.1 → 0.4.0

package/README.md

@@ -252,6 +252,17 @@ A deny is the Claude Code deny JSON, plus the reason on stderr and exit 2, both
 - **The bridge lets the call run if the hook fails to run or crashes.** Only a deny or exit 2 blocks. As with Codex, the hook catches its own crashes, exits 2 on deny, and denies at its own 540-second deadline; the `|| … exit 2` covers a hook that cannot start. A hook killed from outside still fails open.
 - Not yet confirmed live: the tool names the bridge passes in a hosted dsh image (the source passes dsh's names unchanged; the matcher lists Claude Code's too), whether a host's dsh image already includes the bridge plugin, whether the hook's environment keeps `GUARDIAN_AGENT_CREDENTIAL`, and whether a host's headless runs allow a 5-minute wait. See `examples/deepseek-harness/`.
 
+## Edit-type tools: the target file is pinned (0.4)
+
+Approval binds the exact arguments. A file path is an argument; for most tools the file's contents are not. For Edit, MultiEdit, NotebookEdit and DeepSeek Harness `edit`, whose result depends on the file being edited, the hook reads the target file when the call is proposed and puts its SHA-256 in the approved arguments (`guardianContentPins`, or `absent: true` for a file that does not exist yet). Just before it releases the approved call it checks the file again. If the file changed, appeared or disappeared, the call is denied with `CONTENT_CHANGED_SINCE_APPROVAL`, nothing runs and the capability is not redeemed. Guardian's servers never see the file.
+
+- What this checks is that the file matched when the approved call was released. The agent's own Edit tool then reads the file again after the hook returns, so a short window remains.
+- The target path must be absolute; the hook does not resolve it against the working directory. An Edit-type call with a relative path is denied (`CONTENT_PIN_INVALID_ARGUMENT`). Claude Code always sends absolute paths.
+- Write and DeepSeek `write` are not pinned: they replace the whole file, so its current contents do not change what runs. Their arguments and tiers are unchanged.
+- Shell commands are not pinned. The command text is bound; files it names (`bash deploy.sh`, `curl -F file=@x`, globs, `$VAR`) are not.
+- Pinning is supported on Linux and macOS. On Windows an Edit-type call is denied (`CONTENT_PIN_UNSUPPORTED_PLATFORM`).
+- **Digest privacy:** the SHA-256 of the target is sent to Guardian, shown to the approver and kept in receipts. For a small or low-entropy file, anyone who sees the digest can guess the contents offline by hashing candidates.
+
 ## Limits (read these)
 
 - **Decision-gated.** The agent performs the effect after Guardian authorizes and redeems the call. The receipt proves Guardian's authorization of that exact call, not the command's own outcome.

package/dist/agent-sdk.js

@@ -3,6 +3,11 @@ import { createGuardianClient } from "@odingard/guardian-sdk";
 
 // src/classify.ts
 import { createHash } from "node:crypto";
+import {
+  CONTENT_PIN_INVALID_ARGUMENT,
+  CONTENT_PIN_KEY,
+  pinFile
+} from "@odingard/guardian-sdk";
 
 // src/shell.ts
 var MAX_NESTING = 16;
@@ -1244,6 +1249,54 @@ var FILE_TOOLS = /* @__PURE__ */ new Set([
   "edit"
   // DeepSeek Harness
 ]);
+var CONTENT_PIN_TOOLS = /* @__PURE__ */ new Set([
+  "Edit",
+  "MultiEdit",
+  "NotebookEdit",
+  "edit"
+  // DeepSeek Harness
+]);
+var EditPinRefused = class extends Error {
+  constructor(reasonCode, message) {
+    super(message);
+    this.reasonCode = reasonCode;
+    this.name = "EditPinRefused";
+  }
+  reasonCode;
+};
+async function pinEditTarget(call, governed) {
+  if (!CONTENT_PIN_TOOLS.has(call.tool)) return governed;
+  const path = governed.arguments.path;
+  if (typeof path !== "string" || !path.startsWith("/")) {
+    throw new EditPinRefused(
+      CONTENT_PIN_INVALID_ARGUMENT,
+      `${call.tool} needs an absolute file path; the hook does not resolve relative paths`
+    );
+  }
+  let pin;
+  try {
+    pin = await pinFile(path, { allowAbsent: true });
+  } catch (err) {
+    const code = typeof err?.reasonCode === "string" ? err.reasonCode : "CONTENT_PIN_UNREADABLE";
+    throw new EditPinRefused(
+      code,
+      `the current contents of ${path} could not be pinned`
+    );
+  }
+  const record = "absent" in pin ? { arg: "path", index: 0, mode: "recheck", absent: true } : {
+    arg: "path",
+    index: 0,
+    mode: "recheck",
+    name: pin.name,
+    size: pin.size,
+    sha256: pin.sha256
+  };
+  return {
+    ...governed,
+    arguments: { ...governed.arguments, [CONTENT_PIN_KEY]: [record] },
+    contentPin: { path, pin }
+  };
+}
 function commandText(value) {
   if (typeof value === "string") return value;
   if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
@@ -1371,6 +1424,7 @@ function tierOf(toolName) {
 }
 
 // src/decide.ts
+import { verifyPin } from "@odingard/guardian-sdk";
 var PLAIN = {
   NOT_AUTHORIZED: "this agent is not authorized for it",
   APPROVAL_DENIED: "the approver declined it",
@@ -1381,6 +1435,16 @@ var PLAIN = {
   SERVICE_UNAVAILABLE: "Guardian could not be reached",
   REQUEST_CONFLICT: "Guardian saw a conflicting request"
 };
+async function contentPinRefusal(call) {
+  if (!call.contentPin) return void 0;
+  try {
+    await verifyPin(call.contentPin.path, call.contentPin.pin);
+    return void 0;
+  } catch (err) {
+    const code = err?.reasonCode;
+    return typeof code === "string" ? code : "CONTENT_PIN_UNREADABLE";
+  }
+}
 function plain(code) {
   return PLAIN[code] ?? code;
 }
@@ -1461,6 +1525,17 @@ async function decide(call, options) {
       guardianDecision: "DENY"
     });
   }
+  const pinRefusal = await contentPinRefusal(call);
+  if (pinRefusal !== void 0) {
+    const path = call.contentPin.path;
+    return {
+      decision: "deny",
+      reason: pinRefusal === "CONTENT_CHANGED_SINCE_APPROVAL" ? `Guardian hook: ${path} changed since this edit was proposed (CONTENT_CHANGED_SINCE_APPROVAL). Nothing ran. Read the file again and propose the edit again; it needs a new approval.` : `Guardian hook: ${path} could not be checked against its approval (${pinRefusal}). Nothing ran.`,
+      requestId: result.requestId,
+      guardianDecision: approvedByHuman ? "ASK" : "ALLOW",
+      approvedByHuman
+    };
+  }
   let executed;
   try {
     executed = await options.client.execute({
@@ -1587,12 +1662,21 @@ async function evaluate(dialect, stdinText, env, deps, deadlineMs) {
   if (!input || typeof input.tool_name !== "string") {
     return failClosed("the tool call had no tool name. Nothing ran.");
   }
-  const call = governedCall({
+  const toolCall = {
     tool: input.tool_name,
     input: input.tool_input && typeof input.tool_input === "object" ? input.tool_input : {},
     ...typeof input.cwd === "string" ? { cwd: input.cwd } : {}
-  });
-  if (call === null) return null;
+  };
+  const classified = governedCall(toolCall);
+  if (classified === null) return null;
+  let call;
+  try {
+    call = await pinEditTarget(toolCall, classified);
+  } catch (err) {
+    const code = err instanceof EditPinRefused ? err.reasonCode : "CONTENT_PIN_UNREADABLE";
+    const detail = err instanceof EditPinRefused ? err.message : "the target file could not be pinned";
+    return failClosed(`${detail} (${code}). Nothing ran.`);
+  }
   const connectionId = connectionFor(call.toolName, env);
   const credential = env.GUARDIAN_AGENT_CREDENTIAL?.trim();
   const baseUrl = (env.GUARDIAN_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(

package/dist/index.js

@@ -2,6 +2,11 @@
 
 // src/classify.ts
 import { createHash } from "node:crypto";
+import {
+  CONTENT_PIN_INVALID_ARGUMENT,
+  CONTENT_PIN_KEY,
+  pinFile
+} from "@odingard/guardian-sdk";
 
 // src/shell.ts
 var MAX_NESTING = 16;
@@ -1243,6 +1248,54 @@ var FILE_TOOLS = /* @__PURE__ */ new Set([
   "edit"
   // DeepSeek Harness
 ]);
+var CONTENT_PIN_TOOLS = /* @__PURE__ */ new Set([
+  "Edit",
+  "MultiEdit",
+  "NotebookEdit",
+  "edit"
+  // DeepSeek Harness
+]);
+var EditPinRefused = class extends Error {
+  constructor(reasonCode, message) {
+    super(message);
+    this.reasonCode = reasonCode;
+    this.name = "EditPinRefused";
+  }
+  reasonCode;
+};
+async function pinEditTarget(call, governed) {
+  if (!CONTENT_PIN_TOOLS.has(call.tool)) return governed;
+  const path = governed.arguments.path;
+  if (typeof path !== "string" || !path.startsWith("/")) {
+    throw new EditPinRefused(
+      CONTENT_PIN_INVALID_ARGUMENT,
+      `${call.tool} needs an absolute file path; the hook does not resolve relative paths`
+    );
+  }
+  let pin;
+  try {
+    pin = await pinFile(path, { allowAbsent: true });
+  } catch (err) {
+    const code = typeof err?.reasonCode === "string" ? err.reasonCode : "CONTENT_PIN_UNREADABLE";
+    throw new EditPinRefused(
+      code,
+      `the current contents of ${path} could not be pinned`
+    );
+  }
+  const record = "absent" in pin ? { arg: "path", index: 0, mode: "recheck", absent: true } : {
+    arg: "path",
+    index: 0,
+    mode: "recheck",
+    name: pin.name,
+    size: pin.size,
+    sha256: pin.sha256
+  };
+  return {
+    ...governed,
+    arguments: { ...governed.arguments, [CONTENT_PIN_KEY]: [record] },
+    contentPin: { path, pin }
+  };
+}
 function commandText(value) {
   if (typeof value === "string") return value;
   if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
@@ -1373,6 +1426,7 @@ function tierOf(toolName) {
 import { createGuardianClient } from "@odingard/guardian-sdk";
 
 // src/decide.ts
+import { verifyPin } from "@odingard/guardian-sdk";
 var PLAIN = {
   NOT_AUTHORIZED: "this agent is not authorized for it",
   APPROVAL_DENIED: "the approver declined it",
@@ -1383,6 +1437,16 @@ var PLAIN = {
   SERVICE_UNAVAILABLE: "Guardian could not be reached",
   REQUEST_CONFLICT: "Guardian saw a conflicting request"
 };
+async function contentPinRefusal(call) {
+  if (!call.contentPin) return void 0;
+  try {
+    await verifyPin(call.contentPin.path, call.contentPin.pin);
+    return void 0;
+  } catch (err) {
+    const code = err?.reasonCode;
+    return typeof code === "string" ? code : "CONTENT_PIN_UNREADABLE";
+  }
+}
 function plain(code) {
   return PLAIN[code] ?? code;
 }
@@ -1463,6 +1527,17 @@ async function decide(call, options) {
       guardianDecision: "DENY"
     });
   }
+  const pinRefusal = await contentPinRefusal(call);
+  if (pinRefusal !== void 0) {
+    const path = call.contentPin.path;
+    return {
+      decision: "deny",
+      reason: pinRefusal === "CONTENT_CHANGED_SINCE_APPROVAL" ? `Guardian hook: ${path} changed since this edit was proposed (CONTENT_CHANGED_SINCE_APPROVAL). Nothing ran. Read the file again and propose the edit again; it needs a new approval.` : `Guardian hook: ${path} could not be checked against its approval (${pinRefusal}). Nothing ran.`,
+      requestId: result.requestId,
+      guardianDecision: approvedByHuman ? "ASK" : "ALLOW",
+      approvedByHuman
+    };
+  }
   let executed;
   try {
     executed = await options.client.execute({
@@ -1714,12 +1789,21 @@ async function evaluate(dialect2, stdinText, env, deps, deadlineMs) {
   if (!input || typeof input.tool_name !== "string") {
     return failClosed("the tool call had no tool name. Nothing ran.");
   }
-  const call = governedCall({
+  const toolCall = {
     tool: input.tool_name,
     input: input.tool_input && typeof input.tool_input === "object" ? input.tool_input : {},
     ...typeof input.cwd === "string" ? { cwd: input.cwd } : {}
-  });
-  if (call === null) return null;
+  };
+  const classified = governedCall(toolCall);
+  if (classified === null) return null;
+  let call;
+  try {
+    call = await pinEditTarget(toolCall, classified);
+  } catch (err) {
+    const code = err instanceof EditPinRefused ? err.reasonCode : "CONTENT_PIN_UNREADABLE";
+    const detail = err instanceof EditPinRefused ? err.message : "the target file could not be pinned";
+    return failClosed(`${detail} (${code}). Nothing ran.`);
+  }
   const connectionId = connectionFor(call.toolName, env);
   const credential = env.GUARDIAN_AGENT_CREDENTIAL?.trim();
   const baseUrl = (env.GUARDIAN_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@odingard/guardian-hook",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Guardian for coding agents: a Claude Code PreToolUse hook (also for OpenAI Codex CLI, DeepSeek Harness and Claude Agent SDK agents) that sends shell commands, file writes and MCP calls to Guardian for a deterministic ALLOW/ASK/DENY decision. Deploys and destructive commands wait for a human approval on your phone; every allowed call carries a verifiable receipt.",
   "license": "Apache-2.0",
   "author": "Odingard Security LLC",
@@ -32,7 +32,7 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@odingard/guardian-sdk": "^0.3.8"
+    "@odingard/guardian-sdk": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "^22",