Skip to content

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

TypeScript

docs: update docs for tool-lane hook guards and Host phase scoping

Jose Gabriel Ramirez Encinas2354146aafeb
diff --git a/docs/crds/host.md b/docs/crds/host.md
index 3c359d13a..b459a2863 100644
--- a/docs/crds/host.md
+++ b/docs/crds/host.md
@@ -56,12 +56,12 @@ represents a single LLM agent instance (an "agent" in Control UI and the Desktop
| Field | Description |
|-------|-------------|
| `guardrails.rules[]` | Tool-lane rules `{id, action: allow\|ask\|deny, reasonCode, match: {tool, arguments[]}}`. Every matching rule contributes and the strictest decision wins; array order is not precedence. Once any rule exists, a call that matches none resolves to `ask`. |
-| `guardrails.hooks.<phase>[]` | Installed [LlmHook](llmhook.md) references `{id, digest}` per phase: `preToolUse`, `postToolUse`, `preCall`, `moderate`, `postCallSuccess`, `onError`. A referenced hook runs at every point in its own `lifecyclePoints`. |
+| `guardrails.hooks.<phase>[]` | Installed [LlmHook](llmhook.md) references `{id, digest}` per phase: `preToolUse`, `postToolUse`, `preCall`, `moderate`, `postCallSuccess`, `onError`. A referenced hook runs only at the phases it is referenced under that its own `lifecyclePoints` also declare. |
| `guardrails.builtins[]` | First-party hooks compiled into mcp-host (e.g. `prompt-shaping`, `token-trim`). |
| `guardrails.minInstalledHookTrustLevel` | `low` \| `mid` \| `high`: minimum trust level for hooks installed onto this Host. Checked by control-api when a hook is installed or upgraded, not at runtime. |
| `guardrails.capabilityCeiling[]` | Upper bound on the capabilities an install may grant: `may_deny`, `may_rewrite`, `may_substitute_result`, `may_add_context`. Checked at install/upgrade, not at runtime, so a hand-edited LlmHook is not re-validated against it. |
| `guardrails.approvalPolicies[]` | Accepted by the schema (`cli_only`, `channel_users`, `designated_approvers`) but not read by mcp-host today; `ask` decisions use `spec.approval`, or mcp-host's `CLERUM_APPROVAL_CONFIG` when `spec.approval` is unset. |
-| `guardrails.limits` | `maxRules` (100) and `maxHookTimeoutMs` (5000, the transport timeout for each hook call on both lanes) are enforced; LLM-lane hooks also have a fixed 15000 ms hard deadline, so a larger value has no effect there. `maxHookOutputBytes` (65536 when a `limits` object is present; otherwise 1 MiB) caps `moderate`, `postCallSuccess` and `onError` hook responses. It does not apply to `preCall` (always 5 MiB) or to tool-lane hooks (1 MiB). `maxHooksPerPhase` is accepted but not enforced. |
+| `guardrails.limits` | `maxRules` (100) and `maxHookTimeoutMs` (5000, the transport timeout for each hook call on both lanes) are enforced; every hook call also has a fixed 15000 ms hard deadline, so a larger value has no effect. `maxHookOutputBytes` (65536 when a `limits` object is present; otherwise 1 MiB) caps `moderate`, `postCallSuccess` and `onError` hook responses. It does not apply to `preCall` (always 5 MiB) or to tool-lane hooks (1 MiB). `maxHooksPerPhase` is accepted but not enforced. |
Apply the CRD before any component writes `spec.guardrails`: the API server
silently prunes fields an older CRD does not know.
diff --git a/docs/crds/llmhook.md b/docs/crds/llmhook.md
index 1e4e12cad..37a5c3370 100644
--- a/docs/crds/llmhook.md
+++ b/docs/crds/llmhook.md
@@ -50,7 +50,7 @@ either at runtime.
| `spec.contentAccess` | `metadata` \| `content` | no | What the hook receives. **Omitting it means `content`.** Only a `preCall`-only hook may declare `metadata` (model, params and usage, no message bodies). |
| `spec.order` | int | no (default 100) | Order within a phase; lower runs first. |
| `spec.failMode` | `open` \| `closed` | no (CRD default `closed`) | Behaviour when the hook is unavailable. A hook with `may_deny` must fail closed. The Control UI install form preselects the hook author's suggested fail mode, or `open`; granting `may_deny` forces `closed`. |
-| `spec.timeoutMs` | int | no (default 5000) | Accepted but not used today; the transport timeout is the Host's `guardrails.limits.maxHookTimeoutMs` (default 5000). LLM-lane calls also stop at a fixed 15000 ms hard deadline. |
+| `spec.timeoutMs` | int | no (default 5000) | Accepted but not used today; the transport timeout is the Host's `guardrails.limits.maxHookTimeoutMs` (default 5000). Every call also stops at a fixed 15000 ms hard deadline. |
| `spec.onUnavailable` | object | no | Circuit breaker: `mode` (`strict` \| `breaker`, default `strict`), `failureThreshold` (default 5), `cooldownMs` (default 30000). |
| `spec.capabilities` | string[] | no | Admin-granted: `may_deny`, `may_rewrite`, `may_substitute_result`, `may_add_context`. Checked against the Host's `guardrails.capabilityCeiling` at install time; mcp-host ignores response actions the hook was not granted. |
| `spec.config` | object | no | Opaque hook settings. Never used as a trust input. |
@@ -70,7 +70,7 @@ either at runtime.
| Field | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `status.observedDigest` | Image digest actually running. For `image` targets whose Host reference pins `Host.spec.guardrails.hooks[].digest`, mcp-host compares the two. On a mismatch the hook is quarantined at LLM-lane points: calls are treated as unavailable, so a `may_deny` hook denies and an advisory hook contributes nothing. Tool-lane points are not quarantined. |
+| `status.observedDigest` | Image digest actually running. For `image` targets whose Host reference pins `Host.spec.guardrails.hooks[].digest`, mcp-host compares the two. On a mismatch the hook is quarantined on both lanes: calls are treated as unavailable without dialing, so a `may_deny` hook with `failMode: closed` denies and an advisory hook contributes nothing. |
| `status.readyReplicas` | Ready replicas (image targets only). |
| `status.lastReconciled` | Timestamp of the last successful reconcile. |
| `status.conditions[]` | A single `Ready` condition with `observedGeneration`; its `reason` is one of `NoWorkload`, `Deploying`, `Ready`, `DuplicatePath`, `SecretNotFound`, `InvalidEgress`, `ReconcileError`. |
diff --git a/docs/how-to/configure-guardrails.md b/docs/how-to/configure-guardrails.md
index e1556abf1..c9e5810b8 100644
--- a/docs/how-to/configure-guardrails.md
+++ b/docs/how-to/configure-guardrails.md
@@ -213,7 +213,8 @@ Every other org is capped at `CONTROL_API_DEFAULT_HOOK_TRUST_CAP` (default
Open **Agents** → the agent → **Advanced** → **Hooks**. The table lists each
`{hook, phase}` reference. Row actions are **View details** and
-**Remove from \<phase\>**. Removing a reference leaves the hook installed. To
+**Remove from \<phase\>**. Removing a reference stops the hook at that
+phase but leaves it installed. To
remove it from the cluster, uninstall it on **Installed Guardrails**. That
strips the reference from every Host first, then deletes the CR. **Add
hook** goes to the same Marketplace list.
@@ -246,25 +247,30 @@ the fields it does not edit when it saves.
fail mode (or `open`), and **May deny** forces `closed`.
- **Timeouts.** The Host's `limits.maxHookTimeoutMs` (default 5000 ms) is
- the transport timeout for each hook call on both lanes. LLM-lane hooks
- also have a fixed 15000 ms hard deadline, so on that lane a value above
- 15000 has no effect: the call reports unavailable after 15 seconds.
+ the transport timeout for each hook call on both lanes. Every hook call
+ also has a fixed 15000 ms hard deadline, so a value above 15000 has no
+ effect: the call reports unavailable after 15 seconds.
mcp-host does not read `LlmHook.spec.timeoutMs`.
- **Circuit breaker.** `onUnavailable.mode: breaker` (threshold 5, cooldown
30000 ms by default) short-circuits a down hook without dialing it. It
- applies only to LLM-lane hooks **without** `may_deny`. A deny-capable hook
- is always dialed.
+ applies on both lanes, only to hooks **without** `may_deny`, and a hook
+ has one breaker state shared by both lanes. A deny-capable hook is always
+ dialed.
- **Digest binding.** For image hooks whose Host reference pins a `digest`,
mcp-host compares it with `LlmHook.status.observedDigest` (once that is
- set). On a mismatch it quarantines the hook. Quarantine is enforced on the
- LLM lane only: there every call reports unavailable, so the fail-mode
- rules above apply. A tool-lane hook (`preToolUse`/`postToolUse`) with a
- mismatched digest is still dialed. The same quarantine applies to a
+ set). On a mismatch it quarantines the hook on both lanes: every call
+ reports unavailable without dialing, so the fail-mode rules above apply.
+ The same quarantine applies to a
co-located hook that lost a `DuplicatePath` collision. Upgrade with
`POST /admin/registry/upgrade-hook`, which bumps the CR and every Host's
digest together.
-- **The Host phase key does not filter.** mcp-host collects hook ids from
- all phases. The `LlmHook`'s own `lifecyclePoints` decide where it runs.
+- **The Host phase key decides where a hook runs.** A hook runs only at the
+ points that are both declared in its `lifecyclePoints` and referenced on
+ the Host. A Host phase the hook does not declare is ignored. Upgrade keeps
+ each Host's phases: it drops phases the new version no longer declares and
+ adds none the Host did not already reference, including newly declared
+ ones. If no phase survives, the hook is re-referenced at all of its new
+ points.
## Try the reference hook
@@ -338,9 +344,6 @@ guardrail policy` result or a pending approval. The
responses. The CRD default (65536) applies only when a `limits` object is
present; otherwise mcp-host uses 1 MiB, and `preCall` rewrites get 5 MiB.
Tool-lane hooks are not capped by this field.
-- **LLM-lane only.** Quarantine on digest mismatch and the circuit breaker
- are implemented for LLM-lane hooks only. Tool-lane hooks are dialed
- without them.
- **Doom-loop guard.** It is active whenever tool-lane rules or hooks exist:
the third consecutive identical call is denied (`repeated_identical_call`).
It is a runaway guard, not a security control, because alternating calls