feat(guardrails): add pre-tool-call authorization middleware with pluggable providers (#1240)

Add GuardrailMiddleware that evaluates every tool call before execution.
Three provider options: built-in AllowlistProvider (zero deps), OAP passport
providers (open standard), or custom providers loaded by class path.

- GuardrailProvider protocol with GuardrailRequest/Decision dataclasses
- GuardrailMiddleware (AgentMiddleware, position 5 in chain)
- AllowlistProvider for simple deny/allow by tool name
- GuardrailsConfig (Pydantic singleton, loaded from config.yaml)
- 25 tests covering allow/deny, fail-closed/open, async, GraphBubbleUp
- Comprehensive docs at backend/docs/GUARDRAILS.md

Closes #1213

Co-authored-by: Willem Jiang <willem.jiang@gmail.com>

backend/packages/harness/deerflow/config/guardrails_config.py

@@ -0,0 +1,48 @@
+"""Configuration for pre-tool-call authorization."""
+
+from pydantic import BaseModel, Field
+
+
+class GuardrailProviderConfig(BaseModel):
+    """Configuration for a guardrail provider."""
+
+    use: str = Field(description="Class path (e.g. 'deerflow.guardrails.builtin:AllowlistProvider')")
+    config: dict = Field(default_factory=dict, description="Provider-specific settings passed as kwargs")
+
+
+class GuardrailsConfig(BaseModel):
+    """Configuration for pre-tool-call authorization.
+
+    When enabled, every tool call passes through the configured provider
+    before execution. The provider receives tool name, arguments, and the
+    agent's passport reference, and returns an allow/deny decision.
+    """
+
+    enabled: bool = Field(default=False, description="Enable guardrail middleware")
+    fail_closed: bool = Field(default=True, description="Block tool calls if provider errors")
+    passport: str | None = Field(default=None, description="OAP passport path or hosted agent ID")
+    provider: GuardrailProviderConfig | None = Field(default=None, description="Guardrail provider configuration")
+
+
+_guardrails_config: GuardrailsConfig | None = None
+
+
+def get_guardrails_config() -> GuardrailsConfig:
+    """Get the guardrails config, returning defaults if not loaded."""
+    global _guardrails_config
+    if _guardrails_config is None:
+        _guardrails_config = GuardrailsConfig()
+    return _guardrails_config
+
+
+def load_guardrails_config_from_dict(data: dict) -> GuardrailsConfig:
+    """Load guardrails config from a dict (called during AppConfig loading)."""
+    global _guardrails_config
+    _guardrails_config = GuardrailsConfig.model_validate(data)
+    return _guardrails_config
+
+
+def reset_guardrails_config() -> None:
+    """Reset the cached config instance. Used in tests to prevent singleton leaks."""
+    global _guardrails_config
+    _guardrails_config = None