sernixa-cli 0.1.1__tar.gz

sernixa_cli-0.1.1/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: sernixa-cli
+Version: 0.1.1
+Summary: Official Sernixa CLI for policy-governed local AI agent actions
+Author: Sernixa Team
+License-Expression: MIT
+Project-URL: Homepage, https://sernixa.com
+Project-URL: Repository, https://github.com/abhishekdhull63/Sernixa.ai-Web
+Project-URL: Documentation, https://github.com/abhishekdhull63/Sernixa.ai-Web/tree/main/docs/cli.md
+Keywords: sernixa,cli,governance,agents,policy
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: sernixa>=0.3.1
+Requires-Dist: typer>=0.12.0
+
+# Sernixa CLI
+
+The official terminal client for evaluating local AI-agent actions against the real Sernixa control plane.
+
+From the repository root:
+
+```bash
+python3 -m venv .venv-cli
+source .venv-cli/bin/activate
+pip install -e packages/sernixa -e apps/cli
+sernixa auth login
+sernixa validate payload.json
+```
+
+The CLI defaults to `https://api.sernixa.com`. It never evaluates policy locally and never stores raw credentials outside the protected user configuration file.
+
+## Governance commands
+
+Exit codes are stable for shell and CI use:
+
+* 0: allowed / success
+* 1: denied by policy
+* 2: operational error such as config, parsing, auth, or network failure
+
+Core commands:
+
+    sernixa validate payload.json
+    cat payload.json | sernixa validate --json
+    sernixa validate --from-claude < claude-hook-payload.json
+    sernixa validate --from-codex < codex-hook-payload.jsonl
+    sernixa validate-plan --agent-type codex codex-plan.json
+    sernixa validate-many --output json policies/*.json
+    sernixa exec --plan plan.json -- npm test
+    sernixa codex-exec --plan codex-plan.json -- codex exec "fix lint"
+    sernixa doctor --json
+
+validate accepts plain Sernixa governance JSON by default. --from-claude and
+--from-codex parse provider-native hook payloads and map them into the same
+governance request before calling the real Python SDK Client.governance_test()
+endpoint.
+
+watch currently validates newline-delimited JSON action streams:
+
+    generate-actions | sernixa watch --json --plan-stream -
+
+It does not claim side-effect streaming enforcement for arbitrary child
+processes until the backend exposes a streaming governance contract.
+
+validate-plan calls the canonical agent-plan governance endpoint. Plan files
+can be either a JSON array of steps or an object with a plan array. Each step
+uses the shared schema: tool_name, action, arguments, resource, and metadata.
+The backend records a governance_agent_plan_evaluated audit event with a
+redacted plan and plan hash.
+
+## Local agent hooks and MCP integrations
+
+Print hook snippets:
+
+    sernixa hook claude
+    sernixa hook claude-desktop
+    sernixa hook codex --json
+
+Best-effort install:
+
+    sernixa hook install claude
+    sernixa hook install claude-desktop
+    sernixa hook install codex
+
+Repair stale or duplicate Sernixa-managed entries:
+
+    sernixa hook repair claude
+    sernixa hook repair claude-desktop
+    sernixa hook repair codex
+
+Inspect all supported targets:
+
+    sernixa hook status
+    sernixa hook status --json
+
+Sernixa resolves local agent config targets through the shared OS-aware target
+resolver. If an official target location is uncertain, the CLI reports the
+selected path, alternates found, and any uncertainty instead of inventing a
+hidden path.
+
+Supported install/status targets:
+
+- `claude` / Claude Code: global user JSON settings, default
+  `~/.claude/settings.json`, override `SERNIXA_CLAUDE_CONFIG_FILE`.
+- `claude-desktop` / Claude Desktop: MCP server block in the official app config:
+  - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+  - Windows: `%APPDATA%\Claude\claude_desktop_config.json`, with packaged
+    `%LOCALAPPDATA%\Packages\...\LocalCache\Roaming\Claude\claude_desktop_config.json`
+    fallbacks when they already exist
+  - Linux: `~/.config/Claude/claude_desktop_config.json`
+  - override `SERNIXA_CLAUDE_DESKTOP_CONFIG_FILE`
+- `codex` / Codex: global user config only. The resolver inspects
+  `~/.codex/hooks.json` and `~/.codex/config.toml`. Both files may exist and
+  both may contain hook state. Status reports `hooks_json_present`,
+  `inline_toml_hooks_present`, `detected_hook_sources`, and
+  `sernixa_installed_in` instead of pretending only one file is active. Install
+  writes to the primary write target: existing `hooks.json` first, existing
+  `config.toml` when `hooks.json` is absent, and `hooks.json` when neither
+  exists. Overrides: `SERNIXA_CODEX_HOOKS_FILE`, `SERNIXA_CODEX_CONFIG_FILE`.
+  Codex status also separates `hooks_declared`, `hooks_enabled`, and
+  `hooks_effective`. A dedicated `hooks.json` declaration is treated as enabled
+  by that file. Inline TOML hook declarations require an explicit enablement
+  signal such as `hooks.enabled = true` or the status output will include an
+  `activation_hint`.
+
+Project-scoped `.codex/` files are intentionally ignored by these commands
+unless a future command explicitly adds project mode. Existing files are backed
+up before changes. Empty configs are treated as empty. Invalid JSON/TOML fails
+closed with the exact broken file path and remediation guidance. If both Codex
+global files contain Sernixa-managed hooks, status reports a duplicate install
+and `sernixa hook repair codex` keeps the primary write target while removing
+duplicate Sernixa-managed entries from the alternate file.
+
+`sernixa hook status --json` returns the same core fields for every supported
+target: `target_id`, `target_name`, `supported`, `install_mode`,
+`config_format`, `candidate_paths`, `primary_write_target`, `existing_paths`,
+`parse_errors`, `detected_sources`, `sernixa_installed`,
+`sernixa_installed_in`, `wrapper_valid`, `malformed`, `hooks_declared`,
+`hooks_enabled`, `hooks_effective`, `activation_hint`, and `repair_hint`.
+Serialized JSON paths are always absolute; human output may shorten paths for
+readability.
+
+The installed hooks call sernixa hook run <provider>, which reads provider JSON
+on stdin, calls live Sernixa governance, and emits provider-specific deny JSON
+when policy blocks a tool call.
+
+## Bootstrap
+
+    sernixa init
+    sernixa init --chat
+    sernixa init --claude
+    sernixa init --codex
+
+init requires an interactive terminal, validates the API key before writing
+config, writes the config with private file permissions, and never echoes the
+key back to the terminal.
+
+For chat agents, use the Python SDK adapter layer:
+
+    from sernixa import Client
+    from sernixa.adapters import SernixaAgentGuard, chat_plan_step
+
+    guard = SernixaAgentGuard(Client(), agent_type="chat", user_identity=user, context=context)
+    guard.declare_plan([chat_plan_step(tool_name="calendar.create", action="calendar.write", arguments=args)])
+    guard.execute_tool(calendar_create, tool_name="calendar.create", action="calendar.write", arguments=args)
+
+## Deferred audit commands
+
+sernixa events, sernixa decisions, and sernixa replay <decision-id> are present
+but return operational errors until the backend exposes supported audit listing
+/ decision replay endpoints for CLI use.

sernixa_cli-0.1.1/README.md

@@ -0,0 +1,155 @@
+# Sernixa CLI
+
+The official terminal client for evaluating local AI-agent actions against the real Sernixa control plane.
+
+From the repository root:
+
+```bash
+python3 -m venv .venv-cli
+source .venv-cli/bin/activate
+pip install -e packages/sernixa -e apps/cli
+sernixa auth login
+sernixa validate payload.json
+```
+
+The CLI defaults to `https://api.sernixa.com`. It never evaluates policy locally and never stores raw credentials outside the protected user configuration file.
+
+## Governance commands
+
+Exit codes are stable for shell and CI use:
+
+* 0: allowed / success
+* 1: denied by policy
+* 2: operational error such as config, parsing, auth, or network failure
+
+Core commands:
+
+    sernixa validate payload.json
+    cat payload.json | sernixa validate --json
+    sernixa validate --from-claude < claude-hook-payload.json
+    sernixa validate --from-codex < codex-hook-payload.jsonl
+    sernixa validate-plan --agent-type codex codex-plan.json
+    sernixa validate-many --output json policies/*.json
+    sernixa exec --plan plan.json -- npm test
+    sernixa codex-exec --plan codex-plan.json -- codex exec "fix lint"
+    sernixa doctor --json
+
+validate accepts plain Sernixa governance JSON by default. --from-claude and
+--from-codex parse provider-native hook payloads and map them into the same
+governance request before calling the real Python SDK Client.governance_test()
+endpoint.
+
+watch currently validates newline-delimited JSON action streams:
+
+    generate-actions | sernixa watch --json --plan-stream -
+
+It does not claim side-effect streaming enforcement for arbitrary child
+processes until the backend exposes a streaming governance contract.
+
+validate-plan calls the canonical agent-plan governance endpoint. Plan files
+can be either a JSON array of steps or an object with a plan array. Each step
+uses the shared schema: tool_name, action, arguments, resource, and metadata.
+The backend records a governance_agent_plan_evaluated audit event with a
+redacted plan and plan hash.
+
+## Local agent hooks and MCP integrations
+
+Print hook snippets:
+
+    sernixa hook claude
+    sernixa hook claude-desktop
+    sernixa hook codex --json
+
+Best-effort install:
+
+    sernixa hook install claude
+    sernixa hook install claude-desktop
+    sernixa hook install codex
+
+Repair stale or duplicate Sernixa-managed entries:
+
+    sernixa hook repair claude
+    sernixa hook repair claude-desktop
+    sernixa hook repair codex
+
+Inspect all supported targets:
+
+    sernixa hook status
+    sernixa hook status --json
+
+Sernixa resolves local agent config targets through the shared OS-aware target
+resolver. If an official target location is uncertain, the CLI reports the
+selected path, alternates found, and any uncertainty instead of inventing a
+hidden path.
+
+Supported install/status targets:
+
+- `claude` / Claude Code: global user JSON settings, default
+  `~/.claude/settings.json`, override `SERNIXA_CLAUDE_CONFIG_FILE`.
+- `claude-desktop` / Claude Desktop: MCP server block in the official app config:
+  - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+  - Windows: `%APPDATA%\Claude\claude_desktop_config.json`, with packaged
+    `%LOCALAPPDATA%\Packages\...\LocalCache\Roaming\Claude\claude_desktop_config.json`
+    fallbacks when they already exist
+  - Linux: `~/.config/Claude/claude_desktop_config.json`
+  - override `SERNIXA_CLAUDE_DESKTOP_CONFIG_FILE`
+- `codex` / Codex: global user config only. The resolver inspects
+  `~/.codex/hooks.json` and `~/.codex/config.toml`. Both files may exist and
+  both may contain hook state. Status reports `hooks_json_present`,
+  `inline_toml_hooks_present`, `detected_hook_sources`, and
+  `sernixa_installed_in` instead of pretending only one file is active. Install
+  writes to the primary write target: existing `hooks.json` first, existing
+  `config.toml` when `hooks.json` is absent, and `hooks.json` when neither
+  exists. Overrides: `SERNIXA_CODEX_HOOKS_FILE`, `SERNIXA_CODEX_CONFIG_FILE`.
+  Codex status also separates `hooks_declared`, `hooks_enabled`, and
+  `hooks_effective`. A dedicated `hooks.json` declaration is treated as enabled
+  by that file. Inline TOML hook declarations require an explicit enablement
+  signal such as `hooks.enabled = true` or the status output will include an
+  `activation_hint`.
+
+Project-scoped `.codex/` files are intentionally ignored by these commands
+unless a future command explicitly adds project mode. Existing files are backed
+up before changes. Empty configs are treated as empty. Invalid JSON/TOML fails
+closed with the exact broken file path and remediation guidance. If both Codex
+global files contain Sernixa-managed hooks, status reports a duplicate install
+and `sernixa hook repair codex` keeps the primary write target while removing
+duplicate Sernixa-managed entries from the alternate file.
+
+`sernixa hook status --json` returns the same core fields for every supported
+target: `target_id`, `target_name`, `supported`, `install_mode`,
+`config_format`, `candidate_paths`, `primary_write_target`, `existing_paths`,
+`parse_errors`, `detected_sources`, `sernixa_installed`,
+`sernixa_installed_in`, `wrapper_valid`, `malformed`, `hooks_declared`,
+`hooks_enabled`, `hooks_effective`, `activation_hint`, and `repair_hint`.
+Serialized JSON paths are always absolute; human output may shorten paths for
+readability.
+
+The installed hooks call sernixa hook run <provider>, which reads provider JSON
+on stdin, calls live Sernixa governance, and emits provider-specific deny JSON
+when policy blocks a tool call.
+
+## Bootstrap
+
+    sernixa init
+    sernixa init --chat
+    sernixa init --claude
+    sernixa init --codex
+
+init requires an interactive terminal, validates the API key before writing
+config, writes the config with private file permissions, and never echoes the
+key back to the terminal.
+
+For chat agents, use the Python SDK adapter layer:
+
+    from sernixa import Client
+    from sernixa.adapters import SernixaAgentGuard, chat_plan_step
+
+    guard = SernixaAgentGuard(Client(), agent_type="chat", user_identity=user, context=context)
+    guard.declare_plan([chat_plan_step(tool_name="calendar.create", action="calendar.write", arguments=args)])
+    guard.execute_tool(calendar_create, tool_name="calendar.create", action="calendar.write", arguments=args)
+
+## Deferred audit commands
+
+sernixa events, sernixa decisions, and sernixa replay <decision-id> are present
+but return operational errors until the backend exposes supported audit listing
+/ decision replay endpoints for CLI use.

sernixa_cli-0.1.1/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "sernixa-cli"
+version = "0.1.1"
+description = "Official Sernixa CLI for policy-governed local AI agent actions"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Sernixa Team" }]
+keywords = ["sernixa", "cli", "governance", "agents", "policy"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+]
+dependencies = [
+    "platformdirs>=4.0.0",
+    "sernixa>=0.3.1",
+    "typer>=0.12.0",
+]
+
+[project.urls]
+Homepage = "https://sernixa.com"
+Repository = "https://github.com/abhishekdhull63/Sernixa.ai-Web"
+Documentation = "https://github.com/abhishekdhull63/Sernixa.ai-Web/tree/main/docs/cli.md"
+
+[project.scripts]
+sernixa = "sernixa_cli.main:app"
+
+[build-system]
+requires = ["setuptools>=69.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["sernixa_cli*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

sernixa_cli-0.1.1/sernixa_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Official Sernixa command-line client."""
+
+__version__ = "0.1.1"

sernixa_cli-0.1.1/sernixa_cli/__main__.py

@@ -0,0 +1,3 @@
+from .main import app
+
+app()

sernixa_cli-0.1.1/sernixa_cli/adapters.py

@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+
+ProviderMode = Literal["plain", "claude", "codex"]
+
+SENSITIVE_KEY_PARTS = (
+    "api_key",
+    "apikey",
+    "authorization",
+    "bearer",
+    "client_secret",
+    "password",
+    "secret",
+    "token",
+)
+
+
+class AdapterError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class CanonicalGovernanceRequest:
+    input: dict[str, Any]
+    source: ProviderMode
+
+
+def redact_sensitive(value: Any) -> Any:
+    if isinstance(value, dict):
+        redacted: dict[str, Any] = {}
+        for key, item in value.items():
+            normalized = str(key).lower().replace("-", "_")
+            if any(part in normalized for part in SENSITIVE_KEY_PARTS):
+                redacted[str(key)] = "[redacted]"
+            else:
+                redacted[str(key)] = redact_sensitive(item)
+        return redacted
+    if isinstance(value, list):
+        return [redact_sensitive(item) for item in value]
+    return value
+
+
+def load_json_payload(content: str) -> Any:
+    if not content.strip():
+        raise AdapterError("No JSON payload received.")
+    try:
+        return json.loads(content)
+    except json.JSONDecodeError:
+        return _load_json_lines(content)
+
+
+def _load_json_lines(content: str) -> list[Any]:
+    items: list[Any] = []
+    for line_number, line in enumerate(content.splitlines(), start=1):
+        if not line.strip():
+            continue
+        try:
+            items.append(json.loads(line))
+        except json.JSONDecodeError as exc:
+            raise AdapterError(
+                f"Invalid JSON at line {line_number}, column {exc.colno}: {exc.msg}"
+            ) from exc
+    if not items:
+        raise AdapterError("No JSON payload received.")
+    return items
+
+
+def read_payload_source(path: Path | None) -> str:
+    import sys
+
+    try:
+        return path.read_text(encoding="utf-8") if path else sys.stdin.read()
+    except OSError as exc:
+        raise AdapterError(f"Unable to read payload: {exc}") from exc
+
+
+def canonicalize_payload(raw: Any, *, mode: ProviderMode) -> CanonicalGovernanceRequest:
+    if mode == "plain":
+        if not isinstance(raw, dict):
+            raise AdapterError("Governance payload must be a JSON object.")
+        return CanonicalGovernanceRequest(input=raw, source="plain")
+    if mode == "claude":
+        return CanonicalGovernanceRequest(input=_claude_to_governance(raw), source="claude")
+    if mode == "codex":
+        return CanonicalGovernanceRequest(input=_codex_to_governance(raw), source="codex")
+    raise AdapterError(f"Unsupported payload adapter: {mode}")
+
+
+def payload_from_content(content: str, *, mode: ProviderMode) -> CanonicalGovernanceRequest:
+    raw = load_json_payload(content)
+    return canonicalize_payload(raw, mode=mode)
+
+
+def _claude_to_governance(raw: Any) -> dict[str, Any]:
+    if not isinstance(raw, dict):
+        raise AdapterError("Claude hook payload must be a JSON object.")
+    tool_name = _string(raw.get("tool_name") or raw.get("name"))
+    tool_input = raw.get("tool_input")
+    if tool_input is None and isinstance(raw.get("input"), dict):
+        tool_input = raw["input"]
+    if not tool_name:
+        raise AdapterError("Claude hook payload is missing tool_name.")
+    if tool_input is None:
+        raise AdapterError("Claude hook payload is missing tool_input.")
+    if not isinstance(tool_input, dict):
+        raise AdapterError("Claude hook tool_input must be a JSON object.")
+    return _provider_tool_request(
+        source="claude",
+        hook_event_name=_string(raw.get("hook_event_name")) or "PreToolUse",
+        tool_name=tool_name,
+        tool_input=tool_input,
+        provider_context={
+            "session_id": raw.get("session_id"),
+            "transcript_path": raw.get("transcript_path"),
+            "cwd": raw.get("cwd"),
+            "tool_use_id": raw.get("tool_use_id"),
+            "user": _first_present(raw, "user", "user_id", "email", "account_id"),
+        },
+    )
+
+
+def _codex_to_governance(raw: Any) -> dict[str, Any]:
+    event = _select_codex_event(raw)
+    if not isinstance(event, dict):
+        raise AdapterError("Codex payload must be a JSON object or JSON-lines stream.")
+    tool_name = _string(event.get("tool_name") or event.get("name") or event.get("tool"))
+    tool_input = event.get("tool_input")
+    if tool_input is None:
+        if isinstance(event.get("input"), dict):
+            tool_input = event["input"]
+        elif isinstance(event.get("arguments"), dict):
+            tool_input = event["arguments"]
+        elif event.get("command") or event.get("cmd"):
+            tool_input = {"command": event.get("command") or event.get("cmd")}
+            tool_name = tool_name or "Bash"
+    if not tool_name:
+        raise AdapterError("Codex payload is missing tool_name.")
+    if tool_input is None:
+        raise AdapterError("Codex payload is missing tool_input.")
+    if not isinstance(tool_input, dict):
+        raise AdapterError("Codex hook tool_input must be a JSON object.")
+    return _provider_tool_request(
+        source="codex",
+        hook_event_name=_string(event.get("hook_event_name")) or "PreToolUse",
+        tool_name=tool_name,
+        tool_input=tool_input,
+        provider_context={
+            "session_id": event.get("session_id"),
+            "turn_id": event.get("turn_id"),
+            "transcript_path": event.get("transcript_path"),
+            "cwd": event.get("cwd"),
+            "model": event.get("model"),
+            "permission_mode": event.get("permission_mode"),
+            "tool_use_id": event.get("tool_use_id"),
+        },
+    )
+
+
+def _select_codex_event(raw: Any) -> Any:
+    if isinstance(raw, dict):
+        return raw
+    if not isinstance(raw, list):
+        return raw
+    candidates = [
+        item
+        for item in raw
+        if isinstance(item, dict)
+        and (
+            item.get("hook_event_name") in {"PreToolUse", "PermissionRequest"}
+            or item.get("tool_name")
+            or item.get("command")
+            or item.get("cmd")
+        )
+    ]
+    if not candidates:
+        raise AdapterError("No recognizable Codex tool event found in JSON-lines stream.")
+    return candidates[-1]
+
+
+def _provider_tool_request(
+    *,
+    source: ProviderMode,
+    hook_event_name: str,
+    tool_name: str,
+    tool_input: dict[str, Any],
+    provider_context: dict[str, Any],
+) -> dict[str, Any]:
+    sanitized_input = redact_sensitive(tool_input)
+    action = _action_for_tool(tool_name, sanitized_input)
+    return {
+        "schema_version": "sernixa.governance_request.v1",
+        "source": source,
+        "provider": source,
+        "hook_event_name": hook_event_name,
+        "tool_name": tool_name,
+        "action": action["action"],
+        "operation_class": action["operation_class"],
+        "resource": action.get("resource"),
+        "intent": action.get("intent"),
+        "parameters": sanitized_input,
+        "provider_context": {
+            key: value
+            for key, value in redact_sensitive(provider_context).items()
+            if value is not None
+        },
+    }
+
+
+def _action_for_tool(tool_name: str, tool_input: dict[str, Any]) -> dict[str, Any]:
+    normalized = tool_name.lower()
+    if normalized in {"bash", "shell"}:
+        command = _string(tool_input.get("command"))
+        return {
+            "action": "shell.execute",
+            "operation_class": "shell",
+            "resource": command,
+            "intent": _string(tool_input.get("description")),
+        }
+    if normalized in {"write", "edit", "multiedit", "apply_patch"}:
+        return {
+            "action": "file.write",
+            "operation_class": "write",
+            "resource": _string(tool_input.get("file_path"))
+            or _string(tool_input.get("path"))
+            or _string(tool_input.get("command")),
+            "intent": _string(tool_input.get("description")),
+        }
+    if normalized in {"read", "glob", "grep", "ls"}:
+        return {
+            "action": "file.read",
+            "operation_class": "read",
+            "resource": _string(tool_input.get("file_path"))
+            or _string(tool_input.get("path"))
+            or _string(tool_input.get("pattern")),
+            "intent": _string(tool_input.get("description")),
+        }
+    if normalized in {"webfetch", "websearch"}:
+        return {
+            "action": "network.request",
+            "operation_class": "network",
+            "resource": _string(tool_input.get("url")) or _string(tool_input.get("query")),
+            "intent": _string(tool_input.get("prompt")),
+        }
+    if normalized.startswith("mcp__"):
+        return {
+            "action": "mcp.tool",
+            "operation_class": "mcp",
+            "resource": tool_name,
+            "intent": _string(tool_input.get("description")),
+        }
+    if normalized == "agent":
+        return {
+            "action": "agent.delegate",
+            "operation_class": "delegate",
+            "resource": _string(tool_input.get("subagent_type")),
+            "intent": _string(tool_input.get("prompt")) or _string(tool_input.get("description")),
+        }
+    return {
+        "action": f"tool.{normalized}",
+        "operation_class": "tool",
+        "resource": tool_name,
+        "intent": _string(tool_input.get("description")),
+    }
+
+
+def _string(value: Any) -> str | None:
+    return value.strip() if isinstance(value, str) and value.strip() else None
+
+
+def _first_present(payload: dict[str, Any], *keys: str) -> Any:
+    for key in keys:
+        if payload.get(key) is not None:
+            return payload[key]
+    return None