@aporthq/aport-agent-guardrails 1.0.22 → 1.0.23

package/bin/openclaw

@@ -30,6 +30,48 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 APORT_PLUGIN_PATH="$REPO_ROOT/extensions/openclaw-aport"
 DEFAULT_CONFIG="${OPENCLAW_HOME:-$HOME/.openclaw}"
 
+read_local_plugin_version() {
+    if ! command -v node >/dev/null 2>&1; then
+        return 0
+    fi
+    local package_json="$APORT_PLUGIN_PATH/package.json"
+    if [ ! -f "$package_json" ]; then
+        return 0
+    fi
+    node -e '
+const fs = require("node:fs");
+try {
+  const pkg = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+  if (pkg && typeof pkg.version === "string") process.stdout.write(pkg.version);
+} catch {}
+' "$package_json"
+}
+
+read_installed_plugin_version() {
+    if ! command -v openclaw >/dev/null 2>&1 || ! command -v node >/dev/null 2>&1; then
+        return 0
+    fi
+    openclaw plugins list --json 2>/dev/null | node -e '
+let raw = "";
+process.stdin.on("data", (chunk) => {
+  raw += chunk;
+});
+process.stdin.on("end", () => {
+  const jsonStart = raw.indexOf("{");
+  if (jsonStart < 0) return;
+  try {
+    const data = JSON.parse(raw.slice(jsonStart));
+    const plugin = Array.isArray(data.plugins)
+      ? data.plugins.find((entry) => entry && entry.id === "openclaw-aport")
+      : null;
+    if (plugin && typeof plugin.version === "string") {
+      process.stdout.write(plugin.version);
+    }
+  } catch {}
+});
+'
+}
+
 # Parse command line arguments
 HOSTED_AGENT_ID=""
 if [ -n "$1" ]; then
@@ -210,19 +252,29 @@ if true; then
             echo "  Skipping plugin installation."
         fi
     else
+        LOCAL_PLUGIN_VERSION="$(read_local_plugin_version)"
+        INSTALLED_PLUGIN_VERSION="$(read_installed_plugin_version)"
         echo ""
-        echo "  Installing plugin from: $APORT_PLUGIN_PATH"
-        echo "  (Using -l to link local directory; OpenClaw accepts only registry or --link for install.)"
-        if openclaw plugins install -l "$APORT_PLUGIN_PATH" 2>&1; then
-            echo "  ✅ Plugin installed successfully"
+        if [ -n "$LOCAL_PLUGIN_VERSION" ] && [ "$LOCAL_PLUGIN_VERSION" = "$INSTALLED_PLUGIN_VERSION" ]; then
+            echo "  ✅ Plugin version $LOCAL_PLUGIN_VERSION already installed; skipping reinstall."
             PLUGIN_INSTALLED=true
         else
-            echo "  ❌ Plugin installation failed."
-            echo "     OpenClaw did not accept the plugin bundle, so setup is stopping here"
-            echo "     instead of writing plugin config that points at a broken install."
-            echo "     Retry after fixing the bundle or install it manually:"
-            echo "     openclaw plugins install -l $APORT_PLUGIN_PATH"
-            exit 1
+            if [ -n "$INSTALLED_PLUGIN_VERSION" ]; then
+                echo "  Existing openclaw-aport version: $INSTALLED_PLUGIN_VERSION"
+            fi
+            echo "  Installing plugin from: $APORT_PLUGIN_PATH"
+            echo "  (Using -l to link local directory; OpenClaw accepts only registry or --link for install.)"
+            if openclaw plugins install -l "$APORT_PLUGIN_PATH" 2>&1; then
+                echo "  ✅ Plugin installed successfully"
+                PLUGIN_INSTALLED=true
+            else
+                echo "  ❌ Plugin installation failed."
+                echo "     OpenClaw did not accept the plugin bundle, so setup is stopping here"
+                echo "     instead of writing plugin config that points at a broken install."
+                echo "     Retry after fixing the bundle or install it manually:"
+                echo "     openclaw plugins install -l $APORT_PLUGIN_PATH"
+                exit 1
+            fi
         fi
         echo ""
 
@@ -590,19 +642,18 @@ echo "   OpenClaw (or your code) calls the guardrail with a tool name and contex
 echo "   The guardrail maps that to a policy pack in external/aport-policies:"
 echo
 cat << 'TABLE'
-   Tool name (examples)              → Policy pack
-   ------------------------------------------------
-   git.create_pr, git.merge, git.*   → code.repository.merge.v1
-   exec.run, system.command.*       → system.command.execute.v1
-   message.send, messaging.*        → messaging.message.send.v1
-   mcp.tool.*, mcp.*                 → mcp.tool.execute.v1
-   agent.session.*, session.*       → agent.session.create.v1
-   agent.tool.*, tool.register      → agent.tool.register.v1
-   payment.refund, finance.*        → finance.payment.refund.v1
-   payment.charge                    → finance.payment.charge.v1
-   database.write, data.export       → data.export.create.v1
+	   Tool name (examples)              → Policy pack
+	   ------------------------------------------------
+	   git.create_pr, git.merge, git.*   → code.repository.merge.v1
+	   exec.run, system.command.*        → system.command.execute.v1
+	   message + send/reply/broadcast    → messaging.message.send.v1
+	   message + sendAttachment/react    → messaging.message.send.v1
+	   serverName__toolName, mcp__*      → mcp.tool.execute.v1
+	   read, glob, grep                  → data.file.read.v1
+	   write, edit, multiedit            → data.file.write.v1
 TABLE
-echo "   Full list: docs/TOOL_POLICY_MAPPING.md"
+echo "   Plugin mapping source: extensions/openclaw-aport/tool-mapping.js"
+echo "   Unmapped tools are allowed by default; set allowUnmappedTools: false for strict mode."
 echo
 
 # 5. Enforcement summary

package/docs/RELEASE.md

@@ -1,6 +1,6 @@
 # Release process and version policy
 
-**Current release:** 1.0.22 (see [CHANGELOG.md](../CHANGELOG.md)).
+**Current release:** 1.0.23 (see [CHANGELOG.md](../CHANGELOG.md)).
 
 We keep **one version number** across all published packages (Node core, Python core, and every framework adapter). That avoids “core is 1.2 but CLI is 0.9” and keeps the story simple for users and support.
 

package/docs/TOOL_POLICY_MAPPING.md

@@ -1,8 +1,8 @@
 # Tool → policy pack mapping
 
-OpenClaw (or any caller) invokes the guardrail with a **tool name** and **context JSON**. The guardrail maps the tool name to a **policy pack** in `external/aport-policies/` and evaluates the request against that policy and the passport.
+The shell/API guardrail entrypoints invoke the guardrail with a **tool name** and **context JSON**. The guardrail maps the tool name to a **policy pack** in `external/aport-policies/` and evaluates the request against that policy and the passport.
 
-This mapping is implemented in `bin/aport-guardrail-api.sh` and `bin/aport-guardrail-bash.sh`. The table below is the single source of truth for documentation.
+This mapping is implemented in `bin/aport-guardrail-api.sh` and `bin/aport-guardrail-bash.sh`. The OpenClaw plugin has its own host-specific mapping in `extensions/openclaw-aport/tool-mapping.js`.
 
 ## Mapping table
 

package/docs/frameworks/openclaw.md

@@ -14,6 +14,20 @@ If you already have a hosted passport on aport.io, pass the `agent_id` and skip
 npx @aporthq/aport-agent-guardrails openclaw ap_your_agent_id
 ```
 
+If you run `openclaw plugins install @aporthq/openclaw-aport` directly, that installs only the plugin bundle. It does not create a local passport or write the plugin config. Use the setup command above for the full APort + OpenClaw flow, or configure the plugin manually.
+
+After a direct plugin install, the recommended next step is:
+
+```bash
+npx @aporthq/aport-agent-guardrails openclaw
+```
+
+Hosted passport:
+
+```bash
+npx @aporthq/aport-agent-guardrails openclaw ap_your_agent_id
+```
+
 The setup command:
 
 1. Chooses your OpenClaw config directory
@@ -137,9 +151,10 @@ Common mappings include:
 
 - `exec`, `exec.run` -> `system.command.execute.v1`
 - `git.create_pr`, `git.merge`, `git.push` -> `code.repository.merge.v1`
-- `message.send` -> `messaging.message.send.v1`
+- `message` with send-family actions like `send`, `reply`, `broadcast`, `sendAttachment`, `upload-file`, or `react` -> `messaging.message.send.v1`
 - `read`, `view`, `glob` -> `data.file.read.v1`
 - `write`, `edit`, `multiedit` -> `data.file.write.v1`
+- bundle MCP tools exposed as `serverName__toolName` -> `mcp.tool.execute.v1`
 
 ## Kill switch
 

package/extensions/openclaw-aport/CHANGELOG.md

@@ -1,10 +1,17 @@
 # Changelog - APort OpenClaw Plugin
 
+## 1.0.23
+
+### Patch Changes
+
+- Fix the OpenClaw plugin and setup flow for current public OpenClaw releases. This update makes the plugin installer and setup flow more reliable, tightens tool-to-policy mapping for current OpenClaw tools like `message` and MCP bundle tools, normalizes hosted API context for file and message tools, and skips redundant plugin reinstall when the same version is already installed.
+
 All notable changes to the APort OpenClaw plugin will be documented in this file.
 
 ## [1.0.22] - 2026-04-13
 
 ### Fixed
+
 - Replaced the old shell-spawning runtime with a scanner-safe JavaScript plugin runtime for local and API evaluation.
 - Added current OpenClaw compatibility metadata in `package.json` and aligned the hook return shape with the documented `before_tool_call` contract.
 - Kept `alwaysVerifyEachToolCall` as a deprecated manifest field so existing installs continue to load during upgrade.

package/extensions/openclaw-aport/README.md

@@ -33,6 +33,28 @@ After setup, start OpenClaw with the generated config:
 openclaw gateway start --config ~/.openclaw/config.yaml
 ```
 
+## If you installed with `openclaw plugins install`
+
+If you installed the plugin directly with:
+
+```bash
+openclaw plugins install @aporthq/openclaw-aport
+```
+
+that installs only the plugin bundle. It does not create a passport, choose API vs local mode, or write plugin config.
+
+Run the full APort setup immediately after install:
+
+```bash
+npx @aporthq/aport-agent-guardrails openclaw
+```
+
+If you already have a hosted passport, use:
+
+```bash
+npx @aporthq/aport-agent-guardrails openclaw ap_your_agent_id
+```
+
 ## What OpenClaw already gives you
 
 OpenClaw already ships sandboxing, tool policy, elevated exec controls, and install-time scanning. Those are real security controls, not marketing copy.
@@ -57,6 +79,12 @@ If you are working from a local checkout, install the plugin directly from the e
 openclaw plugins install -l /path/to/aport-agent-guardrails/extensions/openclaw-aport
 ```
 
+That command installs only the OpenClaw plugin bundle. It does not create a passport, choose API vs local mode, or write plugin config. For a full working setup, use:
+
+```bash
+npx @aporthq/aport-agent-guardrails openclaw
+```
+
 Then configure it in your OpenClaw config:
 
 ```yaml
@@ -95,10 +123,10 @@ The plugin keeps the existing OpenClaw-specific tool mappings. Common examples:
 
 - `exec`, `exec.run` -> `system.command.execute.v1`
 - `git.create_pr`, `git.merge`, `git.push` -> `code.repository.merge.v1`
-- `message.send` -> `messaging.message.send.v1`
+- `message` with send-family actions like `send`, `reply`, `broadcast`, `sendAttachment`, `upload-file`, or `react` -> `messaging.message.send.v1`
 - `read`, `view`, `glob` -> `data.file.read.v1`
 - `write`, `edit`, `multiedit` -> `data.file.write.v1`
-- `mcp__*` -> `mcp.tool.execute.v1`
+- bundle MCP tools exposed as `serverName__toolName` -> `mcp.tool.execute.v1`
 
 `allowUnmappedTools: true` keeps the previous OpenClaw compatibility behavior for custom skills and unmapped tools.
 

package/extensions/openclaw-aport/api-client.js

@@ -14,7 +14,15 @@ export async function verifyViaApi({ apiUrl, apiKey, policyName, context, passpo
   });
 
   if (!response.ok) {
-    throw new Error(`API request failed: ${response.status} ${response.statusText}`);
+    let details = "";
+    try {
+      const text = await response.text();
+      if (text) details = text;
+    } catch {
+      details = "";
+    }
+    const suffix = details ? ` - ${details}` : "";
+    throw new Error(`API request failed: ${response.status} ${response.statusText}${suffix}`);
   }
 
   const data = await response.json();

package/extensions/openclaw-aport/index.js

@@ -13,7 +13,7 @@ import { homedir } from "node:os";
 import { logAuditEntry } from "./audit.js";
 import { canonicalize, formatReasons, verifyDecisionIntegrity } from "./decision.js";
 import { evaluateLocalDecision } from "./local-evaluator.js";
-import { mapToolToPolicy, normalizeExecContext } from "./tool-mapping.js";
+import { mapToolToPolicy, normalizePolicyContext } from "./tool-mapping.js";
 import { verifyViaApi } from "./api-client.js";
 
 export { canonicalize, mapToolToPolicy, verifyDecisionIntegrity };
@@ -48,7 +48,7 @@ export default definePluginEntry({
 
       try {
         const policyName =
-          toolName === "exec" && !mapExecToPolicy ? null : mapToolToPolicy(toolName);
+          toolName === "exec" && !mapExecToPolicy ? null : mapToolToPolicy(toolName, params);
 
         if (!policyName) {
           if (allowUnmappedTools) {
@@ -64,23 +64,22 @@ export default definePluginEntry({
 
         let effectivePolicyName = policyName;
         let effectiveToolName = toolName;
-        let context =
-          policyName === "system.command.execute.v1"
-            ? normalizeExecContext(params, event)
-            : (params || {});
+        let context = normalizePolicyContext(policyName, toolName, params, event);
 
         const delegated = parseGuardrailInvocation(
           effectivePolicyName === "system.command.execute.v1" ? context.command : null,
         );
         if (delegated) {
-          const innerPolicy = mapToolToPolicy(delegated.innerToolName);
+          const innerPolicy = mapToolToPolicy(delegated.innerToolName, delegated.innerContext);
           if (innerPolicy) {
             effectivePolicyName = innerPolicy;
             effectiveToolName = delegated.innerToolName;
-            context =
-              innerPolicy === "system.command.execute.v1"
-                ? normalizeExecContext(delegated.innerContext, { params: delegated.innerContext })
-                : delegated.innerContext;
+            context = normalizePolicyContext(
+              innerPolicy,
+              delegated.innerToolName,
+              delegated.innerContext,
+              { params: delegated.innerContext },
+            );
           }
         }
 

package/extensions/openclaw-aport/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-aport",
   "name": "APort Guardrails",
   "description": "Deterministic pre-action authorization via APort policy enforcement. Registers before_tool_call to block disallowed tools.",
-  "version": "1.0.22",
+  "version": "1.0.23",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/extensions/openclaw-aport/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@aporthq/openclaw-aport",
-  "version": "1.0.22",
+  "version": "1.0.23",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@aporthq/openclaw-aport",
-      "version": "1.0.22",
+      "version": "1.0.23",
       "license": "Apache-2.0",
       "devDependencies": {
         "@types/node": "^18.0.0",

package/extensions/openclaw-aport/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aporthq/openclaw-aport",
-  "version": "1.0.22",
+  "version": "1.0.23",
   "description": "OpenClaw plugin for deterministic pre-action authorization via APort guardrails",
   "main": "index.js",
   "type": "module",

package/extensions/openclaw-aport/tool-mapping.js

@@ -1,5 +1,60 @@
-export function mapToolToPolicy(toolName) {
-  const tool = String(toolName ?? "").toLowerCase();
+const MESSAGE_SEND_ACTIONS = new Set([
+  "send",
+  "broadcast",
+  "reply",
+  "thread-reply",
+  "sendwitheffect",
+  "sendattachment",
+  "upload-file",
+  "react",
+]);
+
+function firstNonEmpty(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return "";
+}
+
+function readAction(params) {
+  const src = params && typeof params === "object" ? params : {};
+  return firstNonEmpty(
+    src.action,
+    src.action_name,
+    src.actionName,
+    src.arguments && typeof src.arguments === "object" ? src.arguments.action : "",
+    src.input && typeof src.input === "object" ? src.input.action : "",
+  ).toLowerCase();
+}
+
+export function parseMcpToolName(toolName) {
+  const raw = String(toolName ?? "").trim();
+  if (!raw) return null;
+
+  if (raw.startsWith("mcp__")) {
+    const parts = raw.split("__");
+    if (parts.length >= 3 && parts[1] && parts.slice(2).join("__")) {
+      return {
+        serverName: parts[1],
+        toolName: parts.slice(2).join("__"),
+      };
+    }
+  }
+
+  const separatorIndex = raw.indexOf("__");
+  if (separatorIndex <= 0 || separatorIndex >= raw.length - 2) {
+    return null;
+  }
+
+  return {
+    serverName: raw.slice(0, separatorIndex),
+    toolName: raw.slice(separatorIndex + 2),
+  };
+}
+
+export function mapToolToPolicy(toolName, params) {
+  const rawTool = String(toolName ?? "").trim();
+  const tool = rawTool.toLowerCase();
 
   if (tool.match(/git\.(create_pr|merge|push|commit)/)) return "code.repository.merge.v1";
   if (tool.startsWith("git.")) return "code.repository.merge.v1";
@@ -10,9 +65,21 @@ export function mapToolToPolicy(toolName) {
   if (tool.startsWith("system.command.")) return "system.command.execute.v1";
   if (tool === "bash" || tool === "shell" || tool === "command") return "system.command.execute.v1";
 
-  if (tool.startsWith("message.")) return "messaging.message.send.v1";
-  if (tool.startsWith("messaging.")) return "messaging.message.send.v1";
-  if (tool.match(/sms|whatsapp|slack|email/)) return "messaging.message.send.v1";
+  if (tool === "message") {
+    return MESSAGE_SEND_ACTIONS.has(readAction(params)) ? "messaging.message.send.v1" : null;
+  }
+  if (
+    tool === "message.send" ||
+    tool === "message.reply" ||
+    tool === "message.broadcast" ||
+    tool === "message.react" ||
+    tool === "messaging.message.send"
+  ) {
+    return "messaging.message.send.v1";
+  }
+  if (tool.match(/(^|[._-])(whatsapp|telegram|slack|email)([._-](send|reply|broadcast|message|react))?$/)) {
+    return "messaging.message.send.v1";
+  }
 
   if (tool === "read") return "data.file.read.v1";
   if (tool.startsWith("file.read")) return "data.file.read.v1";
@@ -24,13 +91,8 @@ export function mapToolToPolicy(toolName) {
   }
   if (tool === "todoread") return "data.file.read.v1";
   if (tool === "todowrite") return "data.file.write.v1";
-  if (tool === "task" || tool === "taskcreate" || tool === "taskupdate" || tool === "taskstop") {
-    return "agent.session.create.v1";
-  }
   if (tool === "taskget" || tool === "tasklist" || tool === "taskoutput") return "data.file.read.v1";
-  if (tool === "agent" || tool === "skill" || tool === "enterworktree") return "agent.session.create.v1";
   if (tool === "askuserquestion" || tool === "enterplanmode" || tool === "exitplanmode") return null;
-  if (tool === "croncreate" || tool === "crondelete") return "agent.session.create.v1";
   if (tool === "cronlist") return "data.file.read.v1";
   if (tool.startsWith("file.write")) return "data.file.write.v1";
   if (tool.startsWith("file.edit")) return "data.file.write.v1";
@@ -45,25 +107,11 @@ export function mapToolToPolicy(toolName) {
   if (tool.startsWith("browser.")) return "web.browser.v1";
 
   if (tool.startsWith("mcp.")) return "mcp.tool.execute.v1";
-  if (tool.startsWith("mcp__")) return "mcp.tool.execute.v1";
-
-  if (tool.match(/agent\.session|session\.create/)) return "agent.session.create.v1";
-  if (tool === "sessions_spawn" || tool === "sessions_send") return "agent.session.create.v1";
-  if (tool.startsWith("session.") || tool.startsWith("sessions.")) return "agent.session.create.v1";
-  if (tool === "cron" || tool.startsWith("cron.")) return "agent.session.create.v1";
+  if (parseMcpToolName(rawTool)) return "mcp.tool.execute.v1";
 
   if (tool === "gateway" || tool.startsWith("gateway.")) return "system.command.execute.v1";
   if (tool === "process" || tool.startsWith("process.")) return "system.command.execute.v1";
 
-  if (tool.match(/agent\.tool|tool\.register/)) return "agent.tool.register.v1";
-
-  if (tool.match(/payment\.refund|refund/)) return "finance.payment.refund.v1";
-  if (tool.match(/payment\.charge|charge/)) return "finance.payment.charge.v1";
-  if (tool.startsWith("finance.")) return "finance.payment.refund.v1";
-
-  if (tool.match(/database\.(write|insert|update|delete)/)) return "data.export.create.v1";
-  if (tool.match(/data\.export|export/)) return "data.export.create.v1";
-
   return null;
 }
 
@@ -87,3 +135,142 @@ export function normalizeExecContext(params, event) {
   if (params && params.workdir !== undefined && out.cwd === undefined) out.cwd = params.workdir;
   return out;
 }
+
+export function normalizeFileContext(params) {
+  const src = params && typeof params === "object" ? params : {};
+  const filePath =
+    src.file_path ??
+    src.path ??
+    src.filePath ??
+    (src.arguments && typeof src.arguments === "object" ? src.arguments.file_path ?? src.arguments.path : null) ??
+    (src.input && typeof src.input === "object" ? src.input.file_path ?? src.input.path : null) ??
+    (src.args && typeof src.args === "object" ? src.args.file_path ?? src.args.path : null);
+
+  if (filePath == null || String(filePath).trim() === "") {
+    return { ...src };
+  }
+
+  return {
+    ...src,
+    file_path: String(filePath),
+  };
+}
+
+export function normalizeMessageContext(params) {
+  const src = params && typeof params === "object" ? params : {};
+  const action = readAction(src);
+  const firstTarget = Array.isArray(src.targets)
+    ? src.targets.find((value) => typeof value === "string" && value.trim())
+    : "";
+  const channelId = firstNonEmpty(
+    src.channel_id,
+    src.channelId,
+    src.target,
+    firstTarget,
+    src.channel,
+    src.to,
+    src.accountId,
+  );
+  const isAttachmentAction =
+    action === "sendattachment" ||
+    action === "upload-file" ||
+    Boolean(src.media || src.buffer || src.path || src.filePath || src.filename);
+  const messageType = action === "react" ? "reaction" : isAttachmentAction ? "file" : "text";
+  const message = firstNonEmpty(
+    src.message,
+    src.text,
+    src.content,
+    src.caption,
+    src.quoteText,
+    src.emoji,
+    isAttachmentAction ? src.filename : "",
+  );
+  const threadId = firstNonEmpty(src.thread_id, src.threadId);
+  const replyTo = firstNonEmpty(src.reply_to, src.replyTo, src.messageId, src.message_id);
+  const out = {
+    ...src,
+    message_type: src.message_type ?? messageType,
+  };
+
+  if (channelId) out.channel_id = channelId;
+  if (message) out.message = message;
+  else if (messageType === "reaction") out.message = "reaction";
+  else if (messageType === "file") out.message = "[attachment]";
+
+  if (threadId) out.thread_id = threadId;
+  if (replyTo) out.reply_to = replyTo;
+
+  if (!Array.isArray(out.attachments) && isAttachmentAction) {
+    out.attachments = [
+      {
+        ...(typeof src.media === "string" && src.media ? { url: src.media } : {}),
+        ...(typeof src.filename === "string" && src.filename ? { filename: src.filename } : {}),
+      },
+    ];
+  }
+
+  return out;
+}
+
+function buildMcpParameters(src) {
+  if (src.parameters && typeof src.parameters === "object") return src.parameters;
+  if (src.arguments && typeof src.arguments === "object") return src.arguments;
+  if (src.input && typeof src.input === "object") return src.input;
+  if (src.payload && typeof src.payload === "object") return src.payload;
+
+  const {
+    server,
+    server_url,
+    serverUrl,
+    server_name,
+    serverName,
+    tool,
+    tool_name,
+    toolName,
+    parameters,
+    ...rest
+  } = src;
+  return rest;
+}
+
+export function normalizeMcpContext(toolName, params) {
+  const src = params && typeof params === "object" ? params : {};
+  const parsed = parseMcpToolName(toolName);
+  const serverName = firstNonEmpty(
+    src.server,
+    src.server_url,
+    src.serverUrl,
+    src.server_name,
+    src.serverName,
+    src.mcp_server,
+    parsed?.serverName,
+  );
+  const normalizedServer =
+    serverName && serverName.includes("://") ? serverName : serverName ? `mcp://${serverName}` : "";
+  const tool = firstNonEmpty(src.tool, src.tool_name, src.toolName, src.mcp_tool, parsed?.toolName);
+  const out = {
+    ...src,
+    parameters: buildMcpParameters(src),
+  };
+
+  if (normalizedServer) out.server = normalizedServer;
+  if (tool) out.tool = tool;
+
+  return out;
+}
+
+export function normalizePolicyContext(policyName, toolName, params, event) {
+  if (policyName === "system.command.execute.v1") {
+    return normalizeExecContext(params, event);
+  }
+  if (policyName === "data.file.read.v1" || policyName === "data.file.write.v1") {
+    return normalizeFileContext(params);
+  }
+  if (policyName === "messaging.message.send.v1") {
+    return normalizeMessageContext(params);
+  }
+  if (policyName === "mcp.tool.execute.v1") {
+    return normalizeMcpContext(toolName, params);
+  }
+  return params || {};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aporthq/aport-agent-guardrails",
-  "version": "1.0.22",
+  "version": "1.0.23",
   "description": "Policy enforcement guardrails for OpenClaw-compatible agent frameworks",
   "workspaces": [
     "packages/*",