@odingard/guardian-hook 0.1.1 → 0.2.0

package/README.md

@@ -78,6 +78,33 @@ Guardian sets modes **per connection**, not per tool. So the hook uses two recor
 
 `npx @odingard/guardian-hook setup` prints all of this. To see where a command would be routed, run `npx @odingard/guardian-hook classify "terraform apply"`, which prints `shell_deploy`.
 
+## Claude Agent SDK agents (0.2.0)
+
+Agents built on Anthropic's Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`) can be governed by Guardian in the same way:
+
+```ts
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { guardianHookMatcher } from "@odingard/guardian-hook/agent-sdk";
+
+for await (const message of query({
+  prompt: "Run the tests, then deploy staging",
+  options: { hooks: { PreToolUse: [guardianHookMatcher()] } },
+})) {
+  if (message.type === "result") console.log(message.subtype);
+}
+```
+
+It uses the same environment variables, the same two connections (the console's "Set up for Claude Code" creates them) and the same decisions as the Claude Code hook. Approvers see the agent as "Claude agent" unless you pass `agentName`.
+
+`guardianHookMatcher()` registers the hook with:
+
+- `onFailure: "block"`, so a crash blocks the call instead of letting it through (Agent SDK 0.3.317 or later);
+- a timeout longer than Guardian's 5-minute approval window.
+
+A `PreToolUse` hook runs for every tool call, even calls an allow rule or `bypassPermissions` would approve, and its deny holds in every permission mode.
+
+A runnable example is in `examples/claude-agent-sdk.mjs`.
+
 ## 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/agent-sdk.d.ts

@@ -0,0 +1,39 @@
+// Types for "@odingard/guardian-hook/agent-sdk" (see src/agent-sdk.ts).
+type Env = Readonly<Record<string, string | undefined>>;
+
+export type GuardianHookInput = Readonly<{
+  hook_event_name?: string;
+  tool_name?: unknown;
+  tool_input?: unknown;
+  cwd?: unknown;
+}>;
+
+export type GuardianHookOutput =
+  | Record<string, never>
+  | {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse";
+        permissionDecision: "allow" | "deny";
+        permissionDecisionReason: string;
+      };
+    };
+
+export type GuardianPreToolUseOptions = Readonly<{
+  env?: Env;
+  agentName?: string;
+  log?: (line: string) => void;
+}>;
+
+export declare function guardianPreToolUse(
+  options?: GuardianPreToolUseOptions,
+): (input: GuardianHookInput) => Promise<GuardianHookOutput>;
+
+export declare const GUARDIAN_HOOK_TIMEOUT_SECONDS: number;
+
+export declare function guardianHookMatcher(
+  options?: GuardianPreToolUseOptions,
+): {
+  hooks: ((input: GuardianHookInput) => Promise<GuardianHookOutput>)[];
+  timeout: number;
+  onFailure: "block";
+};

package/dist/agent-sdk.js

@@ -0,0 +1,369 @@
+// src/run.ts
+import { createGuardianClient } from "@odingard/guardian-sdk";
+
+// src/classify.ts
+import { createHash } from "node:crypto";
+var HOOK_TOOLS = [
+  {
+    name: "shell",
+    suggestedMode: "allow",
+    description: "Ordinary shell commands (build, test, read-only inspection)."
+  },
+  {
+    name: "shell_deploy",
+    suggestedMode: "ask",
+    description: "Infrastructure and deploy commands: terraform/tofu apply or destroy, pulumi up, kubectl apply/delete, helm install/upgrade, cdk/serverless/fly/vercel deploys, cloud deploy CLIs."
+  },
+  {
+    name: "shell_destructive",
+    suggestedMode: "ask",
+    description: "Destructive commands: rm -rf, git reset --hard, git clean, force pushes, dropping databases, disk formatting."
+  },
+  {
+    name: "git_push",
+    suggestedMode: "ask",
+    description: "Pushing commits to a remote."
+  },
+  {
+    name: "file_write",
+    suggestedMode: "allow",
+    description: "Creating or editing files in the workspace."
+  },
+  {
+    name: "web_fetch",
+    suggestedMode: "allow",
+    description: "Fetching a URL."
+  }
+];
+var MAX_COMMAND = 2e3;
+var DEPLOY = [
+  /\b(terraform|tofu)\b.*\s(apply|destroy|import|state\s+(rm|mv|push))\b/,
+  /\bpulumi\s+(up|destroy|update)\b/,
+  /\bkubectl\b.*\s(apply|delete|create|replace|patch|scale|rollout|drain|cordon)\b/,
+  /\bhelm\s+(install|upgrade|uninstall|rollback|delete)\b/,
+  /\b(cdk|serverless|sls|sam)\s+(deploy|destroy|remove)\b/,
+  /\bfly(ctl)?\s+(deploy|destroy|apps\s+destroy|scale)\b/,
+  /\bvercel\b.*(--prod\b|\bdeploy\b|\bpromote\b|\bremove\b)/,
+  /\bnetlify\s+deploy\b.*--prod\b/,
+  /\bgcloud\s+.*\b(deploy|delete)\b/,
+  /\baws\s+.*\b(deploy|delete-stack|create-stack|update-stack|terminate-instances|delete-db-instance)\b/,
+  /\baz\s+.*\b(deploy|delete|create)\b/,
+  /\bwrangler\s+(deploy|publish|delete)\b/,
+  /\bdocker\s+(push|compose\s+.*\bup\b.*--remote)\b/,
+  /\b(npm|pnpm|yarn)\s+publish\b/,
+  /\btwine\s+upload\b/,
+  /\bgh\s+(release\s+create|workflow\s+run|pr\s+merge)\b/
+];
+var DESTRUCTIVE = [
+  /\brm\s+(?:-\S*[rR]\S*\s+(?:-\S+\s+)*|-\S*f\S*\s+-\S*[rR])/,
+  /\bgit\s+reset\s+.*--hard\b/,
+  /\bgit\s+clean\s+-\S*f/,
+  /\bgit\s+push\b.*(\s--force\b|\s-f\b|--force-with-lease|\s\+\S)/,
+  /\bgit\s+(branch\s+-D|checkout\s+--\s|restore\s+--source)\b/,
+  /\b(drop|truncate)\s+(table|database|schema)\b/i,
+  /\bdelete\s+from\s+\w+\s*(;|$)/i,
+  /\b(mkfs|dd\s+if=|shred|wipefs)\b/,
+  /\bchmod\s+-R\s+777\b/,
+  /\bfind\b.*\s-delete\b/
+];
+var GIT_PUSH = /\bgit\s+push\b/;
+function classifyCommand(command) {
+  if (DESTRUCTIVE.some((re) => re.test(command))) return "shell_destructive";
+  if (DEPLOY.some((re) => re.test(command))) return "shell_deploy";
+  if (GIT_PUSH.test(command)) return "git_push";
+  return "shell";
+}
+function mcpToolName(server, tool) {
+  const part = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").replace(/^(\d)/, "x$1") || "x";
+  return `mcp.${part(server)}.${part(tool)}`.slice(0, 64).replace(/[._-]+$/, "");
+}
+function bounded(text, max = MAX_COMMAND) {
+  return text.length <= max ? text : `${text.slice(0, max)}\u2026 [${text.length - max} more chars]`;
+}
+function digest(text) {
+  return `sha256:${createHash("sha256").update(text).digest("hex")}`;
+}
+function str(value) {
+  return typeof value === "string" ? value : "";
+}
+function governedCall(call) {
+  const { tool, input } = call;
+  const cwd = call.cwd ? { cwd: call.cwd } : {};
+  if (tool === "Bash" || tool === "shell") {
+    const command = str(input.command);
+    const toolName = classifyCommand(command);
+    return {
+      toolName,
+      arguments: { command: bounded(command), ...cwd },
+      summary: `Run: ${bounded(command, 160)}`
+    };
+  }
+  if (["Write", "Edit", "MultiEdit", "NotebookEdit"].includes(tool)) {
+    const path = str(input.file_path) || str(input.notebook_path);
+    const content = str(input.content) || str(input.new_string) || str(input.new_source) || (Array.isArray(input.edits) ? JSON.stringify(input.edits) : "");
+    return {
+      toolName: "file_write",
+      arguments: {
+        operation: tool,
+        path,
+        contentBytes: Buffer.byteLength(content),
+        contentDigest: digest(content),
+        ...cwd
+      },
+      summary: `${tool === "Write" ? "Write" : "Edit"} ${path}`
+    };
+  }
+  if (tool === "WebFetch") {
+    const url = str(input.url);
+    return {
+      toolName: "web_fetch",
+      arguments: { url: bounded(url, 500) },
+      summary: `Fetch ${bounded(url, 160)}`
+    };
+  }
+  const mcp = /^mcp__(.+?)__(.+)$/.exec(tool);
+  if (mcp) {
+    const [, server, name] = mcp;
+    const json = JSON.stringify(input);
+    return {
+      toolName: mcpToolName(server, name),
+      arguments: json.length <= MAX_COMMAND ? { server, tool: name, input } : {
+        server,
+        tool: name,
+        inputBytes: json.length,
+        inputDigest: digest(json)
+      },
+      summary: `MCP ${server} \u2192 ${name}`
+    };
+  }
+  return null;
+}
+function tierOf(toolName) {
+  const known = HOOK_TOOLS.find((t) => t.name === toolName);
+  return known ? known.suggestedMode : "ask";
+}
+
+// src/decide.ts
+var PLAIN = {
+  NOT_AUTHORIZED: "this agent is not authorized for it",
+  APPROVAL_DENIED: "the approver declined it",
+  APPROVAL_NOT_SATISFIED: "the approver declined it",
+  APPROVAL_EXPIRED: "the approval expired",
+  UNAUTHENTICATED: "the Guardian agent credential was rejected",
+  INVALID_REQUEST: `this tool is not allowed for the agent yet. In the Guardian console: Agents \u2192 this agent \u2192 the connection's card \u2192 "Allow a tool by name"`,
+  SERVICE_UNAVAILABLE: "Guardian could not be reached",
+  REQUEST_CONFLICT: "Guardian saw a conflicting request"
+};
+function plain(code) {
+  return PLAIN[code] ?? code;
+}
+function denied(call, code, extra = {}) {
+  return {
+    decision: "deny",
+    reason: `Guardian blocked ${call.toolName} (${code}): ${plain(code)}. Do not retry or work around this; ask the developer to review it in the Guardian console.`,
+    ...extra
+  };
+}
+var isPending = (r) => !r.ok && (r.reasonCode === "APPROVAL_REQUIRED" || r.reasonCode === "APPROVAL_PENDING") || r.ok && r.decision === "ASK";
+async function decide(call, options) {
+  const wait = options.wait ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const now = options.now ?? Date.now;
+  const log = options.log ?? (() => {
+  });
+  let result;
+  try {
+    result = await options.client.request({
+      action: "tool.invoke",
+      connectionId: options.connectionId,
+      toolName: call.toolName,
+      arguments: call.arguments,
+      purpose: `${options.agentName}: ${call.summary}`,
+      ...options.requestTtlMs !== void 0 ? { ttlMs: options.requestTtlMs } : {}
+    });
+  } catch {
+    return denied(call, "SERVICE_UNAVAILABLE");
+  }
+  const requestId = result.requestId;
+  let approvedByHuman = false;
+  if (isPending(result)) {
+    if (!requestId) return denied(call, "MISSING_REQUEST_ID");
+    log(
+      `Guardian: "${call.summary}" is held for approval (request ${requestId}). Approve it on your phone or in the console.`
+    );
+    const deadline = now() + options.approvalTimeoutMs;
+    const maxInterval = Math.max(
+      options.maxPollIntervalMs ?? 1e4,
+      options.pollIntervalMs
+    );
+    let interval = options.pollIntervalMs;
+    for (; ; ) {
+      await wait(interval);
+      interval = Math.min(Math.ceil(interval * 1.5), maxInterval);
+      let claimed;
+      try {
+        claimed = await options.client.claim(requestId);
+      } catch {
+        claimed = { ok: false, reasonCode: "APPROVAL_REQUIRED", requestId };
+      }
+      if (!isPending(claimed)) {
+        result = claimed;
+        approvedByHuman = claimed.ok && claimed.decision === "ALLOW";
+        break;
+      }
+      if (now() >= deadline) {
+        return {
+          decision: "deny",
+          reason: `Guardian is still waiting for a human to approve ${call.toolName} (request ${requestId}). Nothing ran. Tell the developer it needs approval in the Guardian app, then try again.`,
+          requestId,
+          guardianDecision: "ASK"
+        };
+      }
+    }
+  }
+  if (!result.ok || result.decision !== "ALLOW" || !result.capabilityToken) {
+    const code = result.ok ? result.reasonCode ?? (result.decision === "DENY" ? "DENIED" : "MISSING_CAPABILITY") : result.reasonCode;
+    return denied(call, code, {
+      ...requestId ? { requestId } : {},
+      guardianDecision: "DENY"
+    });
+  }
+  let executed;
+  try {
+    executed = await options.client.execute({
+      requestId: result.requestId,
+      capabilityToken: result.capabilityToken
+    });
+  } catch {
+    executed = { ok: false, reasonCode: "SERVICE_UNAVAILABLE" };
+  }
+  if (!executed.ok) {
+    return denied(call, executed.reasonCode, {
+      requestId: result.requestId,
+      guardianDecision: approvedByHuman ? "ASK" : "ALLOW",
+      approvedByHuman
+    });
+  }
+  return {
+    decision: "allow",
+    reason: approvedByHuman ? `Approved by a human in Guardian (request ${result.requestId}).` : `Allowed by Guardian policy (request ${result.requestId}).`,
+    requestId: result.requestId,
+    guardianDecision: approvedByHuman ? "ASK" : "ALLOW",
+    approvedByHuman
+  };
+}
+
+// src/run.ts
+var DEFAULT_BASE_URL = "https://guardian-api.odingard.com";
+var REQUEST_TTL_MS = 3e5;
+var MAX_WAIT_MS = REQUEST_TTL_MS;
+function claudeCodeOutput(verdict) {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: verdict.decision,
+      permissionDecisionReason: verdict.reason
+    }
+  });
+}
+function connectionFor(toolName, env) {
+  const allow = env.GUARDIAN_CONNECTION_ID?.trim() || void 0;
+  if (tierOf(toolName) === "allow") return allow;
+  return env.GUARDIAN_HOOK_ASK_CONNECTION_ID?.trim() || allow;
+}
+async function runHook(stdin, env, deps = {}) {
+  const failClosed = (reason) => claudeCodeOutput({ decision: "deny", reason: `Guardian hook: ${reason}` });
+  let input;
+  try {
+    input = JSON.parse(stdin);
+  } catch {
+    return failClosed(
+      "could not read the tool call from the agent. Nothing ran."
+    );
+  }
+  if (typeof input.tool_name !== "string") {
+    return failClosed("the tool call had no tool name. Nothing ran.");
+  }
+  const call = governedCall({
+    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 "";
+  const connectionId = connectionFor(call.toolName, env);
+  const credential = env.GUARDIAN_AGENT_CREDENTIAL?.trim();
+  const baseUrl = (env.GUARDIAN_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(
+    /\/+$/,
+    ""
+  );
+  if (!deps.client && (!credential || !connectionId)) {
+    return failClosed(
+      "GUARDIAN_AGENT_CREDENTIAL and GUARDIAN_CONNECTION_ID must be set (run `npx @odingard/guardian-hook setup`). Nothing ran."
+    );
+  }
+  if (!deps.client && !baseUrl.startsWith("https://")) {
+    return failClosed("GUARDIAN_BASE_URL must be https. Nothing ran.");
+  }
+  const requested = Number(
+    env.GUARDIAN_HOOK_APPROVAL_TIMEOUT_MS ?? MAX_WAIT_MS
+  );
+  const approvalTimeoutMs = Number.isFinite(requested) ? Math.min(Math.max(requested, 0), MAX_WAIT_MS) : MAX_WAIT_MS;
+  const verdict = await decide(call, {
+    client: deps.client ?? createGuardianClient({
+      baseUrl,
+      credential,
+      ...env.GUARDIAN_ADAPTER_ID ? { adapterId: env.GUARDIAN_ADAPTER_ID } : {}
+    }),
+    connectionId: connectionId ?? "",
+    agentName: env.GUARDIAN_HOOK_AGENT_NAME?.trim() || "Claude Code",
+    approvalTimeoutMs,
+    requestTtlMs: REQUEST_TTL_MS,
+    pollIntervalMs: 2e3,
+    ...deps.wait ? { wait: deps.wait } : {},
+    ...deps.now ? { now: deps.now } : {},
+    ...deps.log ? { log: deps.log } : {}
+  });
+  return claudeCodeOutput(verdict);
+}
+
+// src/agent-sdk.ts
+function guardianPreToolUse(options = {}) {
+  return async (input) => {
+    if (input.hook_event_name && input.hook_event_name !== "PreToolUse") {
+      return {};
+    }
+    const base = options.env ?? process.env;
+    const env = {
+      ...base,
+      GUARDIAN_HOOK_AGENT_NAME: options.agentName ?? base.GUARDIAN_HOOK_AGENT_NAME ?? "Claude agent"
+    };
+    const output = await runHook(
+      JSON.stringify({
+        tool_name: input.tool_name,
+        tool_input: input.tool_input,
+        cwd: input.cwd
+      }),
+      env,
+      {
+        log: options.log ?? ((line) => process.stderr.write(`${line}
+`)),
+        ...options.client ? { client: options.client } : {},
+        ...options.wait ? { wait: options.wait } : {},
+        ...options.now ? { now: options.now } : {}
+      }
+    );
+    return output ? JSON.parse(output) : {};
+  };
+}
+var GUARDIAN_HOOK_TIMEOUT_SECONDS = Math.ceil(MAX_WAIT_MS / 1e3) + 30;
+function guardianHookMatcher(options = {}) {
+  return {
+    hooks: [guardianPreToolUse(options)],
+    timeout: GUARDIAN_HOOK_TIMEOUT_SECONDS,
+    onFailure: "block"
+  };
+}
+export {
+  GUARDIAN_HOOK_TIMEOUT_SECONDS,
+  guardianHookMatcher,
+  guardianPreToolUse
+};

package/dist/index.js

@@ -1,8 +1,5 @@
 #!/usr/bin/env node
 
-// src/index.ts
-import { createGuardianClient } from "@odingard/guardian-sdk";
-
 // src/classify.ts
 import { createHash } from "node:crypto";
 var HOOK_TOOLS = [
@@ -145,6 +142,9 @@ function tierOf(toolName) {
   return known ? known.suggestedMode : "ask";
 }
 
+// src/run.ts
+import { createGuardianClient } from "@odingard/guardian-sdk";
+
 // src/decide.ts
 var PLAIN = {
   NOT_AUTHORIZED: "this agent is not authorized for it",
@@ -254,7 +254,7 @@ async function decide(call, options) {
   };
 }
 
-// src/index.ts
+// src/run.ts
 var DEFAULT_BASE_URL = "https://guardian-api.odingard.com";
 var REQUEST_TTL_MS = 3e5;
 var MAX_WAIT_MS = REQUEST_TTL_MS;
@@ -370,6 +370,8 @@ async function runHook(stdin, env, deps = {}) {
   });
   return claudeCodeOutput(verdict);
 }
+
+// src/index.ts
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) chunks.push(chunk);

package/package.json

@@ -1,22 +1,31 @@
 {
   "name": "@odingard/guardian-hook",
-  "version": "0.1.1",
-  "description": "Guardian for coding agents: a Claude Code PreToolUse hook 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.",
+  "version": "0.2.0",
+  "description": "Guardian for coding agents: a Claude Code PreToolUse hook (and a PreToolUse hook for 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",
   "type": "module",
   "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./agent-sdk": {
+      "types": "./agent-sdk.d.ts",
+      "default": "./dist/agent-sdk.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "guardian-hook": "dist/index.js"
   },
   "files": [
     "dist",
+    "agent-sdk.d.ts",
     "README.md"
   ],
   "engines": {
     "node": ">=22"
   },
   "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node22 --external:@odingard/guardian-sdk --outfile=dist/index.js",
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node22 --external:@odingard/guardian-sdk --outfile=dist/index.js && esbuild src/agent-sdk.ts --bundle --platform=node --format=esm --target=node22 --external:@odingard/guardian-sdk --outfile=dist/agent-sdk.js",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build && npm test"