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.mdindex 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 serversilently prunes fields an older CRD does not know.diff --git a/docs/crds/llmhook.md b/docs/crds/llmhook.mdindex 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.mdindex 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` (defaultOpen **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. Toremove it from the cluster, uninstall it on **Installed Guardrails**. Thatstrips the reference from every Host first, then deletes the CR. **Addhook** 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, cooldown30000 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 aco-located hook that lost a `DuplicatePath` collision. Upgrade with`POST /admin/registry/upgrade-hook`, which bumps the CR and every Host'sdigest 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. Theresponses. The CRD default (65536) applies only when a `limits` object ispresent; 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