Merge pull request #41 from openagentlock/feat/cursor-harness

Feat/cursor harness

Author: RonCodes88

.gitignore

@@ -39,7 +39,6 @@ dev/
 
 # CLI build
 cli/dist/
-cli/agentlock
 
 # OS
 Thumbs.db
@@ -54,3 +53,4 @@ Thumbs.db
 
 # Auto-generated by editor tooling
 graphify-out/
+cli/openagentlock-cli-*.tgz

cli/agentlock

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+exec bun run "$(dirname "$0")/src/index.ts" "$@"

cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openagentlock/cli",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "description": "OpenAgentLock CLI — a firewall for AI coding agents. Detects local agent harnesses (Claude Code, Codex CLI, Cursor, OpenCode, Cline, Gemini CLI, Continue, Copilot), gates risky tool calls via a Go control plane, anchors decisions in a Rust Merkle ledger.",
@@ -33,6 +33,7 @@
   },
   "files": [
     "src/",
+    "agentlock",
     "tsconfig.json",
     "README.md",
     "LICENSE"

cli/src/commands/hook-claude-code.ts

@@ -0,0 +1,142 @@
+// `agentlock hook claude-code <event>` — Claude Code's command-hook shim.
+// Mirrors the codex/cursor pattern: stdin JSON in, daemon round-trip,
+// exit code + (on deny) reason on stderr.
+//
+// Why a shim instead of Claude's native HTTP hooks: when Claude was wired
+// as `type: "http"` directly at the daemon, every hook fire became a
+// browser-style fetch from inside Claude. A daemon outage rendered as a
+// red "PreToolUse:Bash hook error / ECONNREFUSED" banner on every tool
+// call. Routing through this shim lets us fail-open on transport errors
+// (exit 0) and emit a one-time friendly nudge instead — matching the UX
+// codex and cursor already get.
+//
+// Wire shape (Claude Code → daemon → Claude Code):
+//   stdin:  Claude's native event JSON (session_id, hook_event_name,
+//           tool_name, tool_input, tool_use_id, cwd)
+//   POST:   /v1/hooks/claude-code/<event>  (raw payload forwarded verbatim)
+//   reply:  daemon emits claudeHookOutput (continue/stopReason/
+//           hookSpecificOutput) — the same shape Claude consumed when the
+//           hook was HTTP-typed
+//   stdout: on deny, the JSON envelope (Claude Code accepts either an
+//           exit code OR JSON, we emit both for safety)
+//   exit:   0 on allow / observability, 2 on deny
+
+import { clearDaemonDownMarker, warnDaemonDownOnce } from "../util/daemon-warn.ts";
+
+const ALLOWED_EVENTS = new Set([
+  "session-start",
+  "pre-tool-use",
+  "post-tool-use",
+  "stop",
+]);
+
+interface ClaudeHookSpecifics {
+  hookEventName?: string;
+  permissionDecision?: "allow" | "deny" | "ask";
+  permissionDecisionReason?: string;
+}
+
+interface DaemonResponse {
+  continue?: boolean;
+  stopReason?: string;
+  hookSpecificOutput?: ClaudeHookSpecifics;
+}
+
+function defaultDaemonUrl(): string {
+  return (
+    process.env.AGENTLOCK_DAEMON_URL ??
+    process.env.AGENTLOCK_CONTROL_PLANE_URL ??
+    "http://127.0.0.1:7878"
+  );
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+export async function runHookClaudeCode(argv: string[]): Promise<void> {
+  const event = argv[0];
+  if (!event || !ALLOWED_EVENTS.has(event)) {
+    process.stderr.write(
+      `usage: agentlock hook claude-code <session-start|pre-tool-use|post-tool-use|stop>\n`,
+    );
+    process.exit(2);
+  }
+
+  const raw = await readStdin();
+  if (!raw.trim()) {
+    // No payload — nothing to forward. Fail-open: let Claude continue.
+    process.exit(0);
+  }
+
+  // Validate JSON locally so a malformed body doesn't waste a daemon
+  // round trip. Pass through verbatim if it parses.
+  try {
+    JSON.parse(raw);
+  } catch (e) {
+    process.stderr.write(
+      `agentlock hook claude-code ${event}: invalid JSON on stdin: ${(e as Error).message}\n`,
+    );
+    // Fail-open: invalid payload is the harness's bug, not policy.
+    process.exit(0);
+  }
+
+  const url =
+    defaultDaemonUrl().replace(/\/+$/, "") + `/v1/hooks/claude-code/${event}`;
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: raw,
+    });
+  } catch (e) {
+    warnDaemonDownOnce("claude-code", url, e as Error);
+    process.exit(0); // fail-open
+  }
+
+  // Successful round-trip — re-arm the nudge for the next outage.
+  clearDaemonDownMarker();
+
+  if (!res.ok) {
+    process.stderr.write(
+      `agentlock hook claude-code ${event}: daemon returned ${res.status}\n`,
+    );
+    process.exit(0); // fail-open
+  }
+
+  let parsed: DaemonResponse;
+  try {
+    parsed = (await res.json()) as DaemonResponse;
+  } catch (e) {
+    process.stderr.write(
+      `agentlock hook claude-code ${event}: malformed daemon response: ${(e as Error).message}\n`,
+    );
+    process.exit(0);
+  }
+
+  // SessionStart / PostToolUse / Stop are observability — the daemon
+  // returns {continue: true} unconditionally. Only PreToolUse can deny.
+  const decision = parsed.hookSpecificOutput?.permissionDecision;
+  if (decision === "deny") {
+    const reason =
+      parsed.hookSpecificOutput?.permissionDecisionReason ??
+      parsed.stopReason ??
+      "blocked by OpenAgentLock policy";
+    process.stderr.write(`${reason}\n`);
+    // Claude Code reads either the JSON body OR the exit code. Emit both
+    // so future Claude versions that prefer one over the other still see
+    // a deny.
+    process.stdout.write(JSON.stringify(parsed) + "\n");
+    process.exit(2);
+  }
+
+  // Allow path. Some Claude events don't carry hookSpecificOutput; just
+  // exit 0 silently. Stdout stays empty so we don't perturb Claude's
+  // own logging.
+  process.exit(0);
+}

cli/src/commands/hook-codex.ts

@@ -16,6 +16,8 @@
 // daemon-side ledger is the source of truth; if it can't be reached,
 // monitor mode is the safer default than blocking everything.
 
+import { clearDaemonDownMarker, warnDaemonDownOnce } from "../util/daemon-warn.ts";
+
 const ALLOWED_EVENTS = new Set([
   "session-start",
   "pre-tool-use",
@@ -87,12 +89,13 @@ export async function runHookCodex(argv: string[]): Promise<void> {
       body: raw,
     });
   } catch (e) {
-    process.stderr.write(
-      `agentlock hook codex ${event}: daemon unreachable at ${url}: ${(e as Error).message}\n`,
-    );
+    warnDaemonDownOnce("codex", url, e as Error);
     process.exit(0); // fail-open
   }
 
+  // Successful round-trip — re-arm the nudge for the next outage.
+  clearDaemonDownMarker();
+
   if (!res.ok) {
     process.stderr.write(
       `agentlock hook codex ${event}: daemon returned ${res.status}\n`,

cli/src/commands/hook-cursor.ts

@@ -0,0 +1,162 @@
+// `agentlock hook cursor <event>` — Cursor IDE's command-hook bridge to
+// the daemon. Cursor (≥1.7) spawns this binary, writes the hook payload
+// to stdin, and reads exit code + stdout JSON to decide whether the tool
+// call (or shell exec, or MCP call) proceeds.
+//
+// Wire shape (Cursor → daemon → Cursor):
+//   stdin:  Cursor's native event JSON (e.g. preToolUse with
+//           conversation_id / generation_id / tool_use_id)
+//   POST:   /v1/hooks/cursor/<event>  (raw payload forwarded verbatim)
+//   reply:  daemon emits the shared claudeHookOutput envelope
+//   stdout: Cursor's expected {permission, agent_message?} shape
+//   exit:   0 on allow, 2 on deny — Cursor reads either, both for safety
+//
+// Cursor exposes a dedicated `ask` permission, but ADR 0018 forbids
+// in-harness approval prompts. We map daemon `ask` → Cursor `deny` with
+// a fixed reason pointing at the dashboard.
+//
+// Failure modes are fail-open (exit 0). The daemon's ledger is the source
+// of truth; a missing daemon should not soft-brick the user's IDE.
+// Operators who want fail-closed semantics can install with
+// `failClosed: true` in the wired hook entries — Cursor will then treat
+// any exit-code error as a deny regardless of what we write to stdout.
+
+import { clearDaemonDownMarker, warnDaemonDownOnce } from "../util/daemon-warn.ts";
+
+const ALLOWED_EVENTS = new Set([
+  "session-start",
+  "pre-tool-use",
+  "before-shell-execution",
+  "before-mcp-execution",
+  "after-mcp-execution",
+  "post-tool-use",
+  "stop",
+]);
+
+interface ClaudeHookSpecifics {
+  hookEventName?: string;
+  permissionDecision?: "allow" | "deny" | "ask";
+  permissionDecisionReason?: string;
+}
+
+interface DaemonResponse {
+  continue?: boolean;
+  stopReason?: string;
+  hookSpecificOutput?: ClaudeHookSpecifics;
+}
+
+function defaultDaemonUrl(): string {
+  return (
+    process.env.AGENTLOCK_DAEMON_URL ??
+    process.env.AGENTLOCK_CONTROL_PLANE_URL ??
+    "http://127.0.0.1:7878"
+  );
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function emitAllow(): never {
+  process.stdout.write(JSON.stringify({ permission: "allow" }) + "\n");
+  process.exit(0);
+}
+
+function emitDeny(reason: string): never {
+  process.stderr.write(`${reason}\n`);
+  process.stdout.write(
+    JSON.stringify({ permission: "deny", agent_message: reason }) + "\n",
+  );
+  process.exit(2);
+}
+
+export async function runHookCursor(argv: string[]): Promise<void> {
+  const event = argv[0];
+  if (!event || !ALLOWED_EVENTS.has(event)) {
+    process.stderr.write(
+      `usage: agentlock hook cursor <session-start|pre-tool-use|before-shell-execution|before-mcp-execution|after-mcp-execution|post-tool-use|stop>\n`,
+    );
+    process.exit(2);
+  }
+
+  const raw = await readStdin();
+  if (!raw.trim()) {
+    // No payload — nothing to forward. Fail-open: let Cursor continue.
+    process.exit(0);
+  }
+
+  // Validate JSON locally so a malformed body doesn't waste a daemon
+  // round trip. Pass through verbatim if it parses.
+  try {
+    JSON.parse(raw);
+  } catch (e) {
+    process.stderr.write(
+      `agentlock hook cursor ${event}: invalid JSON on stdin: ${(e as Error).message}\n`,
+    );
+    // Fail-open: invalid payload is the harness's bug, not policy.
+    process.exit(0);
+  }
+
+  const url =
+    defaultDaemonUrl().replace(/\/+$/, "") + `/v1/hooks/cursor/${event}`;
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: raw,
+    });
+  } catch (e) {
+    warnDaemonDownOnce("cursor", url, e as Error);
+    process.exit(0); // fail-open
+  }
+
+  // Successful round-trip — re-arm the nudge for the next outage.
+  clearDaemonDownMarker();
+
+  if (!res.ok) {
+    process.stderr.write(
+      `agentlock hook cursor ${event}: daemon returned ${res.status}\n`,
+    );
+    process.exit(0); // fail-open
+  }
+
+  let parsed: DaemonResponse;
+  try {
+    parsed = (await res.json()) as DaemonResponse;
+  } catch (e) {
+    process.stderr.write(
+      `agentlock hook cursor ${event}: malformed daemon response: ${(e as Error).message}\n`,
+    );
+    process.exit(0);
+  }
+
+  // Only PreToolUse / shell / MCP gates can deny. Observability events
+  // (session-start, post-tool-use, after-mcp-execution, stop) come back
+  // with {continue: true} and no permissionDecision — exit 0 silently.
+  const decision = parsed.hookSpecificOutput?.permissionDecision;
+  if (decision === "deny") {
+    const reason =
+      parsed.hookSpecificOutput?.permissionDecisionReason ??
+      parsed.stopReason ??
+      "blocked by OpenAgentLock policy";
+    emitDeny(reason);
+  }
+  if (decision === "ask") {
+    // ADR 0018: no in-harness approval prompts. Map to deny with a
+    // fixed reason directing the user to the dashboard.
+    emitDeny("approval pending — use dashboard");
+  }
+
+  // Allow path. Some Cursor events don't carry hookSpecificOutput at
+  // all (the daemon returns plain {continue: true}); treat that the
+  // same as an explicit allow.
+  if (decision === "allow") {
+    emitAllow();
+  }
+  process.exit(0);
+}