openscript-sdk 0.1.0__py3-none-any.whl

openscript_sdk/__init__.py

@@ -0,0 +1,217 @@
+"""OpenScript: a policy pipeline for LLM agents and the tools they call."""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+# Every public name, and the module it lives in. Nothing is imported until a
+# name is first asked for, so a caller that needs one policy does not pay for
+# all of them (a Claude Code hook pays this on every tool call).
+_EXPORTS: dict[str, str] = {
+    "ActionBlockedError": "openscript_sdk.contracts.types",
+    "ActionContext": "openscript_sdk.contracts.types",
+    "ActionTracer": "openscript_sdk.observability.tracing",
+    "AgentCapabilities": "openscript_sdk.contracts.types",
+    "ApprovalRecord": "openscript_sdk.events.approvals",
+    "ApprovalStatus": "openscript_sdk.events.approvals",
+    "ApprovalStore": "openscript_sdk.events.approvals",
+    "AuditPolicy": "openscript_sdk.interceptors.event_writer",
+    "BasePolicy": "openscript_sdk.contracts.interceptor",
+    "CompliancePolicy": "openscript_sdk.policies.compliance",
+    "EventWriterInterceptor": "openscript_sdk.interceptors.event_writer",
+    "FailureMode": "openscript_sdk.contracts.types",
+    "GuardScan": "openscript_sdk.contracts.interceptor",
+    "HallucinationMode": "openscript_sdk.policies.output_schema",
+    "HarmfulRequestPolicy": "openscript_sdk.policies.harmful_request",
+    "InMemoryApprovalStore": "openscript_sdk.events.approvals",
+    "InMemoryTaintStore": "openscript_sdk.policies.session_taint",
+    "Interceptor": "openscript_sdk.contracts.interceptor",
+    "InterceptorDecision": "openscript_sdk.contracts.types",
+    "InterceptorResult": "openscript_sdk.contracts.types",
+    "InternalURLMode": "openscript_sdk.policies.secrets",
+    "MetricsRecorder": "openscript_sdk.observability.metrics",
+    "NoopInterceptor": "openscript_sdk.interceptors.base",
+    "OnInvalid": "openscript_sdk.policies.output_schema",
+    "OpenScriptMiddleware": "openscript_sdk.middleware.middleware",
+    "OutputSchemaPolicy": "openscript_sdk.policies.output_schema",
+    "PHIMode": "openscript_sdk.policies.compliance",
+    "PIIInterceptor": "openscript_sdk.interceptors.pii",
+    "PIIMode": "openscript_sdk.interceptors.pii",
+    "PIIPolicy": "openscript_sdk.interceptors.pii",
+    "Policy": "openscript_sdk.contracts.interceptor",
+    "PolicyConfig": "openscript_sdk.policies.config",
+    "PromptInjectionPolicy": "openscript_sdk.interceptors.threat",
+    "RedisApprovalStore": "openscript_sdk.events.approvals",
+    "RiskScorer": "openscript_sdk.observability.risk",
+    "SecretsPolicy": "openscript_sdk.policies.secrets",
+    "SecureAgent": "openscript_sdk.middleware.middleware",
+    "SecureTool": "openscript_sdk.middleware.tool",
+    "SemanticHead": "openscript_sdk.policies.semantic",
+    "SemanticMode": "openscript_sdk.policies.semantic",
+    "SemanticPolicy": "openscript_sdk.policies.semantic",
+    "SessionTaintPolicy": "openscript_sdk.policies.session_taint",
+    "StreamGuard": "openscript_sdk.contracts.interceptor",
+    "StreamOutputMode": "openscript_sdk.middleware.middleware",
+    "TaintAction": "openscript_sdk.policies.session_taint",
+    "TaintStore": "openscript_sdk.policies.session_taint",
+    "ThreatInterceptor": "openscript_sdk.interceptors.threat",
+    "ToolFirewallPolicy": "openscript_sdk.policies.tool_firewall",
+    "ToolRules": "openscript_sdk.policies.tool_firewall",
+    "ToxicityPolicy": "openscript_sdk.policies.toxicity",
+    "aggregate_risk": "openscript_sdk.observability.risk",
+    "configure_logging": "openscript_sdk.logging",
+    "find_phi": "openscript_sdk.policies.compliance",
+    "find_pii": "openscript_sdk.policies.redaction",
+    "find_secrets": "openscript_sdk.policies.secrets",
+    "load_policies": "openscript_sdk.policies.config",
+    "redact_data": "openscript_sdk.policies.redaction",
+    "redact_pii": "openscript_sdk.policies.redaction",
+    "redact_secrets": "openscript_sdk.policies.redaction",
+    "register_policy": "openscript_sdk.policies.config",
+    "validate_tool_call": "openscript_sdk.policies.tool_firewall",
+    "wrap_agent": "openscript_sdk.integrations.langchain",
+    "wrap_graph_agent": "openscript_sdk.integrations.langgraph",
+}
+
+if TYPE_CHECKING:
+    from openscript_sdk.contracts.interceptor import (
+        BasePolicy,
+        GuardScan,
+        Interceptor,
+        Policy,
+        StreamGuard,
+    )
+    from openscript_sdk.contracts.types import (
+        ActionBlockedError,
+        ActionContext,
+        AgentCapabilities,
+        FailureMode,
+        InterceptorDecision,
+        InterceptorResult,
+    )
+    from openscript_sdk.events.approvals import (
+        ApprovalRecord,
+        ApprovalStatus,
+        ApprovalStore,
+        InMemoryApprovalStore,
+        RedisApprovalStore,
+    )
+    from openscript_sdk.integrations.langchain import wrap_agent
+    from openscript_sdk.integrations.langgraph import wrap_graph_agent
+    from openscript_sdk.interceptors.base import NoopInterceptor
+    from openscript_sdk.interceptors.event_writer import AuditPolicy, EventWriterInterceptor
+    from openscript_sdk.interceptors.pii import PIIInterceptor, PIIMode, PIIPolicy
+    from openscript_sdk.interceptors.threat import PromptInjectionPolicy, ThreatInterceptor
+    from openscript_sdk.logging import configure_logging
+    from openscript_sdk.middleware.middleware import (
+        OpenScriptMiddleware,
+        SecureAgent,
+        StreamOutputMode,
+    )
+    from openscript_sdk.middleware.tool import SecureTool
+    from openscript_sdk.observability.metrics import MetricsRecorder
+    from openscript_sdk.observability.risk import RiskScorer, aggregate_risk
+    from openscript_sdk.observability.tracing import ActionTracer
+    from openscript_sdk.policies.compliance import CompliancePolicy, PHIMode, find_phi
+    from openscript_sdk.policies.config import PolicyConfig, load_policies, register_policy
+    from openscript_sdk.policies.harmful_request import HarmfulRequestPolicy
+    from openscript_sdk.policies.output_schema import (
+        HallucinationMode,
+        OnInvalid,
+        OutputSchemaPolicy,
+    )
+    from openscript_sdk.policies.redaction import find_pii, redact_data, redact_pii, redact_secrets
+    from openscript_sdk.policies.secrets import InternalURLMode, SecretsPolicy, find_secrets
+    from openscript_sdk.policies.semantic import SemanticHead, SemanticMode, SemanticPolicy
+    from openscript_sdk.policies.session_taint import (
+        InMemoryTaintStore,
+        SessionTaintPolicy,
+        TaintAction,
+        TaintStore,
+    )
+    from openscript_sdk.policies.tool_firewall import (
+        ToolFirewallPolicy,
+        ToolRules,
+        validate_tool_call,
+    )
+    from openscript_sdk.policies.toxicity import ToxicityPolicy
+
+__all__ = [
+    "ActionBlockedError",
+    "ActionContext",
+    "ActionTracer",
+    "AgentCapabilities",
+    "ApprovalRecord",
+    "ApprovalStatus",
+    "ApprovalStore",
+    "AuditPolicy",
+    "BasePolicy",
+    "CompliancePolicy",
+    "EventWriterInterceptor",  # deprecated alias
+    "FailureMode",
+    "GuardScan",
+    "HallucinationMode",
+    "HarmfulRequestPolicy",
+    "InMemoryApprovalStore",
+    "InMemoryTaintStore",
+    "Interceptor",  # deprecated alias
+    "InterceptorDecision",
+    "InterceptorResult",
+    "InternalURLMode",
+    "MetricsRecorder",
+    "NoopInterceptor",
+    "OnInvalid",
+    "OpenScriptMiddleware",  # deprecated alias
+    "OutputSchemaPolicy",
+    "PHIMode",
+    "PIIInterceptor",  # deprecated alias
+    "PIIMode",
+    "PIIPolicy",
+    "Policy",
+    "PolicyConfig",
+    "PromptInjectionPolicy",
+    "RedisApprovalStore",
+    "RiskScorer",
+    "SecretsPolicy",
+    "SecureAgent",
+    "SecureTool",
+    "SemanticHead",
+    "SemanticMode",
+    "SemanticPolicy",
+    "SessionTaintPolicy",
+    "StreamGuard",
+    "StreamOutputMode",
+    "TaintAction",
+    "TaintStore",
+    "ThreatInterceptor",  # deprecated alias
+    "ToolFirewallPolicy",
+    "ToolRules",
+    "ToxicityPolicy",
+    "aggregate_risk",
+    "configure_logging",
+    "find_phi",
+    "find_pii",
+    "find_secrets",
+    "load_policies",
+    "redact_data",
+    "redact_pii",
+    "redact_secrets",
+    "register_policy",
+    "validate_tool_call",
+    "wrap_agent",
+    "wrap_graph_agent",
+]
+
+
+def __getattr__(name: str) -> Any:
+    module = _EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(importlib.import_module(module), name)
+    globals()[name] = value  # asked for once, then a plain attribute
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))

openscript_sdk/contracts/__init__.py

@@ -0,0 +1,82 @@
+"""OpenScript contract: public framework types and protocols."""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+# Every public name, and the module it lives in. Nothing is imported until a
+# name is first asked for, so a caller that needs one policy does not pay for
+# all of them (a Claude Code hook pays this on every tool call).
+_EXPORTS: dict[str, str] = {
+    "ActionContext": "openscript_sdk.contracts.types",
+    "AgentCapabilities": "openscript_sdk.contracts.types",
+    "DetectionResult": "openscript_sdk.contracts.server_types",
+    "Event": "openscript_sdk.contracts.server_types",
+    "EventType": "openscript_sdk.contracts.server_types",
+    "FailureMode": "openscript_sdk.contracts.types",
+    "GraphEdge": "openscript_sdk.contracts.session_graph",
+    "GraphNode": "openscript_sdk.contracts.session_graph",
+    "Interceptor": "openscript_sdk.contracts.interceptor",
+    "InterceptorDecision": "openscript_sdk.contracts.types",
+    "InterceptorResult": "openscript_sdk.contracts.types",
+    "NodeType": "openscript_sdk.contracts.session_graph",
+    "PolicyEvalRequest": "openscript_sdk.contracts.server_types",
+    "PolicyEvalResponse": "openscript_sdk.contracts.server_types",
+    "SessionGraph": "openscript_sdk.contracts.session_graph",
+    "ThreatScoreRequest": "openscript_sdk.contracts.server_types",
+    "ThreatScoreResponse": "openscript_sdk.contracts.server_types",
+}
+
+if TYPE_CHECKING:
+    from openscript_sdk.contracts.interceptor import Interceptor
+    from openscript_sdk.contracts.server_types import (
+        DetectionResult,
+        Event,
+        EventType,
+        PolicyEvalRequest,
+        PolicyEvalResponse,
+        ThreatScoreRequest,
+        ThreatScoreResponse,
+    )
+    from openscript_sdk.contracts.session_graph import GraphEdge, GraphNode, NodeType, SessionGraph
+    from openscript_sdk.contracts.types import (
+        ActionContext,
+        AgentCapabilities,
+        FailureMode,
+        InterceptorDecision,
+        InterceptorResult,
+    )
+
+__all__ = [
+    "ActionContext",
+    "AgentCapabilities",
+    "DetectionResult",
+    "Event",
+    "EventType",
+    "FailureMode",
+    "GraphEdge",
+    "GraphNode",
+    "Interceptor",
+    "InterceptorDecision",
+    "InterceptorResult",
+    "NodeType",
+    "PolicyEvalRequest",
+    "PolicyEvalResponse",
+    "SessionGraph",
+    "ThreatScoreRequest",
+    "ThreatScoreResponse",
+]
+
+
+def __getattr__(name: str) -> Any:
+    module = _EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(importlib.import_module(module), name)
+    globals()[name] = value  # asked for once, then a plain attribute
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))

openscript_sdk/contracts/interceptor.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+from openscript_sdk.contracts.types import ActionContext, FailureMode
+
+
+@dataclass
+class GuardScan:
+    """Result of one incremental scan by a StreamGuard.
+
+    text is the (possibly redacted) input text; labels/risk mirror the
+    owning policy's metadata conventions; deny=True aborts the stream with
+    *reason* before the offending text is released.
+    """
+
+    text: str
+    labels: list[str] = field(default_factory=list)
+    risk: float = 0.0
+    deny: bool = False
+    reason: str = ""
+
+
+@runtime_checkable
+class StreamGuard(Protocol):
+    """Bounded incremental text scanner for guarded streaming.
+
+    max_match_len is the guard's honest upper bound on how many characters
+    one of its patterns can span — the middleware holds back a tail of that
+    size, which is what guarantees a match is never split across the
+    released/held boundary. Unbounded constructs must be handled by their
+    prefix (e.g. a PEM header) or must deny.
+
+    final=False means more text may follow: a match ending exactly at the
+    end of *text* is tentative (it could extend) and must be left untouched
+    and unreported — it sits inside the held tail, so deferring never leaks
+    it. final=True (stream end) acts on everything.
+    """
+
+    name: str
+    max_match_len: int
+
+    def scan(self, text: str, final: bool = False) -> GuardScan: ...
+
+
+@runtime_checkable
+class Policy(Protocol):
+    """Protocol all OpenScript policies must satisfy."""
+
+    failure_mode: FailureMode
+
+    async def before_action(self, context: ActionContext) -> ActionContext: ...
+    async def after_action(self, context: ActionContext) -> ActionContext: ...
+
+
+class BasePolicy:
+    """Concrete base class for policies; subclasses override only the hooks they need."""
+
+    failure_mode: FailureMode = FailureMode.FAIL_OPEN
+
+    async def before_action(self, context: ActionContext) -> ActionContext:
+        return context
+
+    async def after_action(self, context: ActionContext) -> ActionContext:
+        return context
+
+    async def on_blocked(
+        self,
+        context: ActionContext,
+        *,
+        blocked_by: str,
+        phase: str,
+        approval_id: str = "",
+    ) -> None:
+        """Called once when the pipeline refuses an action, on every policy.
+
+        Optional, and not part of the Policy protocol: SecureAgent looks it up
+        by name. It exists for observers. A deny in the before phase stops the
+        loop, so policies listed after the one that denied never run — this is
+        how an audit policy placed last still gets to record the refusal.
+
+        *phase* is "before" (the agent never ran), "after" (the response was
+        withheld) or "stream" (a guard aborted a guarded stream). The decision
+        is already final; the hook cannot change it.
+        """
+        return None
+
+    def stream_guard(self) -> StreamGuard | None:
+        """Override to participate in guarded streaming. Only policies whose
+        checks are bounded text patterns can do so; policies needing the
+        complete output (schema validation, grounding) return None and run
+        at stream end."""
+        return None
+
+
+# Deprecated alias — prefer Policy
+Interceptor = Policy

openscript_sdk/contracts/server_types.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class EventType(StrEnum):
+    TURN_STARTED = "turn_start"
+    TURN_END = "turn_end"
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    MEMORY_WRITE = "memory_write"
+    MEMORY_READ = "memory_read"
+    INTERCEPTOR_BEFORE = "interceptor_before"
+    INTERCEPTOR_AFTER = "interceptor_after"
+    THREAT_DETECTED = "threat_detected"
+    POLICY_EVALUATED = "policy_evaluated"
+    AGENT_MESSAGE = "agent_message"
+    APPROVAL_REQUESTED = "approval_requested"
+    APPROVAL_RESOLVED = "approval_resolved"
+    ACTION_BLOCKED = "action_blocked"
+
+
+class Event(BaseModel):
+    model_config = {"frozen": True}
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    session_id: str
+    agent_id: str
+    event_type: EventType
+    payload: dict[str, Any] = Field(default_factory=dict)
+    timestamp: datetime = Field(default_factory=datetime.now)
+    sequence_num: int
+
+
+class ThreatScoreRequest(BaseModel):
+    session_id: str
+    agent_id: str
+    text: str
+    turn_number: int
+    context: dict[str, Any] = Field(default_factory=dict)
+
+
+class ThreatScoreResponse(BaseModel):
+    session_id: str
+    score: float
+    signals: dict[str, float] = Field(default_factory=dict)
+    flagged: bool = False
+    reason: str = ""
+
+
+class PolicyEvalRequest(BaseModel):
+    session_id: str
+    agent_id: str
+    action: str
+    capabilities: dict[str, bool] = Field(default_factory=dict)
+    context: dict[str, Any] = Field(default_factory=dict)
+
+
+class PolicyEvalResponse(BaseModel):
+    session_id: str
+    decision: str
+    reason: str = ""
+    policies_evaluated: list[str] = Field(default_factory=list)
+
+
+class DetectionResult(BaseModel):
+    regex_score: float = 0.0
+    embedding_score: float = 0.0
+    final_score: float = 0.0
+    method: str = ""
+
+
+class ToolValidateRequest(BaseModel):
+    tool_name: str
+    args: dict[str, Any] = Field(default_factory=dict)
+    role: str | None = None
+
+
+class ToolValidateResponse(BaseModel):
+    allowed: bool
+    reason: str
+    requires_approval: bool = False

openscript_sdk/contracts/session_graph.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import TYPE_CHECKING, Any
+
+from openscript_sdk.contracts.server_types import Event, EventType
+
+if TYPE_CHECKING:
+    from openscript_sdk.events.store import EventStore
+
+
+class NodeType(StrEnum):
+    TURN = "turn"
+    TOOL_CALL = "tool_call"
+    MEMORY_WRITE = "memory_write"
+    AGENT_MESSAGE = "agent_message"
+    INTERCEPTOR = "interceptor"
+    THREAT = "threat"
+    POLICY = "policy"
+
+
+_EVENT_TO_NODE: dict[EventType, NodeType] = {
+    EventType.TURN_STARTED: NodeType.TURN,
+    EventType.TURN_END: NodeType.TURN,
+    EventType.TOOL_CALL: NodeType.TOOL_CALL,
+    EventType.TOOL_RESULT: NodeType.TOOL_CALL,
+    EventType.MEMORY_WRITE: NodeType.MEMORY_WRITE,
+    EventType.MEMORY_READ: NodeType.MEMORY_WRITE,
+    EventType.INTERCEPTOR_BEFORE: NodeType.INTERCEPTOR,
+    EventType.INTERCEPTOR_AFTER: NodeType.INTERCEPTOR,
+    EventType.THREAT_DETECTED: NodeType.THREAT,
+    EventType.POLICY_EVALUATED: NodeType.POLICY,
+    EventType.AGENT_MESSAGE: NodeType.AGENT_MESSAGE,
+}
+
+
+@dataclass(frozen=True)
+class GraphNode:
+    id: str
+    node_type: str
+    event: Event
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class GraphEdge:
+    source_id: str
+    target_id: str
+    edge_type: str = "causal"
+
+
+@dataclass
+class SessionGraph:
+    session_id: str
+    nodes: dict[str, GraphNode] = field(default_factory=dict)
+    edges: list[GraphEdge] = field(default_factory=list)
+
+    def add_node(self, node: GraphNode) -> None:
+        self.nodes[node.id] = node
+
+    def add_edge(self, edge: GraphEdge) -> None:
+        self.edges.append(edge)
+
+    @classmethod
+    def build(cls, session_id: str, events: list[Event]) -> SessionGraph:
+        """Build a DAG from an ordered list of events.
+
+        Nodes map 1:1 to events. Edges encode sequential causality and
+        parent-child relationships (tool calls / memory writes nested
+        inside turns).
+        """
+        sorted_events = sorted(events, key=lambda e: e.sequence_num)
+        graph = cls(session_id=session_id)
+
+        prev_node_id: str | None = None
+        turn_stack: list[str] = []
+
+        for event in sorted_events:
+            node_type = _EVENT_TO_NODE.get(event.event_type, NodeType.AGENT_MESSAGE)
+            node = GraphNode(
+                id=event.id,
+                node_type=node_type.value,
+                event=event,
+            )
+            graph.add_node(node)
+
+            if prev_node_id is not None:
+                graph.add_edge(GraphEdge(source_id=prev_node_id, target_id=node.id))
+
+            if event.event_type == EventType.TURN_STARTED:
+                turn_stack.append(node.id)
+            elif event.event_type in (EventType.TOOL_CALL, EventType.MEMORY_WRITE):
+                if turn_stack:
+                    graph.add_edge(
+                        GraphEdge(
+                            source_id=turn_stack[-1],
+                            target_id=node.id,
+                            edge_type="parent",
+                        )
+                    )
+            elif event.event_type == EventType.TURN_END and turn_stack:
+                turn_stack.pop()
+
+            prev_node_id = node.id
+
+        return graph
+
+    @classmethod
+    async def from_live_stream(cls, events: AsyncIterator[Event]) -> SessionGraph:
+        collected: list[Event] = []
+        session_id = ""
+        async for event in events:
+            if not session_id:
+                session_id = event.session_id
+            collected.append(event)
+        return cls.build(session_id=session_id, events=collected)
+
+    @classmethod
+    async def from_store(cls, session_id: str, event_store: EventStore) -> SessionGraph:
+        events = await event_store.get_events(session_id=session_id)
+        return cls.build(session_id=session_id, events=events)

openscript_sdk/contracts/types.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class FailureMode(Enum):
+    FAIL_CLOSED = "fail_closed"
+    FAIL_OPEN = "fail_open"
+    FAIL_EXCEPTION = "fail_exception"
+
+
+class InterceptorDecision(Enum):
+    ALLOW = "allow"
+    DENY = "deny"
+    REQUIRE_APPROVAL = "require_approval"
+
+
+class ActionBlockedError(RuntimeError):
+    """Raised by middleware when an interceptor sets decision=DENY or REQUIRE_APPROVAL.
+
+    Carries the final ActionContext and aggregated risk_score so blocked
+    calls surface the same risk signal as allowed ones. When the block is a
+    REQUIRE_APPROVAL, approval_id names the pending approval record — once
+    a human approves it, retry the action with invoke(..., approval_id=...).
+    """
+
+    def __init__(
+        self,
+        reason: str = "",
+        interceptor: str = "",
+        context: ActionContext | None = None,
+        risk_score: float = 0.0,
+        approval_id: str = "",
+    ) -> None:
+        self.reason = reason
+        self.interceptor = interceptor
+        self.context = context
+        self.risk_score = risk_score
+        self.approval_id = approval_id
+        msg = (
+            f"Action blocked by {interceptor}: {reason}"
+            if interceptor
+            else f"Action blocked: {reason}"
+        )
+        super().__init__(msg)
+
+
+@dataclass(frozen=True)
+class AgentCapabilities:
+    untrusted_input: bool = False
+    sensitive_access: bool = False
+    external_write: bool = False
+
+
+@dataclass
+class ActionContext:
+    action: str
+    agent_id: str
+    session_id: str
+    input_data: dict[str, Any] = field(default_factory=dict)
+    output_data: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+    capabilities: AgentCapabilities = field(default_factory=AgentCapabilities)
+    decision: InterceptorDecision = field(default=InterceptorDecision.ALLOW)
+    decision_reason: str = ""
+    risk_score: float = 0.0
+    risk_categories: dict[str, float] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class InterceptorResult:
+    decision: InterceptorDecision
+    reason: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)