@drakon-systems/shieldcortex-realtime 4.43.0 → 4.44.0

package/README.md

@@ -29,6 +29,7 @@ The defensive root `openclaw.plugin.json` is kept for one release on the main pa
 |------|--------|
 | `llm_input` | Scans prompts and history through the ShieldCortex defence pipeline. Threats are logged to audit and can forward to ShieldCortex Cloud. |
 | `llm_output` | Extracts high-signal memories from assistant replies and writes them into ShieldCortex with novelty filtering and dedupe. |
+| `before_tool_call` | Runs the Action Guard before tools execute. Catastrophic shell/file/network/git actions are blocked; dangerous actions warn by default or request approval when enforcement is enabled. |
 
 The plugin is intentionally fire-and-forget: it should not stall the OpenClaw turn loop if ShieldCortex is unavailable.
 
@@ -82,6 +83,9 @@ Example:
     "entries": {
       "shieldcortex-realtime": {
         "enabled": true,
+        "hooks": {
+          "allowConversationAccess": true
+        },
         "config": {
           "binaryPath": "/usr/local/bin/shieldcortex",
           "openclawAutoMemory": true,

package/dist/index.js

@@ -1,8 +1,10 @@
 /**
  * ShieldCortex Real-time Scanning Plugin for OpenClaw v2026.3.22+
  *
- * Uses explicit capability registration (registerHook + registerCommand)
- * for llm_input/llm_output scanning and optional memory extraction.
+ * Uses typed OpenClaw plugin hooks (`api.on`) for llm_input/llm_output
+ * scanning and before_tool_call interception. `api.registerHook` registers
+ * internal HOOK-style automation and does not participate in the agent-loop
+ * block/approval semantics ShieldCortex needs.
  * All scanning operations are fire-and-forget.
  */
 import { createHash } from "node:crypto";
@@ -640,6 +642,63 @@ function handleLlmOutput(event, ctx) {
         }
     })();
 }
+class TypedApprovalRequest extends Error {
+    request;
+    constructor(message, request) {
+        super(message);
+        this.name = "TypedApprovalRequest";
+        this.request = request;
+    }
+}
+function truncateApprovalText(text, maxLength) {
+    const normalized = text.replace(/\s+/g, " ").trim();
+    if (normalized.length <= maxLength)
+        return normalized;
+    return `${normalized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
+}
+function buildTypedApprovalRequest(message) {
+    const lines = message
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .filter((line) => !/^\[(?:Approve|Deny)\]/i.test(line));
+    const rawTitle = (lines[0] || "ShieldCortex approval required").replace(/^🛡️\s*/u, "");
+    const details = lines.slice(1).join(" | ") || rawTitle;
+    const riskText = message.toLowerCase();
+    const severity = /\b(?:critical|catastrophic|auto[-_\s]?deny|exfil|rm\s+-rf)\b/u.test(riskText)
+        ? "critical"
+        : /\b(?:high|dangerous|sensitive|risk|intercepted)\b/u.test(riskText)
+            ? "warning"
+            : "info";
+    return {
+        title: truncateApprovalText(rawTitle, 80),
+        description: truncateApprovalText(details, 256),
+        severity,
+        timeoutMs: 120_000,
+        timeoutBehavior: "deny",
+        allowedDecisions: ["allow-once", "deny"],
+    };
+}
+async function handleTypedBeforeToolCall(event, interceptor, logger) {
+    try {
+        await interceptor.handleToolCall({
+            toolName: event.toolName,
+            arguments: event.params ?? {},
+            requireApproval: async (message) => {
+                throw new TypedApprovalRequest(message, buildTypedApprovalRequest(message));
+            },
+        });
+    }
+    catch (err) {
+        if (err instanceof TypedApprovalRequest) {
+            return { requireApproval: err.request };
+        }
+        if (err instanceof Error && err.message.startsWith("ShieldCortex:")) {
+            return { block: true, blockReason: err.message };
+        }
+        logger?.warn?.(`[shieldcortex] before_tool_call error (allowing tool call): ${err instanceof Error ? err.message : err}`);
+    }
+}
 // ==================== PLUGIN EXPORT ====================
 export default {
     id: PLUGIN_ID,
@@ -713,44 +772,23 @@ export default {
                     return null;
                 }
             }
-            // Register before_tool_call with lazy-init wrapper
-            api.registerHook('before_tool_call', async (context) => {
+            // Typed before_tool_call hook: this is the OpenClaw agent-loop gate that
+            // can block or require approval before the selected tool executes.
+            api.on('before_tool_call', async (event) => {
                 const interceptor = await initInterceptor();
                 if (!interceptor)
                     return;
-                try {
-                    await interceptor.handleToolCall(context);
-                }
-                catch (err) {
-                    // Intentional blocks from the interceptor (ShieldCortex: ...) should propagate
-                    if (err instanceof Error && err.message.startsWith('ShieldCortex:'))
-                        throw err;
-                    // Unexpected errors (DB crash, etc.) — log and allow the tool call through
-                    api.logger?.warn?.(`[shieldcortex] Interceptor error (allowing tool call): ${err instanceof Error ? err.message : err}`);
-                }
-            }, {
-                name: 'shieldcortex-intercept-tool',
-                description: 'Active threat gating on tool calls',
-            });
+                return handleTypedBeforeToolCall(event, interceptor, api.logger);
+            }, { priority: 80, timeoutMs: 30_000 });
             // Try to register session_end for cache cleanup
             try {
-                api.registerHook('session_end', () => { interceptorReady?.resetSession(); }, {
-                    name: 'shieldcortex-session-cleanup',
-                    description: 'Clear interceptor deny cache on session end',
-                });
+                api.on('session_end', () => { interceptorReady?.resetSession(); });
             }
             catch {
                 // session_end may not be a supported hook — TTL safety net handles this
             }
-            // Explicit capability registration (replaces legacy api.on)
-            api.registerHook("llm_input", handleLlmInput, {
-                name: "shieldcortex-scan-input",
-                description: "Real-time threat scanning on LLM input",
-            });
-            api.registerHook("llm_output", handleLlmOutput, {
-                name: "shieldcortex-scan-output",
-                description: "Memory extraction from LLM output",
-            });
+            api.on("llm_input", handleLlmInput, { timeoutMs: 30_000 });
+            api.on("llm_output", handleLlmOutput, { timeoutMs: 30_000 });
             // Register a lightweight status command so the plugin is not hook-only
             api.registerCommand({
                 name: "shieldcortex-status",

package/dist/interceptor.js

@@ -266,6 +266,10 @@ export function createInterceptor(config, pipeline, options) {
         // Catastrophic / exfil — hard block, always enforced when the guard is enabled.
         if (v.decision === 'block') {
             emitAudit({ ...base, action: 'auto_deny', outcome: 'auto_denied' });
+            // Surface the block to the gateway log (journald). Blocks are recorded in
+            // the ShieldCortex audit jsonl, but were otherwise invisible to an operator
+            // tailing the gateway; a denial — especially a false positive — must be seen.
+            log.warn(`[shieldcortex] action-guard BLOCKED ${context.toolName}: ${v.reason} [${v.signals.join(", ")}]`);
             throw new Error(`ShieldCortex: tool call blocked — ${v.reason}`);
         }
         // require_approval — warn-only by default (never nags), prompt when enforcing.

package/dist/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.43.0",
+  "version": "4.44.0",
   "name": "ShieldCortex Real-time Scanner",
   "description": "Real-time defence scanning on LLM input, memory extraction on LLM output, and active tool call interception with approval gating.",
   "kind": null,

package/index.ts

@@ -1,8 +1,10 @@
 /**
  * ShieldCortex Real-time Scanning Plugin for OpenClaw v2026.3.22+
  *
- * Uses explicit capability registration (registerHook + registerCommand)
- * for llm_input/llm_output scanning and optional memory extraction.
+ * Uses typed OpenClaw plugin hooks (`api.on`) for llm_input/llm_output
+ * scanning and before_tool_call interception. `api.registerHook` registers
+ * internal HOOK-style automation and does not participate in the agent-loop
+ * block/approval semantics ShieldCortex needs.
  * All scanning operations are fire-and-forget.
  */
 
@@ -14,7 +16,7 @@ import { homedir } from "node:os";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { createInterceptor, DEFAULT_CONFIG as DEFAULT_INTERCEPTOR_CONFIG } from './interceptor.js';
-import type { InterceptorConfig, ToolCallContext } from './interceptor.js';
+import type { InterceptorConfig } from './interceptor.js';
 import { syncInterceptEvent } from './intercept-ingest.js';
 import { cloudSync } from './cloud-sync.js';
 
@@ -190,9 +192,26 @@ type AgentCtx = {
   agentId?: string; sessionKey?: string; sessionId?: string;
   workspaceDir?: string; messageProvider?: string;
 };
+type TypedBeforeToolCallEvent = {
+  toolName: string;
+  params?: Record<string, unknown>;
+};
+type TypedBeforeToolCallResult = {
+  block?: boolean;
+  blockReason?: string;
+  requireApproval?: {
+    title: string;
+    description: string;
+    severity?: "info" | "warning" | "critical";
+    timeoutMs?: number;
+    timeoutBehavior?: "allow" | "deny";
+    allowedDecisions?: Array<"allow-once" | "allow-always" | "deny">;
+    onResolution?: (decision: "allow-once" | "allow-always" | "deny" | "timeout" | "cancelled") => Promise<void> | void;
+  };
+};
 type PluginApi = {
   id: string; name: string; logger: { info: (m: string) => void };
-  on: (hook: string, handler: (...args: any[]) => any) => void;
+  on: (hook: string, handler: (...args: any[]) => any, opts?: Record<string, unknown>) => void;
   [k: string]: any;
 };
 
@@ -756,6 +775,73 @@ function handleLlmOutput(event: LlmOutputEvent, ctx: AgentCtx): void {
   })();
 }
 
+class TypedApprovalRequest extends Error {
+  request: NonNullable<TypedBeforeToolCallResult["requireApproval"]>;
+
+  constructor(message: string, request: NonNullable<TypedBeforeToolCallResult["requireApproval"]>) {
+    super(message);
+    this.name = "TypedApprovalRequest";
+    this.request = request;
+  }
+}
+
+function truncateApprovalText(text: string, maxLength: number): string {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  if (normalized.length <= maxLength) return normalized;
+  return `${normalized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
+}
+
+function buildTypedApprovalRequest(message: string): NonNullable<TypedBeforeToolCallResult["requireApproval"]> {
+  const lines = message
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .filter((line) => !/^\[(?:Approve|Deny)\]/i.test(line));
+  const rawTitle = (lines[0] || "ShieldCortex approval required").replace(/^🛡️\s*/u, "");
+  const details = lines.slice(1).join(" | ") || rawTitle;
+  const riskText = message.toLowerCase();
+  const severity = /\b(?:critical|catastrophic|auto[-_\s]?deny|exfil|rm\s+-rf)\b/u.test(riskText)
+    ? "critical"
+    : /\b(?:high|dangerous|sensitive|risk|intercepted)\b/u.test(riskText)
+      ? "warning"
+      : "info";
+
+  return {
+    title: truncateApprovalText(rawTitle, 80),
+    description: truncateApprovalText(details, 256),
+    severity,
+    timeoutMs: 120_000,
+    timeoutBehavior: "deny",
+    allowedDecisions: ["allow-once", "deny"],
+  };
+}
+
+async function handleTypedBeforeToolCall(
+  event: TypedBeforeToolCallEvent,
+  interceptor: ReturnType<typeof createInterceptor>,
+  logger: PluginApi["logger"],
+): Promise<TypedBeforeToolCallResult | void> {
+  try {
+    await interceptor.handleToolCall({
+      toolName: event.toolName,
+      arguments: event.params ?? {},
+      requireApproval: async (message: string) => {
+        throw new TypedApprovalRequest(message, buildTypedApprovalRequest(message));
+      },
+    });
+  } catch (err) {
+    if (err instanceof TypedApprovalRequest) {
+      return { requireApproval: err.request };
+    }
+
+    if (err instanceof Error && err.message.startsWith("ShieldCortex:")) {
+      return { block: true, blockReason: err.message };
+    }
+
+    (logger as any)?.warn?.(`[shieldcortex] before_tool_call error (allowing tool call): ${err instanceof Error ? err.message : err}`);
+  }
+}
+
 // ==================== PLUGIN EXPORT ====================
 
 export default {
@@ -833,42 +919,23 @@ export default {
       }
     }
 
-    // Register before_tool_call with lazy-init wrapper
-    api.registerHook('before_tool_call', async (context: ToolCallContext) => {
+    // Typed before_tool_call hook: this is the OpenClaw agent-loop gate that
+    // can block or require approval before the selected tool executes.
+    api.on('before_tool_call', async (event: TypedBeforeToolCallEvent) => {
       const interceptor = await initInterceptor();
       if (!interceptor) return;
-      try {
-        await interceptor.handleToolCall(context);
-      } catch (err) {
-        // Intentional blocks from the interceptor (ShieldCortex: ...) should propagate
-        if (err instanceof Error && err.message.startsWith('ShieldCortex:')) throw err;
-        // Unexpected errors (DB crash, etc.) — log and allow the tool call through
-        (api.logger as any)?.warn?.(`[shieldcortex] Interceptor error (allowing tool call): ${err instanceof Error ? err.message : err}`);
-      }
-    }, {
-      name: 'shieldcortex-intercept-tool',
-      description: 'Active threat gating on tool calls',
-    });
+      return handleTypedBeforeToolCall(event, interceptor, api.logger);
+    }, { priority: 80, timeoutMs: 30_000 });
 
     // Try to register session_end for cache cleanup
     try {
-      api.registerHook('session_end', () => { interceptorReady?.resetSession(); }, {
-        name: 'shieldcortex-session-cleanup',
-        description: 'Clear interceptor deny cache on session end',
-      });
+      api.on('session_end', () => { interceptorReady?.resetSession(); });
     } catch {
       // session_end may not be a supported hook — TTL safety net handles this
     }
 
-    // Explicit capability registration (replaces legacy api.on)
-    api.registerHook("llm_input", handleLlmInput, {
-      name: "shieldcortex-scan-input",
-      description: "Real-time threat scanning on LLM input",
-    });
-    api.registerHook("llm_output", handleLlmOutput, {
-      name: "shieldcortex-scan-output",
-      description: "Memory extraction from LLM output",
-    });
+    api.on("llm_input", handleLlmInput, { timeoutMs: 30_000 });
+    api.on("llm_output", handleLlmOutput, { timeoutMs: 30_000 });
 
     // Register a lightweight status command so the plugin is not hook-only
     api.registerCommand({

package/interceptor.ts

@@ -414,6 +414,10 @@ export function createInterceptor(
     // Catastrophic / exfil — hard block, always enforced when the guard is enabled.
     if (v.decision === 'block') {
       emitAudit({ ...base, action: 'auto_deny', outcome: 'auto_denied' });
+      // Surface the block to the gateway log (journald). Blocks are recorded in
+      // the ShieldCortex audit jsonl, but were otherwise invisible to an operator
+      // tailing the gateway; a denial — especially a false positive — must be seen.
+      log.warn(`[shieldcortex] action-guard BLOCKED ${context.toolName}: ${v.reason} [${v.signals.join(", ")}]`);
       throw new Error(`ShieldCortex: tool call blocked — ${v.reason}`);
     }
 

package/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.43.0",
+  "version": "4.44.0",
   "name": "ShieldCortex Real-time Scanner",
   "description": "Real-time defence scanning on LLM input, memory extraction on LLM output, and active tool call interception with approval gating.",
   "kind": null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/shieldcortex-realtime",
-  "version": "4.43.0",
+  "version": "4.44.0",
   "description": "OpenClaw plugin for ShieldCortex real-time defence scanning and optional memory extraction.",
   "type": "module",
   "main": "./dist/index.js",