feat(F): F-PERM permissions, F-APPR approval, F-AIUSE metadata, F-TRANS transparency, F-DATA-POL data policy, F-OVERSIGHT decision record, F-DRY dry-run, F-AUDIT audit log

- F-PERM: app/ai/agent_permissions.py (230 lines) — AgentPermissionContext, resolve_agent_permissions(), filter_visible_agents(), check_agent_execute_permission(), optimistic locking
- F-APPR: app/core/approval.py (160 lines) + app/routes/approvals.py (305 lines) + migration 0123 — ApprovalRequest model, CRUD API, approve/reject/expire
- F-AIUSE: app/ai/ai_use_case.py (156 lines) — AIUseCaseMetadata Pydantic model, validate_ai_use_case()
- F-TRANS: app/ai/transparency.py (60 lines) — mark_as_ai_generated(), is_ai_participant()
- F-DATA-POL: app/ai/data_policy.py (210 lines) — enforce_data_policy() with SENSITIVE_FIELDS + provider compliance
- F-OVERSIGHT: app/ai/oversight.py (108 lines) — DecisionRecord, create_decision_record()
- F-DRY: agent_loop.py updated with dry_run parameter
- F-AUDIT: agent_loop.py updated with audit log for tool calls
- agent_routes.py: AI use case metadata endpoints added
- main.py: approval routes registered
- All Python compile checks pass

app/ai/agent_loop.py

@@ -148,6 +148,7 @@ async def run_react_loop(
     timeout_seconds: int = 300,
     trace_id: str | None = None,
     on_step: Callable | None = None,
+    dry_run: bool = False,
 ) -> ReActResult:
     """Execute a ReAct loop: LLM reasoning → tool execution → repeat.
 
@@ -164,6 +165,9 @@ async def run_react_loop(
         timeout_seconds: Overall timeout (default 300).
         trace_id: Optional trace ID for correlation.
         on_step: Optional async callback fired after each step.
+        dry_run: When True, tool execution is simulated — tool handlers are
+            NOT called. A mock result is returned instead and steps are still
+            logged with real LLM cost.
 
     Returns:
         ReActResult with final content, steps, cost, and status.
@@ -193,6 +197,38 @@ async def run_react_loop(
         "db": db,
     }
 
+    # Audit helper — records every tool call in the audit log.
+    async def _audit_tool_call(
+        step_number: int,
+        tool_name: str,
+        arguments: dict[str, Any],
+        result: str,
+        cost_usd: float,
+    ) -> None:
+        """Create an audit log entry for a single tool call."""
+        try:
+            from app.core.audit import log_audit
+
+            await log_audit(
+                db=db,
+                tenant_id=tenant_id,
+                user_id=user_id,
+                action="agent.tool_call",
+                entity_type="agent_run",
+                entity_id=agent_run_id,
+                details={
+                    "agent_run_id": str(agent_run_id) if agent_run_id else None,
+                    "step_number": step_number,
+                    "tool_name": tool_name,
+                    "arguments": arguments,
+                    "result": result[:2000],
+                    "cost_usd": cost_usd,
+                    "dry_run": dry_run,
+                },
+            )
+        except Exception:
+            logger.exception("Failed to audit tool call '%s'", tool_name)
+
     for step_num in range(1, max_steps + 1):
         # ── Timeout check ──
         elapsed = time.monotonic() - start_time
@@ -327,9 +363,27 @@ async def run_react_loop(
                 args = {}
                 logger.warning("Invalid JSON arguments for tool '%s': %s", tool_name, tc["arguments"])
 
-            observation = await _execute_tool(tool_registry, tool_name, args, tool_context)
+            if dry_run:
+                observation = json.dumps(
+                    {
+                        "dry_run": True,
+                        "would_execute": tool_name,
+                        "arguments": args,
+                    }
+                )
+            else:
+                observation = await _execute_tool(tool_registry, tool_name, args, tool_context)
             observations.append(observation)
 
+            # Audit every tool call (real or simulated)
+            await _audit_tool_call(
+                step_number=step_num,
+                tool_name=tool_name,
+                arguments=args,
+                result=observation,
+                cost_usd=cost_usd / len(tool_calls) if tool_calls else cost_usd,
+            )
+
             # Feed tool result back into conversation
             full_messages.append({
                 "role": "tool",

app/ai/agent_permissions.py

@@ -0,0 +1,230 @@
+"""Agent permission context resolution for AI agents.
+
+Resolves the effective permissions available to an agent run as the
+intersection of the user's (or run-as user's) RBAC permissions, the agent's
+configured tools/skills, and the tools each skill is allowed to use.
+
+Effective = User/Run-as ∩ Agent ∩ Skill ∩ Tool
+
+Key principles:
+- Skills orchestrate tools but NEVER grant additional permissions.
+- Every tool/service call re-checks permissions — rights are NOT frozen
+  for a run.
+- System admins get all tools.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.error_codes import ApiError
+from app.core.permissions import check_permission, resolve_permissions
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AgentPermissionContext:
+    """Effective permission context for a single agent run."""
+
+    user_id: uuid.UUID
+    tenant_id: uuid.UUID
+    run_as_user_id: uuid.UUID | None
+    user_permissions: dict[str, Any]  # RBAC permissions from Role
+    agent_tool_ids: list[str]
+    agent_skill_ids: list[str]
+    effective_tool_ids: list[str]  # After intersection
+    is_system_admin: bool = False
+
+    def has_permission(self, permission: str) -> bool:
+        """Check whether the run-as user has the given RBAC permission."""
+        return check_permission(self.user_permissions, permission)
+
+    def can_use_tool(self, tool_id: str) -> bool:
+        """Check whether the agent may call the given tool."""
+        return tool_id in self.effective_tool_ids
+
+
+def _resolve_effective_tool_ids(
+    agent_definition: Any,
+    user_permissions: dict[str, Any],
+) -> list[str]:
+    """Compute the effective tool IDs after User ∩ Agent ∩ Skill ∩ Tool.
+
+    Mirrors the semantics of ``app.ai.agent_tools.get_agent_tools``: skills
+    orchestrate tools but never grant additional permissions.
+    """
+    from app.ai.skill_registry import get_skill_registry
+    from app.plugins.builtins.ai_assistant.contracts import get_tool_registry
+
+    agent_tool_ids: list[str] = list(getattr(agent_definition, "tool_ids", None) or [])
+    agent_skill_ids: list[str] = list(getattr(agent_definition, "skill_ids", None) or [])
+
+    skill_registry = get_skill_registry()
+    skills = skill_registry.get_by_names(agent_skill_ids)
+
+    direct_tool_ids = set(agent_tool_ids)
+    skill_tool_ids: set[str] = set()
+    for skill in skills:
+        skill_tool_ids.update(skill.allowed_tool_ids or [])
+
+    # Tools directly on the agent, plus tools reachable via skills that are
+    # also directly on the agent (skills never widen the agent's tool set).
+    available_tool_ids = direct_tool_ids | (direct_tool_ids & skill_tool_ids)
+
+    tool_registry = get_tool_registry()
+    tools = tool_registry.get_by_names(sorted(available_tool_ids))
+
+    permitted = [
+        tool
+        for tool in tools
+        if not getattr(tool, "required_permission", None)
+        or check_permission(user_permissions, tool.required_permission)
+    ]
+    return [tool.name for tool in permitted]
+
+
+async def resolve_agent_permissions(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    user_id: uuid.UUID,
+    agent_definition: Any,
+    run_as_user_id: uuid.UUID | None = None,
+) -> AgentPermissionContext:
+    """Resolve effective permissions for an agent run.
+
+    Effective = User/Run-as ∩ Agent ∩ Skill ∩ Tool.
+
+    Args:
+        db: Async DB session.
+        tenant_id: Tenant ID for multi-tenancy.
+        user_id: The user requesting the run (permission source).
+        agent_definition: AgentDefinition with tool_ids and skill_ids.
+        run_as_user_id: Optional user the agent runs as. When provided, the
+            run-as user's permissions are used instead of the requester's.
+
+    Returns:
+        AgentPermissionContext with the resolved effective tool IDs.
+    """
+    effective_user_id = run_as_user_id or user_id
+    user_permissions = await resolve_permissions(db, effective_user_id, tenant_id)
+    is_system_admin = bool(user_permissions.get("is_system_admin", False))
+
+    agent_tool_ids: list[str] = list(getattr(agent_definition, "tool_ids", None) or [])
+    agent_skill_ids: list[str] = list(getattr(agent_definition, "skill_ids", None) or [])
+
+    if is_system_admin:
+        effective_tool_ids = list(agent_tool_ids)
+    else:
+        effective_tool_ids = _resolve_effective_tool_ids(agent_definition, user_permissions)
+
+    return AgentPermissionContext(
+        user_id=user_id,
+        tenant_id=tenant_id,
+        run_as_user_id=run_as_user_id,
+        user_permissions=user_permissions,
+        agent_tool_ids=agent_tool_ids,
+        agent_skill_ids=agent_skill_ids,
+        effective_tool_ids=effective_tool_ids,
+        is_system_admin=is_system_admin,
+    )
+
+
+async def check_entity_lock(
+    db: AsyncSession,
+    entity_type: str,
+    entity_id: uuid.UUID,
+    expected_version: int,
+) -> bool:
+    """Optimistic-lock check: raise ApiError('conflict') on version mismatch.
+
+    Loads the entity's ``version`` column. If the current version differs from
+    ``expected_version``, raises ``ApiError`` with code ``conflict``. Models
+    without a ``version`` column are treated as unlocked (no-op).
+
+    Returns True when the lock check passes.
+    """
+    from app.services.entity_permission_service import ENTITY_MODELS
+
+    model = ENTITY_MODELS.get(entity_type)
+    if model is None or not hasattr(model, "version"):
+        return True
+
+    result = await db.execute(select(model.version).where(model.id == entity_id))
+    current_version = result.scalar_one_or_none()
+    if current_version is None:
+        raise ApiError(code="not_found", detail=f"{entity_type} not found")
+
+    if int(current_version) != int(expected_version):
+        raise ApiError(
+            code="conflict",
+            detail=(
+                f"{entity_type} {entity_id} was modified concurrently "
+                f"(expected version {expected_version}, current {current_version})"
+            ),
+        )
+    return True
+
+
+async def filter_visible_agents(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    user_id: uuid.UUID,
+    agents: list,
+) -> list:
+    """Filter agents visible to a user based on agents:read + EntityPermission.
+
+    A user sees an agent when they have the ``agents:read`` permission AND the
+    agent is visible via ownership, tenant-ownership, or entity_permissions.
+    System admins see all agents.
+    """
+    user_permissions = await resolve_permissions(db, user_id, tenant_id)
+    if user_permissions.get("is_system_admin"):
+        return list(agents)
+    if not check_permission(user_permissions, "agents:read"):
+        return []
+
+    from app.services.permission_resolver import get_visible_ids
+
+    visible_ids, _ = await get_visible_ids(db, tenant_id, user_id, "agent_definition")
+    return [a for a in agents if a.id in visible_ids]
+
+
+async def check_agent_execute_permission(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    user_id: uuid.UUID,
+    agent_id: uuid.UUID,
+) -> bool:
+    """Check if a user has agents:execute permission for a specific agent.
+
+    Requires the ``agents:execute`` RBAC permission AND entity-level access
+    (owner, tenant-owned, or shared via entity_permissions). System admins
+    always pass.
+    """
+    user_permissions = await resolve_permissions(db, user_id, tenant_id)
+    if user_permissions.get("is_system_admin"):
+        return True
+    if not check_permission(user_permissions, "agents:execute"):
+        return False
+
+    from app.services.permission_resolver import check_entity_access
+
+    return await check_entity_access(
+        db, tenant_id, user_id, "agent_definition", agent_id, required_level="read"
+    )
+
+
+__all__ = [
+    "AgentPermissionContext",
+    "resolve_agent_permissions",
+    "check_entity_lock",
+    "filter_visible_agents",
+    "check_agent_execute_permission",
+]

app/ai/ai_use_case.py

@@ -0,0 +1,156 @@
+"""AI use-case metadata and validation.
+
+Defines the structured metadata that describes *why* and *how* an AI agent
+may process data. This is the governance contract for an agent definition:
+which data categories it may touch, which providers/models/actions are
+allowed, and whether human oversight is required.
+
+Used by:
+- ``app/ai/data_policy.py`` — runtime enforcement of allowed data categories
+- ``app/ai/oversight.py`` — human-review policy (``oversight_policy``)
+- ``app/plugins/builtins/automation/agent_routes.py`` — PATCH/GET endpoints
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+# ──────────────────────────────────────────────────────────────────────────
+# Constants
+# ──────────────────────────────────────────────────────────────────────────
+
+# Known data categories an agent may declare it processes.
+KNOWN_DATA_CATEGORIES = (
+    "contact_data",
+    "email_content",
+    "calendar",
+    "tasks",
+    "dms",
+    "communication",
+    "financial",
+    "public",
+)
+
+# Valid oversight policies.
+OVERSIGHT_POLICIES = ("always_required", "on_high_risk", "never")
+
+# Valid risk classes.
+RISK_CLASSES = ("low", "medium", "high")
+
+# Valid allowed actions.
+KNOWN_ACTIONS = ("read", "summarize", "draft", "send", "create", "update", "delete")
+
+
+class AIUseCaseMetadata(BaseModel):
+    """Structured metadata describing an AI agent's intended use case.
+
+    Attributes:
+        intended_purpose: Human-readable description of the use case.
+        owner: User ID or email responsible for the use case.
+        data_categories: Data categories the agent may process.
+        allowed_providers: Provider IDs the agent may use (empty = any).
+        allowed_models: Model names the agent may use (empty = any).
+        allowed_actions: Actions the agent may perform (empty = any).
+        oversight_policy: When human review is required.
+        risk_class: Risk classification of the use case.
+        human_review_required: Whether a human must review outputs.
+    """
+
+    intended_purpose: str = Field(default="", max_length=1000)
+    owner: str = Field(default="", max_length=255)
+    data_categories: list[str] = Field(default_factory=list)
+    allowed_providers: list[str] = Field(default_factory=list)
+    allowed_models: list[str] = Field(default_factory=list)
+    allowed_actions: list[str] = Field(default_factory=list)
+    oversight_policy: str = Field(default="never")
+    risk_class: str = Field(default="low")
+    human_review_required: bool = False
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> "AIUseCaseMetadata":
+        """Build metadata from a raw dict (e.g. the agent's JSONB column)."""
+        if not data:
+            return cls()
+        # Only pass known fields so unknown keys don't break validation.
+        known = {k: v for k, v in data.items() if k in cls.model_fields}
+        return cls(**known)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to a plain dict for JSONB storage."""
+        return self.model_dump()
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Validation
+# ──────────────────────────────────────────────────────────────────────────
+
+
+def validate_ai_use_case(metadata: AIUseCaseMetadata, agent_definition: Any) -> list[str]:
+    """Validate metadata against an agent configuration.
+
+    Returns a list of human-readable warnings. An empty list means the
+    metadata is consistent with the agent definition.
+
+    Checks performed:
+    - ``intended_purpose`` and ``owner`` are set.
+    - ``data_categories`` are known values.
+    - ``oversight_policy`` and ``risk_class`` are valid.
+    - ``allowed_models`` (if non-empty) include the agent's configured model.
+    - ``allowed_providers`` (if non-empty) include the agent's provider.
+    - ``human_review_required`` is consistent with ``oversight_policy``.
+    """
+    warnings: list[str] = []
+
+    if not metadata.intended_purpose.strip():
+        warnings.append("intended_purpose is empty — describe the AI use case")
+
+    if not metadata.owner.strip():
+        warnings.append("owner is empty — set a responsible user or email")
+
+    for cat in metadata.data_categories:
+        if cat not in KNOWN_DATA_CATEGORIES:
+            warnings.append(f"data_category '{cat}' is not a known category")
+
+    if metadata.oversight_policy not in OVERSIGHT_POLICIES:
+        warnings.append(
+            f"oversight_policy '{metadata.oversight_policy}' is invalid "
+            f"(expected one of {OVERSIGHT_POLICIES})"
+        )
+
+    if metadata.risk_class not in RISK_CLASSES:
+        warnings.append(
+            f"risk_class '{metadata.risk_class}' is invalid "
+            f"(expected one of {RISK_CLASSES})"
+        )
+
+    # Model / provider consistency (only if the agent pins allowed values).
+    agent_model = getattr(agent_definition, "llm_model", None)
+    if metadata.allowed_models and agent_model:
+        # Strip provider prefix for comparison (e.g. "openai/gpt-4o" -> "gpt-4o").
+        bare_model = agent_model.split("/", 1)[-1]
+        if agent_model not in metadata.allowed_models and bare_model not in metadata.allowed_models:
+            warnings.append(
+                f"agent model '{agent_model}' is not in allowed_models {metadata.allowed_models}"
+            )
+
+    agent_provider = getattr(agent_definition, "provider", None)
+    if metadata.allowed_providers and agent_provider:
+        if agent_provider not in metadata.allowed_providers:
+            warnings.append(
+                f"agent provider '{agent_provider}' is not in allowed_providers "
+                f"{metadata.allowed_providers}"
+            )
+
+    # Oversight consistency.
+    if metadata.oversight_policy == "always_required" and not metadata.human_review_required:
+        warnings.append(
+            "oversight_policy is 'always_required' but human_review_required is False"
+        )
+    if metadata.oversight_policy == "never" and metadata.human_review_required:
+        warnings.append(
+            "oversight_policy is 'never' but human_review_required is True"
+        )
+
+    return warnings

app/ai/data_policy.py

@@ -0,0 +1,210 @@
+"""Runtime provider / data policy enforcement for AI agents.
+
+Filters messages and context before they reach the LLM based on:
+- Sensitive fields (``app.core.sensitive_data.SENSITIVE_FIELDS``)
+- AI use-case metadata (allowed data categories)
+- Provider compliance (data residency / allowed data classes)
+
+This is the enforcement layer that guarantees an agent never sends data it
+is not permitted to process to a provider that is not approved for it.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.ai.ai_use_case import AIUseCaseMetadata
+from app.core.sensitive_data import (
+    SENSITIVE_FIELDS,
+    filter_for_llm_context,
+    get_data_class_for_field,
+)
+
+logger = logging.getLogger(__name__)
+
+# Data categories that map to entity types for sensitive-field filtering.
+_CATEGORY_ENTITY_MAP = {
+    "contact_data": "contact",
+    "email_content": "mail_account",
+    "communication": "mail_account",
+}
+
+
+async def enforce_data_policy(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    messages: list[dict[str, Any]],
+    agent_definition: Any,
+) -> list[dict[str, Any]]:
+    """Filter messages/context based on the data policy.
+
+    Steps:
+    1. Remove sensitive fields from any dict content in the messages.
+    2. Check AI use-case metadata for allowed data categories.
+    3. Check provider compliance for data residency requirements.
+
+    Args:
+        db: Async DB session (may be ``None`` in tests / mock mode).
+        tenant_id: Tenant ID for provider lookup.
+        messages: The chat messages to filter.
+        agent_definition: AgentDefinition with ``ai_use_case_metadata``.
+
+    Returns:
+        A new list of messages with disallowed data removed.
+    """
+    metadata = AIUseCaseMetadata.from_dict(
+        getattr(agent_definition, "ai_use_case_metadata", None)
+    )
+
+    # Provider compliance (data residency / allowed data classes).
+    compliance: dict[str, Any] | None = None
+    if db is not None and tenant_id is not None:
+        try:
+            from app.ai.llm_client import get_provider_compliance
+
+            compliance = await get_provider_compliance(db, tenant_id)
+        except Exception:
+            logger.debug("Failed to load provider compliance — skipping residency check")
+
+    filtered: list[dict[str, Any]] = []
+    for msg in messages:
+        content = msg.get("content", "")
+        if isinstance(content, dict):
+            content = _filter_dict_content(
+                content, metadata, compliance, agent_definition
+            )
+        elif isinstance(content, list):
+            content = [
+                _filter_dict_content(c, metadata, compliance, agent_definition)
+                if isinstance(c, dict)
+                else c
+                for c in content
+            ]
+        new_msg = dict(msg)
+        new_msg["content"] = content
+        filtered.append(new_msg)
+
+    return filtered
+
+
+def _filter_dict_content(
+    data: dict[str, Any],
+    metadata: AIUseCaseMetadata,
+    compliance: dict[str, Any] | None,
+    agent_definition: Any,
+) -> dict[str, Any]:
+    """Filter a single dict (entity payload) against the data policy."""
+    # 1. Remove sensitive fields (always blocked from LLM context).
+    result = _strip_sensitive_fields(data)
+
+    # 2. Enforce allowed data categories from AI use-case metadata.
+    if metadata.data_categories:
+        result = _filter_by_allowed_categories(result, metadata.data_categories)
+
+    # 3. Provider compliance — block fields whose data class the provider
+    #    is not approved to process.
+    if compliance is not None:
+        result = _filter_by_provider_compliance(result, compliance)
+
+    return result
+
+
+def _strip_sensitive_fields(data: dict[str, Any]) -> dict[str, Any]:
+    """Recursively remove any key that matches a sensitive field name."""
+    sensitive_names = set()
+    for fields in SENSITIVE_FIELDS.values():
+        sensitive_names |= fields
+
+    result: dict[str, Any] = {}
+    for key, value in data.items():
+        if key in sensitive_names:
+            continue
+        if isinstance(value, dict):
+            result[key] = _strip_sensitive_fields(value)
+        elif isinstance(value, list):
+            result[key] = [
+                _strip_sensitive_fields(v) if isinstance(v, dict) else v
+                for v in value
+            ]
+        else:
+            result[key] = value
+    return result
+
+
+def _filter_by_allowed_categories(
+    data: dict[str, Any], allowed_categories: list[str]
+) -> dict[str, Any]:
+    """Remove entity-type payloads whose category is not allowed.
+
+    Uses the category→entity mapping to decide whether a dict represents a
+    disallowed entity type. Unknown dicts are kept (fail-open for generic
+    context that has no clear entity type).
+    """
+    # Determine the entity type of this dict by checking for known keys.
+    entity_type = _guess_entity_type(data)
+    if entity_type is None:
+        return data
+
+    category = _entity_to_category(entity_type)
+    if category is not None and category not in allowed_categories:
+        return {}
+    return data
+
+
+def _filter_by_provider_compliance(
+    data: dict[str, Any], compliance: dict[str, Any]
+) -> dict[str, Any]:
+    """Remove fields whose data class the provider may not process."""
+    allowed_classes = compliance.get("allowed_data_classes") or []
+    if not allowed_classes:
+        return data  # No restriction configured (fail-open).
+
+    from app.core.sensitive_data import check_provider_compliance
+
+    result: dict[str, Any] = {}
+    for key, value in data.items():
+        if isinstance(value, dict):
+            result[key] = _filter_by_provider_compliance(value, compliance)
+            continue
+        # Determine data class for this field (best-effort).
+        data_class = _guess_data_class(key, value)
+        if check_provider_compliance(allowed_classes, data_class):
+            result[key] = value
+    return result
+
+
+def _guess_entity_type(data: dict[str, Any]) -> str | None:
+    """Best-effort guess of the entity type from dict keys."""
+    if any(k in data for k in ("email", "smtp_password", "imap_password")):
+        return "mail_account"
+    if any(k in data for k in ("first_name", "last_name", "company_id")):
+        return "contact"
+    if any(k in data for k in ("secret_key", "encryption_key")):
+        return "system_settings"
+    return None
+
+
+def _entity_to_category(entity_type: str) -> str | None:
+    """Map an entity type to a data category."""
+    for category, entity in _CATEGORY_ENTITY_MAP.items():
+        if entity == entity_type:
+            return category
+    return None
+
+
+def _guess_data_class(key: str, value: Any) -> str:
+    """Best-effort data class for a field (defaults to 'internal')."""
+    # Sensitive field names are always critical.
+    for fields in SENSITIVE_FIELDS.values():
+        if key in fields:
+            return "critical"
+    # Heuristic: values that look like credentials/tokens are critical.
+    if isinstance(value, str) and any(
+        marker in key.lower() for marker in ("password", "token", "secret", "key")
+    ):
+        return "critical"
+    return "internal"

app/ai/oversight.py

@@ -0,0 +1,108 @@
+"""Human oversight and decision records for AI agents.
+
+Stores a durable audit trail of AI recommendations and the human decisions
+made on them. A ``DecisionRecord`` captures the recommendation, the evidence
+that supported it, and the reviewer's decision (approved / rejected) with an
+explanation when the decision deviates from the recommendation.
+
+Used by:
+- ``app/ai/agent_loop.py`` — recording recommendations that need review
+- ``app/plugins/builtins/automation`` — agent run oversight
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+from sqlalchemy import String, Text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.core.db import Base, TenantMixin
+from app.models.owned_mixin import OwnedMixin
+
+
+@dataclass
+class DecisionRecord:
+    """A recommendation and its human decision, for the audit trail.
+
+    Attributes:
+        agent_run_id: The agent run this decision belongs to.
+        recommendation: The AI's recommendation text.
+        evidence: Supporting data for the recommendation.
+        reviewer_id: The human reviewer (None while pending).
+        decision: ``approved``, ``rejected``, or ``None`` (pending).
+        decision_timestamp: ISO timestamp of the decision (None while pending).
+        deviation_note: Explanation when the decision differs from the
+            recommendation.
+    """
+
+    agent_run_id: uuid.UUID
+    recommendation: str
+    evidence: dict[str, Any] = field(default_factory=dict)
+    reviewer_id: uuid.UUID | None = None
+    decision: str | None = None  # "approved", "rejected", None (pending)
+    decision_timestamp: str | None = None
+    deviation_note: str | None = None
+
+
+class DecisionRecordDB(Base, TenantMixin, OwnedMixin):
+    """Persistent storage for AI decision records (audit trail)."""
+
+    __tablename__ = "ai_decision_records"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    agent_run_id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True), nullable=False, index=True
+    )
+    recommendation: Mapped[str] = mapped_column(Text, nullable=False)
+    evidence: Mapped[dict[str, Any]] = mapped_column(
+        JSONB, nullable=False, default=dict
+    )
+    reviewer_id: Mapped[uuid.UUID | None] = mapped_column(
+        PGUUID(as_uuid=True), nullable=True
+    )
+    decision: Mapped[str | None] = mapped_column(String(20), nullable=True)
+    decision_timestamp: Mapped[str | None] = mapped_column(
+        String(40), nullable=True
+    )
+    deviation_note: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+
+async def create_decision_record(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    record: DecisionRecord,
+) -> uuid.UUID:
+    """Store a decision record for the audit trail.
+
+    Args:
+        db: Async DB session.
+        tenant_id: Tenant ID.
+        record: The decision record to persist.
+
+    Returns:
+        The UUID of the created record.
+    """
+    entry = DecisionRecordDB(
+        tenant_id=tenant_id,
+        agent_run_id=record.agent_run_id,
+        recommendation=record.recommendation,
+        evidence=record.evidence or {},
+        reviewer_id=record.reviewer_id,
+        decision=record.decision,
+        decision_timestamp=record.decision_timestamp
+        or (datetime.now(UTC).isoformat() if record.decision else None),
+        deviation_note=record.deviation_note,
+        owner_id=record.reviewer_id,
+    )
+    db.add(entry)
+    await db.flush()
+    return entry.id

app/ai/transparency.py

@@ -0,0 +1,60 @@
+"""AI transparency helpers.
+
+Provides utilities to mark content as AI-generated and to detect whether a
+communication participant is an AI agent. This is the transparency layer
+required by the AI governance framework: any content produced by an AI agent
+must be identifiable as such.
+
+Used by:
+- ``app/plugins/builtins/kommunikation`` — marking AI agent messages
+- ``app/ai/agent_loop.py`` — tagging final outputs as AI-generated
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+# Participant types that represent an AI agent (not a human user).
+AI_PARTICIPANT_TYPES = ("agent", "ai", "system_ai")
+
+
+def mark_as_ai_generated(content: str, metadata: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Add AI transparency metadata to content.
+
+    Args:
+        content: The AI-generated content.
+        metadata: Optional dict with ``model`` and ``provider`` keys plus any
+            additional context to record.
+
+    Returns:
+        A dict with the original content plus an ``ai_generated`` flag and an
+        ``ai_metadata`` block containing model, provider, timestamp, and any
+        extra metadata passed in.
+    """
+    metadata = metadata or {}
+    return {
+        "content": content,
+        "ai_generated": True,
+        "ai_metadata": {
+            "model": metadata.get("model", "unknown"),
+            "provider": metadata.get("provider", "unknown"),
+            "timestamp": datetime.now(UTC).isoformat(),
+            **metadata,
+        },
+    }
+
+
+def is_ai_participant(participant_id: str, participant_type: str) -> bool:
+    """Check if a participant is an AI agent.
+
+    Args:
+        participant_id: The participant's ID (unused for the check, kept for
+            API symmetry and future heuristics).
+        participant_type: The participant type string (e.g. ``user``,
+            ``agent``, ``ai``, ``system_ai``).
+
+    Returns:
+        ``True`` if the participant type is an AI agent type.
+    """
+    return participant_type in AI_PARTICIPANT_TYPES