Merge pull request #50 from chiruu12/feat/agentos-guardrails

AgentOS Phase 2: content guardrails (PII + prompt injection)

Author: chiruu12

CLAUDE.md

@@ -98,6 +98,7 @@ src/hive/
 |-----------|-----|------|
 | Custom tool | Subclass `Toolkit`, `@tool()` methods | `src/hive/tools/base.py` |
 | Gated tool (HITL) | `@tool(requires_approval=True)` or `ApprovalGate` protocol | `src/hive/runtime/approval.py` |
+| Custom guardrail | `Guardrail` protocol, `GuardrailRegistry.default().register(...)` | `src/hive/runtime/guardrails.py` |
 | Custom model provider | Subclass `BaseProvider` | `src/hive/models/base.py` |
 | Custom stressor | `StressorRegistry.default().register(name, rate, desc)` | `src/hive/agents/suffering.py` |
 | Custom A2A pattern | Subclass `A2APattern`, `PatternRegistry.default().register(name, instance)` | `src/hive/interactions/registry.py` |

docs/changelog.md

@@ -18,6 +18,12 @@
 - **Per-user/per-session isolation**: the `sessions` table gains tenant columns and a
   `SessionService` resolves a session per request (via the `X-Hive-User` header),
   isolating one tenant's sessions from another's.
+- **Content guardrails**: a `Guardrail` protocol with pre-hook (task input) and
+  post-hook (model output) inspection in the ReAct loop, plus built-in `PIIGuardrail`
+  (emails/phones/SSNs/cards/IPs) and `PromptInjectionGuardrail` (instruction-override /
+  jailbreak phrasing). Config-driven (`guardrails.enabled`, per-guardrail `flag`/
+  `redact`/`block` actions); `GuardrailRegistry` and `GuardrailPipeline` compose custom
+  guardrails. Off by default. `Agent(guardrails=...)`.
 
 ## [0.6.1] -- 2026-06-03
 

docs/extending/index.md

@@ -592,3 +592,32 @@ agent = Agent(name="releaser", model=provider, toolkits=[DeployToolkit()],
 
 The built-in `StoreApprovalGate` persists pending approvals so they survive the
 daemon's heartbeat cycles. See [Human-in-the-Loop Approvals](../guide/daemon-mode.md#human-in-the-loop-approvals).
+
+## 10. Custom Guardrail
+
+A guardrail inspects text entering or leaving the model. Implement the `Guardrail`
+protocol and register it so it composes with the built-in PII and prompt-injection
+guardrails.
+
+```python
+from hive.runtime.guardrails import (
+    Guardrail, GuardrailAction, GuardrailFinding, GuardrailStage, GuardrailRegistry,
+)
+
+class ProfanityGuardrail:
+    name = "profanity"
+    action = GuardrailAction.REDACT
+
+    def inspect(self, text: str, stage: GuardrailStage) -> GuardrailFinding:
+        if stage is GuardrailStage.OUTPUT and "badword" in text.lower():
+            cleaned = text.replace("badword", "[REDACTED]")
+            return GuardrailFinding(True, self.action, cleaned, ["profanity"])
+        return GuardrailFinding(False, self.action, text)
+
+# Compose directly into a pipeline:
+from hive.runtime.guardrails import GuardrailPipeline, PIIGuardrail
+pipeline = GuardrailPipeline([ProfanityGuardrail(), PIIGuardrail()])
+agent = Agent(name="writer", model=provider, guardrails=pipeline)
+```
+
+See [Guardrails](../guide/daemon-mode.md#guardrails).

docs/getting-started/cli-quickstart.md

@@ -118,6 +118,13 @@ approval:                 # human-in-the-loop tool gating (off by default)
   auto_approve: []        # tool names never gated (overrides a tool's own flag)
   timeout_cycles: 0       # auto-deny after N heartbeats (0 = never)
 
+guardrails:               # content checks on model input/output (off by default)
+  enabled: false
+  pii: true               # redact PII in output
+  prompt_injection: true  # block injection phrasing in input
+  pii_action: redact      # flag | redact | block
+  injection_action: block # flag | redact | block
+
 event_log_fsync: false  # fsync every event-log append (crash-durable, slower)
 seed: null              # int for a reproducible world RNG; null = system entropy
 ```

docs/guide/daemon-mode.md

@@ -137,6 +137,27 @@ An approval is granted for a specific `(tool, arguments)` pair and is single-use
 re-running the same call later prompts again. `timeout_cycles` auto-denies a request
 that sits unresolved too long.
 
+## Guardrails
+
+Guardrails inspect content around the model -- a **pre-hook** on the task input and a
+**post-hook** on the final output (the model-I/O analog of lifecycle hooks). Enable
+them in `.hive/config.yaml`:
+
+```yaml
+guardrails:
+  enabled: true
+  pii: true                 # redact PII in output
+  prompt_injection: true    # block injection phrasing in input
+  pii_action: redact        # flag | redact | block
+  injection_action: block   # flag | redact | block
+```
+
+Built-ins: **PII** (emails, phones, SSNs, cards, IPs) and **prompt injection**
+("ignore previous instructions", "you are now …", jailbreak phrasing). Each action is
+`flag` (log only), `redact` (mask matches), or `block` (refuse the input / withhold the
+output). A blocked input fails the task; a blocked output is replaced with a notice.
+Add your own via the `Guardrail` protocol and `GuardrailRegistry`.
+
 ## Life Events
 
 The event engine rolls random events each cycle (30% probability). Events force agents to make decisions that affect their stats and suffering.

src/hive/config.py

@@ -3,7 +3,7 @@
 import os
 from collections.abc import Callable
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
 
 import yaml
 from dotenv import dotenv_values
@@ -186,6 +186,21 @@ def _timeout_non_negative(cls, v: int) -> int:
         return v
 
 
+class GuardrailConfig(BaseModel):
+    """Content guardrails on model input/output.
+
+    Disabled by default. When enabled, a PII guardrail (redacts output by default)
+    and a prompt-injection guardrail (blocks input by default) run around the model.
+    Actions are ``flag`` (log only), ``redact`` (mask matches), or ``block``.
+    """
+
+    enabled: bool = False
+    pii: bool = True
+    prompt_injection: bool = True
+    pii_action: Literal["flag", "redact", "block"] = "redact"
+    injection_action: Literal["flag", "redact", "block"] = "block"
+
+
 class ModelConfig(BaseModel):
     default_model: str = "claude-haiku-4-5"
     planning_model: str = "claude-sonnet-4-6"
@@ -202,6 +217,7 @@ class HiveConfig(BaseModel):
     daemon: DaemonConfig = DaemonConfig()
     model: ModelConfig = ModelConfig()
     approval: ApprovalConfig = ApprovalConfig()
+    guardrails: GuardrailConfig = GuardrailConfig()
     profiles_dir: str = ""
     logs_dir: str = "logs"
     # fsync every event-log append for crash durability (one fsync per event).

src/hive/daemon/loop.py

@@ -30,6 +30,7 @@
 from hive.models.base import BaseProvider
 from hive.models.factory import create_runtime_provider
 from hive.runtime import Agent, DaemonAgentAdapter, Message
+from hive.runtime.guardrails import build_guardrail_pipeline
 from hive.runtime.persona import Persona
 from hive.tools.a2a import A2AToolkit
 from hive.tools.alarms import AlarmToolkit, fire_notification
@@ -479,6 +480,7 @@ async def _run_agent_cycle_inner(self, agent: AgentState, suffering: SufferingSt
                     session_id=session_id,
                     goal_id=active_goal["goal_id"],
                 )
+            guardrails = build_guardrail_pipeline(get_config().guardrails)
             if persona is not None:
                 runtime_agent = Agent(
                     name=agent.name,
@@ -487,6 +489,7 @@ async def _run_agent_cycle_inner(self, agent: AgentState, suffering: SufferingSt
                     toolkits=self._build_toolkits(agent.agent_id),
                     tool_timeout=tool_timeout,
                     approval_gate=approval_gate,
+                    guardrails=guardrails,
                 )
             else:
                 runtime_agent = Agent(
@@ -498,6 +501,7 @@ async def _run_agent_cycle_inner(self, agent: AgentState, suffering: SufferingSt
                     toolkits=self._build_toolkits(agent.agent_id),
                     tool_timeout=tool_timeout,
                     approval_gate=approval_gate,
+                    guardrails=guardrails,
                 )
             adapter = DaemonAgentAdapter(runtime_agent, agent.agent_id)
             # Give the pursuing agent its persistent self -- name and accumulated

src/hive/runtime/agent.py

@@ -14,6 +14,7 @@
 from hive.models.base import BaseProvider
 from hive.models.registry import estimate_cost
 from hive.runtime.approval import ApprovalDecision, ApprovalGate, AwaitingApprovalSignal
+from hive.runtime.guardrails import GuardrailAction, GuardrailPipeline, GuardrailStage
 from hive.runtime.instructions import InstructionLike, Instructions
 from hive.runtime.memory import ConversationMemory, PersistentMemory
 from hive.runtime.persona import Persona
@@ -79,13 +80,17 @@ def __init__(
         on_text: Callable[[str], None] | None = None,
         tool_timeout: float = 0.0,
         approval_gate: ApprovalGate | None = None,
+        guardrails: GuardrailPipeline | None = None,
     ):
         self.name = name
         self._model = model
         self._on_text = on_text
         # Optional human-in-the-loop gate. When set, tools it flags are paused for
         # approval instead of executing (see _execute_tool_calls). None = no gating.
         self._approval_gate = approval_gate
+        # Optional content guardrails. When set, the task input is checked before the
+        # model runs (pre-hook) and the final output before it is returned (post-hook).
+        self._guardrails = guardrails
         # Per-tool wall-clock limit (seconds); 0 disables. A tool that exceeds it
         # becomes a tool-error result so one hung tool can't stall the whole cycle.
         self._tool_timeout = tool_timeout
@@ -473,6 +478,29 @@ async def run(self, task: Task) -> TaskResult:
         self._tokens_warned = False
         t0 = time.time()
 
+        # Pre-hook: inspect the task input before the model sees it. A blocking
+        # guardrail (e.g. prompt injection) refuses the run; a redacting one rewrites
+        # the instruction the model receives.
+        if self._guardrails:
+            finding = self._guardrails.run(task.instruction, GuardrailStage.INPUT)
+            if finding.triggered:
+                logger.warning(
+                    "Agent %r: input guardrail %s (%s)",
+                    self.name,
+                    finding.action.value,
+                    "; ".join(finding.reasons),
+                )
+                if finding.blocked:
+                    return TaskResult(
+                        task_id=task.id,
+                        status=TaskStatus.FAILED,
+                        output="",
+                        error=f"blocked by guardrail: {'; '.join(finding.reasons)}",
+                        duration_seconds=time.time() - t0,
+                    )
+                if finding.action is GuardrailAction.REDACT:
+                    task = task.model_copy(update={"instruction": finding.text})
+
         tools = self.get_tools()
         tool_map = {t.name: t for t in tools}
         tool_schemas = [t.to_schema() for t in tools] if tools else None
@@ -529,11 +557,33 @@ async def run(self, task: Task) -> TaskResult:
             conversation.add(response)
 
             if not response.tool_calls:
-                self._write_conversation_log(task.id, conversation.get_messages(), "completed")
+                # Post-hook: inspect the final output before returning it. A blocking
+                # guardrail withholds it; a redacting one masks matched spans (e.g. PII).
+                output = response.content
+                if self._guardrails:
+                    finding = self._guardrails.run(output, GuardrailStage.OUTPUT)
+                    if finding.triggered:
+                        logger.warning(
+                            "Agent %r: output guardrail %s (%s)",
+                            self.name,
+                            finding.action.value,
+                            "; ".join(finding.reasons),
+                        )
+                        if finding.blocked:
+                            output = "[output withheld by guardrail]"
+                        elif finding.action is GuardrailAction.REDACT:
+                            output = finding.text
+                # The raw assistant message is already in the conversation; replace it
+                # with the sanitized output for the on-disk log too, so a redacting
+                # guardrail doesn't leak the unredacted content into the JSON log file.
+                log_messages = conversation.get_messages()
+                if output != response.content:
+                    log_messages = [*log_messages[:-1], Message.assistant(output)]
+                self._write_conversation_log(task.id, log_messages, "completed")
                 return TaskResult(
                     task_id=task.id,
                     status=TaskStatus.COMPLETED,
-                    output=response.content,
+                    output=output,
                     steps_taken=steps,
                     tool_calls_made=tool_calls_total,
                     duration_seconds=time.time() - t0,