Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

feat(guardrails): make tool-lane hooks installable, gated as content-bearing (l5)

Andy Paviaa12e72b59976
diff --git a/charts/clerum-crds/crds/llmhook.yaml b/charts/clerum-crds/crds/llmhook.yaml
index fb4217a14..6c02f0271 100644
--- a/charts/clerum-crds/crds/llmhook.yaml
+++ b/charts/clerum-crds/crds/llmhook.yaml
@@ -157,8 +157,15 @@ spec:
lifecyclePoints:
type: array
minItems: 1
- maxItems: 4
- description: Lifecycle points this hook subscribes to.
+ maxItems: 6
+ description: >-
+ Lifecycle points this hook subscribes to. The first four are the
+ LLM lane (§8.1); preToolUse/postToolUse are the tool lane (§6.2)
+ and are accepted here because Host.spec.guardrails.hooks already
+ keys on them and mcp-host already maps them
+ (guardrailHookResolver PHASE_TO_POINT). Omitting them made an
+ installed tool-lane hook unrepresentable: the apiserver rejected
+ the CR the install saga tried to create.
items:
type: string
enum:
@@ -166,6 +173,8 @@ spec:
- moderate
- postCallSuccess
- onError
+ - preToolUse
+ - postToolUse
contentAccess:
type: string
enum:
@@ -248,9 +257,15 @@ spec:
# contentAccess: metadata is contradictory for an inherently content-bearing
# point. An absent field passes (absent is read as `content`), so this is
# non-breaking for existing CRs; it only rejects an explicit metadata on
- # moderate/post/onError.
- - rule: "!has(self.contentAccess) || self.contentAccess == 'content' || !self.lifecyclePoints.exists(p, p == 'moderate' || p == 'postCallSuccess' || p == 'onError')"
- message: "contentAccess: metadata is not allowed for a hook using moderate/postCallSuccess/onError (those points are inherently content-bearing)"
+ # a content-bearing point.
+ #
+ # The tool-lane points are listed because the tool lane has no metadata
+ # projection at all: preToolUse receives {tool, arguments} and postToolUse
+ # receives the tool result, and remoteToolHook never consults
+ # contentAccess. Declaring `metadata` there would describe a projection
+ # that does not exist.
+ - rule: "!has(self.contentAccess) || self.contentAccess == 'content' || !self.lifecyclePoints.exists(p, p == 'moderate' || p == 'postCallSuccess' || p == 'onError' || p == 'preToolUse' || p == 'postToolUse')"
+ message: "contentAccess: metadata is not allowed for a hook using moderate/postCallSuccess/onError/preToolUse/postToolUse (those points are inherently content-bearing)"
status:
type: object
description: >-
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 971556d02..94317002b 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.469",
+ "version": "0.1.470",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.469",
+ "version": "0.1.470",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/image-policy": "file:../packages/image-policy",
diff --git a/control-api/package.json b/control-api/package.json
index 4d711e8cd..32f95cd2f 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.469",
+ "version": "0.1.470",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/routes/admin/__tests__/installHookTrust.test.ts b/control-api/src/routes/admin/__tests__/installHookTrust.test.ts
index 6f424ccb3..aeed720d7 100644
--- a/control-api/src/routes/admin/__tests__/installHookTrust.test.ts
+++ b/control-api/src/routes/admin/__tests__/installHookTrust.test.ts
@@ -70,6 +70,20 @@ describe('content-bearing classification (§8.4/§8.7)', () => {
expect(isContentBearingHook(undefined)).toBe(false)
expect(isContentBearingHook(['somethingElse'])).toBe(false)
})
+
+ // The tool lane has no metadata projection: preToolUse receives {tool, arguments}
+ // and postToolUse receives the tool result, and remoteToolHook never consults
+ // contentAccess. Classified content-free, a preToolUse-only hook with egress at
+ // low trust passed the gate while reading every tool argument at runtime.
+ it('both tool-lane points are always content-bearing', () => {
+ expect(isContentBearingHook(['preToolUse'])).toBe(true)
+ expect(isContentBearingHook(['postToolUse'])).toBe(true)
+ })
+
+ it('contentAccess: metadata cannot make a tool-lane point content-free', () => {
+ expect(isContentBearingHook(['preToolUse'], 'metadata')).toBe(true)
+ expect(isContentBearingHook(['postToolUse'], 'metadata')).toBe(true)
+ })
})
describe('content/egress separation gate (§8.4)', () => {
@@ -118,6 +132,43 @@ describe('content/egress separation gate (§8.4)', () => {
).toBe(false)
})
+ // A tool-lane hook reads tool arguments and results, so egress at low trust is
+ // the same exfiltration shape the LLM-lane points are gated on. Before the tool
+ // points were classified content-bearing this returned false and the install
+ // was admitted.
+ it('preToolUse + egress at low trust → requires high (blocked)', () => {
+ expect(
+ contentEgressRequiresHighTrust({
+ lifecyclePoints: ['preToolUse'],
+ hasEgress: true,
+ isRemote: false,
+ trustLevel: 'low',
+ })
+ ).toBe(true)
+ })
+
+ it('postToolUse + remote target at mid trust → requires high (blocked)', () => {
+ expect(
+ contentEgressRequiresHighTrust({
+ lifecyclePoints: ['postToolUse'],
+ hasEgress: false,
+ isRemote: true,
+ trustLevel: 'mid',
+ })
+ ).toBe(true)
+ })
+
+ it('a tool-lane hook with no egress at low trust → allowed', () => {
+ expect(
+ contentEgressRequiresHighTrust({
+ lifecyclePoints: ['preToolUse', 'postToolUse'],
+ hasEgress: false,
+ isRemote: false,
+ trustLevel: 'low',
+ })
+ ).toBe(false)
+ })
+
it('egress WITHOUT content at low trust → allowed (nothing to leak)', () => {
expect(
contentEgressRequiresHighTrust({
diff --git a/control-api/src/routes/admin/registry.ts b/control-api/src/routes/admin/registry.ts
index 2d25b8b40..a477fd59c 100644
--- a/control-api/src/routes/admin/registry.ts
+++ b/control-api/src/routes/admin/registry.ts
@@ -161,14 +161,28 @@ const HOOK_TRUST_ORDER: Record<string, number> = { low: 0, mid: 1, high: 2 }
// Lifecycle points that ALWAYS receive message/response content (§8.4/§8.7). preCall
// is the one point with two flavors — content-bearing unless the hook declares
// `contentAccess: metadata` — so it is handled separately in isContentBearingHook.
-const INHERENTLY_CONTENT_POINTS = new Set(['moderate', 'postCallSuccess', 'onError'])
+//
+// The tool-lane points (§6.2) are here because the tool lane has NO metadata
+// projection: preToolUse receives {tool, arguments} and postToolUse receives the
+// tool result, and remoteToolHook never consults contentAccess. Leaving them out
+// classified a preToolUse-only hook as content-free, so a low-trust third-party
+// hook with egressBindings or a remote target passed the content/egress gate
+// while reading every tool argument and result at runtime.
+const INHERENTLY_CONTENT_POINTS = new Set([
+ 'moderate',
+ 'postCallSuccess',
+ 'onError',
+ 'preToolUse',
+ 'postToolUse',
+])
/**
* §8.4/§8.7 — does this hook receive message/response CONTENT at any of its
- * lifecycle points? moderate/postCallSuccess/onError always do; preCall does
- * unless it explicitly declared `contentAccess: metadata` (mcp-host's projection
- * enforces the same rule, so the gate and the runtime agree — the two land
- * together, §12.4). Absent contentAccess ⇒ content-bearing (conservative).
+ * lifecycle points? moderate/postCallSuccess/onError and both tool-lane points
+ * always do; preCall does unless it explicitly declared `contentAccess: metadata`
+ * (mcp-host's projection enforces the same rule, so the gate and the runtime
+ * agree — the two land together, §12.4). Absent contentAccess ⇒ content-bearing
+ * (conservative).
*/
export function isContentBearingHook(
lifecyclePoints: string[] | undefined,