agent-control-plane-core 0.1.0

package/src/control-plane.mjs

@@ -0,0 +1,299 @@
+/**
+ * The vendor-neutral control-plane contract.
+ *
+ * This is the published seam between an agent's native hook/tool-call protocol
+ * and claude-guard's guardrails (monitor, deny-match, redaction, sanitizers).
+ * It defines TWO normalized shapes — {@link ToolCallEvent} (what an agent is
+ * about to / just did) and {@link Verdict} (what the guardrail decided) — plus
+ * the {@link Adapter} pair that translates a specific agent's protocol to and
+ * from them. Every downstream consumer imports THESE types, never an agent's
+ * raw hook JSON; the agent-specific field names live only in that agent's
+ * adapter (see adapter-claude.mjs / adapter-codex.mjs).
+ *
+ * DRIFT DISCIPLINE — the reason the seam earns its keep. An agent protocol
+ * drifts additively and independently (N agents, N release cadences). So an
+ * adapter's `parse` MUST NOT throw on an event type or tool-input field it does
+ * not model: the unmodelled remainder is carried through verbatim (an unknown
+ * event becomes {@link EventKind.UNKNOWN} with its native name preserved; extra
+ * top-level fields land in `meta.passthrough`). An additive upstream change is
+ * then a no-op here, not an outage. The core models ONLY the stable middle:
+ * four event kinds, three decisions, and the Bash/Edit/Write/Read/WebFetch tool
+ * inputs. Exotic per-agent tools pass through untouched.
+ *
+ * Dependency-free on purpose, so a fail-closed hook can import it without
+ * dragging in eager config-file reads.
+ *
+ * VERSIONING — this module IS the frozen contract (its own SSOT, no parallel
+ * schema file to drift). Adapters and guardrail consumers are built against it
+ * in parallel, so its shapes are stable: {@link EventKind}, {@link Decision},
+ * and {@link MODELED_TOOLS} are frozen, and {@link SCHEMA_VERSION} /
+ * {@link CONTROL_PLANE_SCHEMA} are pinned (control-plane.test.mjs asserts the
+ * exact values, so any shape change is a deliberate, reviewed version bump).
+ * ADDING to the contract (a new optional field, a new modeled tool) is
+ * backward-compatible and stays at v1; RENAMING or REMOVING a field, or
+ * changing a decision/event vocabulary, is breaking and bumps the version.
+ */
+
+/** Wire identifier for this schema version; bump on a breaking shape change. */
+export const CONTROL_PLANE_SCHEMA = "control-plane/v1";
+
+/** Numeric schema version stamped onto every {@link ToolCallEvent}. */
+export const SCHEMA_VERSION = 1;
+
+/**
+ * The normalized event kinds the core models. A native event that maps to none
+ * of these is carried as {@link EventKind.UNKNOWN} with its native name kept in
+ * `meta.native_event`.
+ */
+export const EventKind = Object.freeze({
+  PRE_TOOL: "pre_tool",
+  POST_TOOL: "post_tool",
+  PROMPT_SUBMIT: "prompt_submit",
+  SESSION_START: "session_start",
+  UNKNOWN: "unknown",
+});
+
+/** The normalized verdict decisions a guardrail can return. */
+export const Decision = Object.freeze({
+  ALLOW: "allow",
+  DENY: "deny",
+  ASK: "ask",
+});
+
+/**
+ * Tools whose input shape the core models. Every other tool passes through
+ * unmodelled — its input object is preserved verbatim and no field is required.
+ */
+export const MODELED_TOOLS = Object.freeze([
+  "Bash",
+  "Edit",
+  "Write",
+  "Read",
+  "WebFetch",
+]);
+
+/**
+ * How a guardrail ATTACHES to an agent — the transport, kept separate from the
+ * normalized decision so the judge/Verdict core stays transport-agnostic:
+ *   - EXTERNAL_HOOK: the agent shells out to a hook (stdin JSON → deny body /
+ *     exit code). The decision can pre-empt the tool call.
+ *   - IN_PROCESS: an embedded analyzer or a driven confirm/reject loop over the
+ *     agent's own API. Can pre-empt.
+ *   - OBSERVE_ONLY: transcript reader; cannot pre-empt, so its Verdict is
+ *     advisory — the hard stop is the sandbox, not the hook.
+ */
+export const IntegrationMode = Object.freeze({
+  EXTERNAL_HOOK: "external_hook",
+  IN_PROCESS: "in_process",
+  OBSERVE_ONLY: "observe_only",
+});
+
+/**
+ * @typedef {object} EventMeta
+ * @property {string} agent producing agent id ("claude", "codex", …)
+ * @property {string} native_event original native event name, preserved verbatim
+ * @property {"external_hook"|"in_process"|"observe_only"} integration_mode how the guardrail attaches
+ * @property {boolean} primary_gate_present the agent's own native gate already ran (⇒ the monitor is a SECOND opinion; the LLM call can be skipped when the native gate already blocked)
+ * @property {string} [session_id]
+ * @property {string} [cwd]
+ * @property {string} [permission_mode]
+ * @property {string} [transcript_path]
+ * @property {Record<string, unknown>} passthrough unmodelled native top-level fields, verbatim
+ */
+
+/**
+ * The result of rendering a {@link Verdict} for a specific agent's transport —
+ * the ATTACH mechanism, not the decision. A caller applies whichever channels
+ * are present: write `stdout`, exit with `exit_code`, or `throw`.
+ * @typedef {object} NativeResponse
+ * @property {"external_hook"|"in_process"|"observe_only"} transport
+ * @property {number} exit_code process exit code carrying the decision (0 = proceed)
+ * @property {boolean} enforced whether THIS render actually blocks (false ⇒ advisory only)
+ * @property {unknown} [stdout] native JSON body to write to stdout, when the transport uses one
+ * @property {{ message: string }} [throw_] a thrown-error block signal (plugin transports, e.g. opencode)
+ * @property {ConfigFallback} [fallback] an out-of-band enforcement the adapter ALSO requires (external pin / config deny-wildcards)
+ */
+
+/**
+ * An enforcement the adapter cannot express in-band and so hands to the sandbox
+ * to apply out-of-band — because the in-agent hook has a documented hole:
+ *   - `external_pin`: the agent can re-enable/override its own hook, so the
+ *     sandbox must pin it from OUTSIDE (read-only config mount / PATH-shadow).
+ *   - `config_deny`: an in-agent throw doesn't reach every path (e.g. opencode
+ *     MCP tools / subagents), so a config-level deny-by-name wildcard is ALSO
+ *     required. `uncovered` names paths still not covered (a logged, known gap).
+ * @typedef {object} ConfigFallback
+ * @property {"external_pin"|"config_deny"} kind
+ * @property {string} reason
+ * @property {string[]} [deny_globs] tool-NAME globs to deny at config level (config_deny)
+ * @property {string[]} [uncovered] paths this fallback still cannot reach (known gap)
+ */
+
+/**
+ * A normalized, agent-agnostic view of one agent event.
+ * @typedef {object} ToolCallEvent
+ * @property {number} schema_version stamped {@link SCHEMA_VERSION}
+ * @property {"pre_tool"|"post_tool"|"prompt_submit"|"session_start"|"unknown"} event
+ * @property {string|null} tool tool name (null for prompt/session events)
+ * @property {Record<string, unknown>} input passthrough tool input; a submitted prompt is folded into `input.prompt`
+ * @property {unknown} [response] tool output, post_tool only (string or structured), verbatim
+ * @property {boolean} this_call_vetoable false ⇒ the guardrail cannot veto THIS call; a monitor must auto-degrade deny to notify, and any render of it stays advisory (never `enforced`)
+ * @property {EventMeta} meta
+ */
+
+/**
+ * A normalized guardrail decision.
+ * @typedef {object} Verdict
+ * @property {"allow"|"deny"|"ask"} decision
+ * @property {Record<string, unknown>} [mutated_input] replacement tool input
+ * @property {string} [additional_context] extra context to splice into the agent's stream
+ * @property {string} [reason] human-readable rationale (shown on deny/ask)
+ */
+
+/**
+ * The translator for one agent's protocol. `parse` maps a native event to a
+ * {@link ToolCallEvent} (never throwing on unmodelled input, stamping the
+ * integration mode / enforcement flags on `meta`); `render` maps a {@link Verdict}
+ * to that agent's native transport ({@link NativeResponse}), not just a JSON body.
+ * @typedef {object} Adapter
+ * @property {string} AGENT
+ * @property {"external_hook"|"in_process"|"observe_only"} INTEGRATION_MODE
+ * @property {(native: any) => ToolCallEvent} parse
+ * @property {(verdict: Verdict, event: ToolCallEvent, options?: { soleGate?: boolean }) => NativeResponse} render
+ */
+
+/**
+ * Build a normalized {@link ToolCallEvent}, stamping the schema version. Pure —
+ * adapters pass already-normalized parts. `response` is omitted unless defined
+ * so a pre_tool event has no `response` key at all.
+ * @param {{ event: string, tool: string|null, input: Record<string, unknown>, response?: unknown, this_call_vetoable: boolean, meta: EventMeta }} parts
+ * @returns {ToolCallEvent}
+ */
+export function makeEvent({
+  event,
+  tool,
+  input,
+  response,
+  this_call_vetoable,
+  meta,
+}) {
+  /** @type {ToolCallEvent} */
+  const evt = {
+    schema_version: SCHEMA_VERSION,
+    event: /** @type {ToolCallEvent["event"]} */ (event),
+    tool,
+    input,
+    this_call_vetoable,
+    meta,
+  };
+  if (response !== undefined) evt.response = response;
+  return evt;
+}
+
+/**
+ * Validate and normalize a {@link Verdict}. The decision must be one of
+ * allow/deny/ask — a verdict is produced internally, so an out-of-range
+ * decision is a bug and throws (fail loud), unlike the pass-through tolerance
+ * `parse` extends to untrusted upstream events. Returns a fresh object carrying
+ * only the modeled optional fields that are present; never mutates its input.
+ * @param {Verdict} verdict
+ * @returns {Verdict}
+ */
+export function normalizeVerdict(verdict) {
+  const { decision } = verdict;
+  if (
+    decision !== Decision.ALLOW &&
+    decision !== Decision.DENY &&
+    decision !== Decision.ASK
+  ) {
+    throw new Error(
+      `control-plane: invalid verdict decision ${JSON.stringify(decision)}`,
+    );
+  }
+  /** @type {Verdict} */
+  const out = { decision };
+  if (verdict.mutated_input !== undefined)
+    out.mutated_input = verdict.mutated_input;
+  if (verdict.additional_context !== undefined)
+    out.additional_context = verdict.additional_context;
+  if (verdict.reason !== undefined) out.reason = verdict.reason;
+  return out;
+}
+
+/**
+ * Return a shallow copy of `native` with the `consumed` keys removed — the
+ * unmodelled remainder an adapter carries in `meta.passthrough` so an additive
+ * upstream field survives instead of being silently dropped.
+ * @param {Record<string, unknown>} native
+ * @param {Set<string>} consumed
+ * @returns {Record<string, unknown>}
+ */
+export function collectPassthrough(native, consumed) {
+  /** @type {Record<string, unknown>} */
+  const rest = {};
+  for (const [key, val] of Object.entries(native)) {
+    if (!consumed.has(key)) rest[key] = val;
+  }
+  return rest;
+}
+
+// ─── Coercion primitives ─────────────────────────────────────────────────────
+// Adapters read untrusted native JSON: a field may be absent, null, or the wrong
+// type. These coerce to a safe shape (never throw) so a malformed field degrades
+// to a well-defined default instead of taking the parse down.
+
+/**
+ * The value if it is a plain (non-array) object, else `{}`.
+ * @param {unknown} value
+ * @returns {Record<string, unknown>}
+ */
+export function asObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? /** @type {Record<string, unknown>} */ (value)
+    : {};
+}
+
+/**
+ * The value if it is a string, else `null`.
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+export function asStringOrNull(value) {
+  return typeof value === "string" ? value : null;
+}
+
+/**
+ * The value if it is a string, else `fallback`.
+ * @param {unknown} value
+ * @param {string} fallback
+ * @returns {string}
+ */
+export function asString(value, fallback) {
+  return typeof value === "string" ? value : fallback;
+}
+
+/**
+ * Assemble a {@link NativeResponse}, omitting absent optional channels so a
+ * pure exit-code transport carries no `stdout` key and vice versa.
+ * @param {{ transport: string, exit_code: number, enforced: boolean, stdout?: unknown, throw_?: {message:string}, fallback?: ConfigFallback }} parts
+ * @returns {NativeResponse}
+ */
+export function nativeResponse({
+  transport,
+  exit_code,
+  enforced,
+  stdout,
+  throw_,
+  fallback,
+}) {
+  /** @type {NativeResponse} */
+  const out = {
+    transport: /** @type {NativeResponse["transport"]} */ (transport),
+    exit_code,
+    enforced,
+  };
+  if (stdout !== undefined) out.stdout = stdout;
+  if (throw_ !== undefined) out.throw_ = throw_;
+  if (fallback !== undefined) out.fallback = fallback;
+  return out;
+}

package/src/fixtures/amp.json

@@ -0,0 +1,121 @@
+{
+  "agent": "amp",
+  "cases": [
+    {
+      "name": "delegate Bash, exit-code transport, all verdicts",
+      "native": {
+        "tool": "Bash",
+        "input": {
+          "command": "ls -la"
+        },
+        "session_id": "a1",
+        "cwd": "/w"
+      },
+      "event": {
+        "schema_version": 1,
+        "event": "pre_tool",
+        "tool": "Bash",
+        "input": {
+          "command": "ls -la"
+        },
+        "this_call_vetoable": true,
+        "meta": {
+          "agent": "amp",
+          "native_event": "delegate",
+          "integration_mode": "external_hook",
+          "primary_gate_present": true,
+          "passthrough": {},
+          "session_id": "a1",
+          "cwd": "/w"
+        }
+      },
+      "render": {
+        "allow": {
+          "verdict": {
+            "decision": "allow"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false
+          }
+        },
+        "deny": {
+          "verdict": {
+            "decision": "deny",
+            "reason": "blocked"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 2,
+            "enforced": true
+          }
+        },
+        "ask": {
+          "verdict": {
+            "decision": "ask",
+            "reason": "confirm"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 1,
+            "enforced": false
+          }
+        },
+        "mutation": {
+          "verdict": {
+            "decision": "allow",
+            "mutated_input": {
+              "command": "ls"
+            }
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false
+          }
+        }
+      }
+    },
+    {
+      "name": "delegate Read, bare meta + passthrough",
+      "native": {
+        "tool": "Read",
+        "input": {
+          "file_path": "/x"
+        },
+        "extra_meta": 7
+      },
+      "event": {
+        "schema_version": 1,
+        "event": "pre_tool",
+        "tool": "Read",
+        "input": {
+          "file_path": "/x"
+        },
+        "this_call_vetoable": true,
+        "meta": {
+          "agent": "amp",
+          "native_event": "delegate",
+          "integration_mode": "external_hook",
+          "primary_gate_present": true,
+          "passthrough": {
+            "extra_meta": 7
+          }
+        }
+      },
+      "render": {
+        "allow": {
+          "verdict": {
+            "decision": "allow"
+          },
+          "native": {
+            "transport": "external_hook",
+            "exit_code": 0,
+            "enforced": false
+          }
+        }
+      }
+    }
+  ]
+}