agent-control-plane-core 0.1.0

package/README.md

@@ -0,0 +1,194 @@
+# agent-control-plane-core
+
+**One shape for "a coding agent is about to run a tool" and "here's what my
+guardrail decided" — so you write your tool once and it works across every
+agent.**
+
+## The problem this solves
+
+Coding agents — Claude Code, Codex, Gemini CLI, opencode, Amp, and friends — all
+let you hook into their tool-call loop: before a shell command runs, after a file
+is written, when a prompt is submitted. That's where you'd plug in a security
+guardrail, an audit log, a secret redactor, a policy engine.
+
+But **every agent speaks its own protocol.** One sends you `tool_name` +
+`tool_input` on stdin and wants `{"permissionDecision":"deny"}` back plus exit
+code 2. Another names the fields differently, blocks by throwing inside a plugin,
+or can only _observe_ and not veto. The field names differ, the "block this"
+signal differs, and each one drifts on its own release cadence.
+
+So if you build a tool that touches more than one agent, you end up writing and
+maintaining **N copies of the same logic** — one per agent — and re-testing all
+of them every time an agent ships a new field. That's the tax this package
+removes.
+
+## What it gives you
+
+- **`ToolCallEvent`** — one normalized, agent-agnostic view of "an agent event"
+  (a tool about to run, a tool that just ran, a prompt, a session start).
+- **`Verdict`** — one normalized way to say what your guardrail decided:
+  `allow` / `deny` / `ask`, optionally with a rewritten input or extra context.
+- **Adapters** — a thin `{ parse, render }` translator per agent. `parse` turns
+  that agent's raw hook payload into a `ToolCallEvent`; `render` turns your
+  `Verdict` back into the **real** native signal that agent enforces (the right
+  JSON body, exit code, or thrown error — not just a print).
+
+You write your logic **once** against the normalized types. Adding support for a
+new agent is a new adapter (~one file + fixtures), not a rewrite of your tool.
+The agent-specific field names live **only** inside that agent's adapter.
+
+## Who wants this
+
+Anyone building a tool that sits in the tool-call loop of **more than one**
+coding agent, and doesn't want to fork it per agent:
+
+- **Security guardrails** — deny-listers, command/path sanitizers, permission gates.
+- **Observability & audit** — log or replay every tool call in a uniform shape.
+- **Redaction / DLP** — strip secrets from tool inputs or outputs before they move.
+- **Policy engines** — one rule set enforced identically no matter which agent runs.
+
+If you only ever target a single agent, you don't need this — just use that
+agent's native hooks. The value is entirely in the _N-agents_ case.
+
+> **Not a security boundary.** A `Verdict` is advisory: a useful first filter,
+> never the last line of defense. Some agents can't enforce a `deny` at all (the
+> adapter marks those `observe_only`), so a real deployment still needs a sandbox
+> underneath. Treat the control plane as a policy layer on top of isolation, not
+> a replacement for it.
+
+## Install
+
+```bash
+pnpm add agent-control-plane-core
+```
+
+## The model
+
+```js
+// ToolCallEvent — a normalized, agent-agnostic view of one agent event.
+{
+  schema_version: 1,
+  event: "pre_tool" | "post_tool" | "prompt_submit" | "session_start" | "unknown",
+  tool: string | null,              // "Bash" | "Edit" | "Write" | "Read" | "WebFetch" | <passthrough> | null
+  input: object,                    // tool input; a submitted prompt folds into input.prompt
+  response?: unknown,               // post_tool only
+  this_call_vetoable: boolean,      // false ⇒ a deny here is advisory only; the guardrail cannot block THIS call
+  meta: {
+    agent: string,                  // "claude" | "codex" | …
+    native_event: string,           // original native event name, preserved verbatim
+    session_id?, cwd?, permission_mode?, transcript_path?,
+    passthrough: object,            // every unmodelled native top-level field, verbatim
+  }
+}
+
+// Verdict — a normalized guardrail decision.
+{
+  decision: "allow" | "deny" | "ask",
+  mutated_input?: object,           // replacement tool input
+  additional_context?: string,      // extra context to splice into the agent's stream
+  reason?: string,                  // shown on deny/ask
+}
+```
+
+An **Adapter** is a pair `{ AGENT, parse, render }`:
+
+```js
+parse(nativeEvent) -> ToolCallEvent      // never throws on unknown input
+render(verdict, event) -> nativeResponse // the agent's native shape
+```
+
+## Usage
+
+```js
+import { claudeAdapter } from "agent-control-plane-core/claude";
+
+// 1. Normalize the agent's raw hook payload.
+const event = claudeAdapter.parse(rawHookJson);
+
+// 2. Your guardrail decides, using only the normalized types.
+const verdict =
+  event.tool === "Bash" && /rm -rf/.test(String(event.input.command))
+    ? { decision: "deny", reason: "destructive command blocked" }
+    : { decision: "allow" };
+
+// 3. Render back to the agent's native response.
+process.stdout.write(JSON.stringify(claudeAdapter.render(verdict, event)));
+```
+
+The core contract and every adapter (`claude`, `codex`, `amp`, `gemini`) are
+also on the default entry:
+
+```js
+import {
+  EventKind,
+  Decision,
+  claudeAdapter,
+  codexAdapter,
+  ampAdapter,
+  geminiAdapter,
+  runAdapterConformance,
+} from "agent-control-plane-core";
+```
+
+## Drift discipline (the point of the seam)
+
+Agent protocols drift **additively and independently** — N agents, N release
+cadences. So `parse` **never throws** on an event type or tool-input field it
+does not model: an unrecognized event becomes `EventKind.UNKNOWN` with its native
+name kept in `meta.native_event`, and every unmodelled field survives in `input`
+or `meta.passthrough`. An additive upstream change is a **no-op**, not an outage.
+
+The core models only the stable middle — four event kinds, three decisions, and
+the `Bash`/`Edit`/`Write`/`Read`/`WebFetch` tool inputs (`MODELED_TOOLS`). Exotic
+per-agent tools pass through untouched.
+
+## Writing a new adapter
+
+An adapter for cursor/cline/gemini-cli/aider is a thin, independently-pinned
+translator with its own golden fixtures. It must pass the conformance suite:
+
+```js
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { runAdapterConformance } from "agent-control-plane-core/conformance";
+import { myAdapter } from "./my-adapter.mjs";
+import fixtures from "./fixtures/my-agent.json" with { type: "json" };
+
+test("my adapter conforms", () => {
+  runAdapterConformance({ adapter: myAdapter, fixtures, assert });
+});
+```
+
+The harness pins both directions and rejects a vacuous suite:
+
+1. `parse(native)` deep-equals the fixture's golden `event`.
+2. `render(verdict, event)` deep-equals the fixture's golden native response, for
+   each verdict scenario.
+3. The fixture set collectively renders an `allow`, a `deny`, an `ask`, **and** a
+   `mutated_input` — so a suite can't pass while skipping a decision the contract
+   requires every adapter to express.
+
+See `src/fixtures/claude.json` and `src/fixtures/codex.json` for the format.
+
+## Versioning
+
+`src/control-plane.mjs` is the frozen contract and its own single source of
+truth. `SCHEMA_VERSION` / `CONTROL_PLANE_SCHEMA` are pinned by a test. **Adding**
+an optional field or a modeled tool is backward-compatible and stays at v1;
+**renaming/removing** a field or changing a decision/event vocabulary is breaking
+and bumps the version.
+
+## Development
+
+```bash
+./setup.sh          # install deps + git hooks
+pnpm test           # node --test
+pnpm test:coverage  # c8, 100% lines/branches/functions per file
+pnpm check          # tsc --noEmit (JSDoc types)
+pnpm lint           # eslint
+pnpm build          # emit .d.mts declarations into types/
+```
+
+## License
+
+MIT

package/bin/amp-hook.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Amp EXTERNAL_HOOK entry (pure exit-code transport, no stdout body). Reads a
+ * delegate payload on stdin, applies the demo judge, and exits with Amp's
+ * decision code (0 allow / 1 ask / 2 reject).
+ *
+ * FAILURE POSTURE — fail to ASK (exit 1), NOT allow. Amp's delegate reads exit 1
+ * as "ask the human," which is the safe degradation when the guardrail itself is
+ * broken: neither silently allowing (exit 0) nor hard-denying (exit 2) a call it
+ * never actually judged. This is the asymmetry the per-host split exists for —
+ * Amp has a safe "ask" failure code that Claude Code's transport does not.
+ *
+ * Usage: `node bin/amp-hook.mjs < payload.json`
+ */
+import { ampAdapter } from "../src/adapters/amp.mjs";
+import { readStdin, renderHookResponse, emit } from "./hook-runtime.mjs";
+
+/** @type {import("../src/control-plane.mjs").NativeResponse} */
+const FAIL_ASK = { transport: "external_hook", exit_code: 1, enforced: false };
+
+emit(renderHookResponse(ampAdapter, await readStdin(), FAIL_ASK));

package/bin/claude-hook.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * Claude Code EXTERNAL_HOOK entry. Reads a native PreToolUse payload on stdin,
+ * applies the demo judge, and emits Claude Code's native response.
+ *
+ * FAILURE POSTURE — fail OPEN. Claude Code treats a hook that crashes, times out,
+ * or emits a non-conforming body as "no objection" and runs the tool anyway, so
+ * on any internal failure this exits 0 with no body rather than pretending to a
+ * decision it couldn't compute. A broken guardrail must not wedge the user; the
+ * sandbox is the real backstop, not this hook.
+ *
+ * Usage: `node bin/claude-hook.mjs < payload.json`
+ */
+import { claudeAdapter } from "../src/adapters/claude.mjs";
+import { readStdin, renderHookResponse, emit } from "./hook-runtime.mjs";
+
+/** @type {import("../src/control-plane.mjs").NativeResponse} */
+const FAIL_OPEN = { transport: "external_hook", exit_code: 0, enforced: false };
+
+emit(renderHookResponse(claudeAdapter, await readStdin(), FAIL_OPEN));

package/bin/codex-hook.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * Codex CLI EXTERNAL_HOOK entry. Reads a native PreToolUse/PermissionRequest
+ * payload on stdin, applies the demo judge, and emits Codex's native response.
+ *
+ * FAILURE POSTURE — fail OPEN (exit 0), like Claude Code: Codex treats a
+ * non-conforming hook as non-blocking. On a pre-v0.135 Codex the render is
+ * advisory anyway (the adapter marks it observe-only), so a failure and a
+ * successful advisory both leave the tool to proceed — the sandbox is the
+ * backstop.
+ *
+ * Usage: `node bin/codex-hook.mjs < payload.json`
+ */
+import { codexAdapter } from "../src/adapters/codex.mjs";
+import { readStdin, renderHookResponse, emit } from "./hook-runtime.mjs";
+
+/** @type {import("../src/control-plane.mjs").NativeResponse} */
+const FAIL_OPEN = { transport: "external_hook", exit_code: 0, enforced: false };
+
+emit(renderHookResponse(codexAdapter, await readStdin(), FAIL_OPEN));

package/bin/gemini-hook.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Gemini CLI EXTERNAL_HOOK entry. Reads a native BeforeTool payload on stdin,
+ * applies the demo judge, and emits Gemini's native response.
+ *
+ * FAILURE POSTURE — fail OPEN (exit 0). Gemini CLI treats a non-2 / crashed hook
+ * exit as a non-fatal warning and continues, so on any internal failure this
+ * exits 0 rather than emitting a spurious System Block (only a clean deny exits
+ * 2). A broken guardrail must not wedge the user; the sandbox is the backstop.
+ *
+ * Usage: `node bin/gemini-hook.mjs < payload.json`
+ */
+import { geminiAdapter } from "../src/adapters/gemini.mjs";
+import { readStdin, renderHookResponse, emit } from "./hook-runtime.mjs";
+
+/** @type {import("../src/control-plane.mjs").NativeResponse} */
+const FAIL_OPEN = { transport: "external_hook", exit_code: 0, enforced: false };
+
+emit(renderHookResponse(geminiAdapter, await readStdin(), FAIL_OPEN));

package/bin/hook-runtime.mjs

@@ -0,0 +1,69 @@
+/**
+ * Shared plumbing for the per-host EXTERNAL_HOOK entries — NOT a runtime host
+ * multiplexer. Each host has its OWN entry (`bin/<host>-hook.mjs`) that hardcodes
+ * its adapter and declares its OWN failure posture; this module only holds the
+ * transport mechanics they genuinely share (stdin read, the demo judge, the
+ * parse→judge→render pipe with a host-supplied fail-safe, and stdout+exit
+ * emission). The thing item ② deleted was the `--agent` switch that let one
+ * binary impersonate every host and so had to pick a single shared failure
+ * behavior; sharing pure plumbing across distinct entries is not that.
+ */
+import { Decision } from "../src/control-plane.mjs";
+
+/** Read all of stdin to a string. */
+export function readStdin() {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    process.stdin.on("data", (chunk) => chunks.push(chunk));
+    process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString()));
+    process.stdin.on("error", reject);
+  });
+}
+
+/**
+ * The DEMO policy standing in for a real guardrail judge: deny any command
+ * matching /rm -rf/, allow everything else. A real deployment swaps this for its
+ * own judge over the normalized {@link ToolCallEvent}.
+ * @param {import("../src/control-plane.mjs").ToolCallEvent} event
+ * @returns {import("../src/control-plane.mjs").Verdict}
+ */
+export function demoJudge(event) {
+  const command =
+    typeof event.input.command === "string" ? event.input.command : "";
+  return /rm\s+-rf/.test(command)
+    ? { decision: Decision.DENY, reason: "demo policy: rm -rf blocked" }
+    : { decision: Decision.ALLOW };
+}
+
+/**
+ * Run one host's parse→judge→render pipe over a raw stdin payload. If the payload
+ * can't be parsed or the pipe throws, return `onFailure` — the host's OWN
+ * fail-safe response — so a crashed hook degrades the way THAT host expects
+ * (claude/codex fail OPEN = exit 0; amp fails to ASK = exit 1) instead of a
+ * single shared default. This is the deliberate, necessary recovery the whole
+ * per-host split exists for, not a blanket swallow.
+ * @param {import("../src/control-plane.mjs").Adapter} adapter
+ * @param {string} rawInput
+ * @param {import("../src/control-plane.mjs").NativeResponse} onFailure
+ * @returns {import("../src/control-plane.mjs").NativeResponse}
+ */
+export function renderHookResponse(adapter, rawInput, onFailure) {
+  try {
+    const event = adapter.parse(JSON.parse(rawInput));
+    return adapter.render(demoJudge(event), event);
+  } catch {
+    return onFailure;
+  }
+}
+
+/**
+ * Emit a {@link NativeResponse} to the host: write the native stdout body when
+ * the transport has one, then exit with the transport's exit code.
+ * @param {import("../src/control-plane.mjs").NativeResponse} response
+ * @returns {never}
+ */
+export function emit(response) {
+  if (response.stdout !== undefined)
+    process.stdout.write(JSON.stringify(response.stdout));
+  process.exit(response.exit_code);
+}

package/package.json

@@ -0,0 +1,109 @@
+{
+  "name": "agent-control-plane-core",
+  "version": "0.1.0",
+  "description": "Vendor-neutral control-plane contract for coding agents: a normalized ToolCallEvent/Verdict schema with per-agent adapters (Claude Code, Codex) and a conformance suite.",
+  "type": "module",
+  "license": "MIT",
+  "packageManager": "pnpm@11.8.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./src/index.mjs",
+  "types": "./types/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.mts",
+      "import": "./src/index.mjs"
+    },
+    "./claude": {
+      "types": "./types/adapters/claude.d.mts",
+      "import": "./src/adapters/claude.mjs"
+    },
+    "./codex": {
+      "types": "./types/adapters/codex.d.mts",
+      "import": "./src/adapters/codex.mjs"
+    },
+    "./amp": {
+      "types": "./types/adapters/amp.d.mts",
+      "import": "./src/adapters/amp.mjs"
+    },
+    "./gemini": {
+      "types": "./types/adapters/gemini.d.mts",
+      "import": "./src/adapters/gemini.mjs"
+    },
+    "./conformance": {
+      "types": "./types/conformance.d.mts",
+      "import": "./src/conformance.mjs"
+    }
+  },
+  "files": [
+    "src",
+    "types",
+    "bin"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "codex",
+    "agent",
+    "control-plane",
+    "hooks",
+    "adapter",
+    "guardrail"
+  ],
+  "scripts": {
+    "prepare": "git config core.hooksPath .hooks",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "pnpm build",
+    "test": "node --test test/*.test.mjs",
+    "test:coverage": "c8 node --test test/*.test.mjs",
+    "check": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "lint-staged": {
+    "*.{css,scss}": [
+      "prettier --write"
+    ],
+    "*.json": [
+      "prettier --write"
+    ],
+    "*.json.example": [
+      "prettier --write --parser json"
+    ],
+    "*.{js,jsx,ts,tsx,mjs}": [
+      "prettier --write",
+      "eslint --fix"
+    ],
+    "*.{yaml,yml}": [
+      "prettier --write"
+    ],
+    "*.md": [
+      "prettier --write"
+    ],
+    ".claude/skills/*/SKILL.md": [
+      ".hooks/lint-skills.sh"
+    ],
+    "{*.sh,.hooks/*}": [
+      "shfmt -i 2 -w"
+    ],
+    "*.py": [
+      "ruff check --fix",
+      "ruff format"
+    ]
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.0.1",
+    "@commitlint/config-conventional": "^21.0.1",
+    "@eslint/js": "^9.13.0",
+    "@types/node": "^22.7.0",
+    "c8": "^10.1.2",
+    "eslint": "^9.13.0",
+    "fast-check": "^3.22.0",
+    "globals": "^15.11.0",
+    "lint-staged": "^17.0.5",
+    "prettier": "^3.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/src/adapters/amp.mjs

@@ -0,0 +1,82 @@
+/**
+ * The Amp adapter — EXTERNAL_HOOK translator with a pure exit-code transport.
+ *
+ * Amp's `amp.permissions` `delegate` rule invokes a helper on PATH; the helper's
+ * EXIT CODE is the whole decision — 0 allow / 1 ask / 2 reject — with no JSON
+ * body. Managed pin: /etc/ampcode/managed-settings.json overrides user+workspace
+ * (pin the delegate rule there). Transcript is server-canonical `--stream-json`.
+ *
+ * This adapter is what proves the transport split earns its keep: the normalized
+ * ToolCallEvent/Verdict are identical to Claude's, but `render` carries the
+ * decision in `exit_code` with no `stdout` at all.
+ */
+
+import {
+  EventKind,
+  Decision,
+  IntegrationMode,
+  makeEvent,
+  normalizeVerdict,
+  nativeResponse,
+  collectPassthrough,
+  asObject,
+  asStringOrNull,
+} from "../control-plane.mjs";
+
+/** @typedef {import("../control-plane.mjs").ToolCallEvent} ToolCallEvent */
+/** @typedef {import("../control-plane.mjs").Verdict} Verdict */
+/** @typedef {import("../control-plane.mjs").EventMeta} EventMeta */
+/** @typedef {import("../control-plane.mjs").NativeResponse} NativeResponse */
+
+export const AGENT = "amp";
+export const INTEGRATION_MODE = IntegrationMode.EXTERNAL_HOOK;
+
+// Amp invokes the delegate for a tool call; the payload carries the tool name +
+// input and the session context. Pinned by fixtures/amp.json.
+const CONSUMED = new Set(["tool", "input", "session_id", "cwd"]);
+
+/**
+ * @param {any} native
+ * @returns {ToolCallEvent}
+ */
+export function parse(native) {
+  const raw = asObject(native);
+  /** @type {EventMeta} */
+  const meta = {
+    agent: AGENT,
+    native_event: "delegate",
+    integration_mode: INTEGRATION_MODE,
+    primary_gate_present: true,
+    passthrough: collectPassthrough(raw, CONSUMED),
+  };
+  if (typeof raw.session_id === "string") meta.session_id = raw.session_id;
+  if (typeof raw.cwd === "string") meta.cwd = raw.cwd;
+  return makeEvent({
+    event: EventKind.PRE_TOOL,
+    tool: asStringOrNull(raw.tool),
+    input: asObject(raw.input),
+    response: undefined,
+    this_call_vetoable: true,
+    meta,
+  });
+}
+
+/**
+ * Render into Amp's pure exit-code transport: the decision is the exit code,
+ * with no stdout body. `reason` has no native channel here, so it is dropped
+ * (Amp surfaces the helper's own stderr). No `soleGate` option — an allow
+ * already renders as exit 0 either way, so there's no distinct "real approve"
+ * signal for this transport to opt into.
+ * @param {Verdict} verdict
+ * @param {ToolCallEvent} event
+ * @returns {NativeResponse}
+ */
+export function render(verdict, event) {
+  const vd = normalizeVerdict(verdict);
+  const enforced = vd.decision === Decision.DENY && event.this_call_vetoable;
+  const exit_code = enforced ? 2 : vd.decision === Decision.ASK ? 1 : 0;
+  return nativeResponse({ transport: INTEGRATION_MODE, exit_code, enforced });
+}
+
+/** @type {import("../control-plane.mjs").Adapter} */
+export const ampAdapter = { AGENT, INTEGRATION_MODE, parse, render };