@drakon-systems/shieldcortex-realtime 4.42.4 → 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,
@@ -675,6 +734,7 @@ export default {
                             enabled: rawInterceptorConfig.enabled ?? DEFAULT_INTERCEPTOR_CONFIG.enabled,
                             severityActions: { ...DEFAULT_INTERCEPTOR_CONFIG.severityActions, ...rawInterceptorConfig.severityActions },
                             failurePolicy: { ...DEFAULT_INTERCEPTOR_CONFIG.failurePolicy, ...rawInterceptorConfig.failurePolicy },
+                            actionGuard: { ...(DEFAULT_INTERCEPTOR_CONFIG.actionGuard ?? { enabled: true, enforce: false }), ...(rawInterceptorConfig.actionGuard ?? {}) },
                         } : {}),
                         logger: { info: api.logger?.info ?? console.log, warn: api.logger?.warn ?? console.warn },
                     };
@@ -692,13 +752,19 @@ export default {
                     if (typeof defenceMod.runDefencePipeline !== 'function')
                         return null;
                     interceptorReady = createInterceptor(interceptorConfig, defenceMod.runDefencePipeline, {
+                        evaluateToolCall: typeof defenceMod.evaluateToolCall === 'function'
+                            ? defenceMod.evaluateToolCall
+                            : undefined,
                         onAuditEntry: (entry) => syncInterceptEvent(entry, {
                             cloudApiKey: scConfig.cloudApiKey ?? '',
                             cloudBaseUrl: scConfig.cloudBaseUrl ?? 'https://api.shieldcortex.ai',
                             cloudEnabled: scConfig.cloudEnabled ?? false,
                         }),
                     });
-                    api.logger?.info?.('[shieldcortex] Interceptor active — watching: remember, mcp__memory__remember');
+                    const guardState = interceptorConfig.actionGuard?.enabled
+                        ? (interceptorConfig.actionGuard.enforce ? 'Action Guard: enforce' : 'Action Guard: warn')
+                        : 'Action Guard: off';
+                    api.logger?.info?.(`[shieldcortex] Interceptor active — memory writes + ${guardState} (shell/file/network/git)`);
                     return interceptorReady;
                 }
                 catch (err) {
@@ -706,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

@@ -26,6 +26,12 @@ const DEFAULT_CONFIG = {
         high: 'deny',
         critical: 'deny',
     },
+    // Action Guard on by default: catastrophic ops are blocked out of the box;
+    // dangerous ops are surfaced (warn+audit) but allowed unless `enforce` is set.
+    actionGuard: {
+        enabled: true,
+        enforce: false,
+    },
 };
 export { WATCHED_TOOLS, CONTENT_FIELDS, DEFAULT_CONFIG };
 export function extractContent(toolName, args) {
@@ -133,6 +139,33 @@ export function formatApprovalPrompt(input) {
         '[Approve]  [Deny]',
     ].join('\n');
 }
+/** One-line summary of tool args for audit previews (bounded, no secrets dumped). */
+export function summariseToolArgs(args) {
+    if (!args)
+        return '';
+    const parts = [];
+    for (const [k, val] of Object.entries(args)) {
+        if (typeof val === 'string')
+            parts.push(`${k}=${val.slice(0, 80)}`);
+        else if (typeof val === 'number' || typeof val === 'boolean')
+            parts.push(`${k}=${val}`);
+    }
+    return parts.join(' ').slice(0, 160);
+}
+/** Operator-facing approval prompt for a gated action (not a memory write). */
+export function formatActionGuardPrompt(toolName, v) {
+    return [
+        '🛡️ ShieldCortex — Action Intercepted',
+        '',
+        `Tool:       ${toolName}`,
+        `Action:     ${v.action}`,
+        `Risk:       ${v.severity}`,
+        `Signals:    ${v.signals.join(', ') || 'none'}`,
+        `Reason:     ${v.reason}`,
+        '',
+        '[Approve]  [Deny]',
+    ].join('\n');
+}
 // --- Audit Logging (local JSONL) ---
 const AUDIT_DIR = join(homedir(), '.shieldcortex', 'audit');
 function writeAuditEntry(entry) {
@@ -194,13 +227,96 @@ export function createInterceptor(config, pipeline, options) {
     const rateLimiter = new RateLimiter(options?.maxPromptsPerMinute ?? 5);
     const log = config.logger ?? { info: console.log, warn: console.warn };
     const onAuditEntry = options?.onAuditEntry;
+    const actionGuardCfg = config.actionGuard ?? { enabled: true, enforce: false };
+    const evaluateToolCall = options?.evaluateToolCall;
     function emitAudit(entry) {
         writeAuditEntry(entry);
         onAuditEntry?.(entry);
     }
+    function guardAuditBase(toolName, v, preview) {
+        return {
+            type: 'intercept', tool: toolName,
+            severity: v.severity === 'catastrophic' ? 'critical' : 'high',
+            firewallResult: 'ACTION_GUARD', threats: v.signals,
+            anomalyScore: v.decision === 'block' ? 1 : 0.6,
+            trustScore: 0, sensitivityLevel: 'INTERNAL', fragmentationScore: null, pipelineDurationMs: 0,
+            preview: preview.slice(0, 200), ts: new Date().toISOString(),
+        };
+    }
+    // Action Guard: gates non-memory tool calls (shell / file / network / git).
+    // This is what makes "Iron Dome protects what the agent DOES" true at runtime.
+    async function runActionGuard(context) {
+        if (!actionGuardCfg.enabled || typeof evaluateToolCall !== 'function')
+            return;
+        let v;
+        try {
+            v = evaluateToolCall(context.toolName, context.arguments || {});
+        }
+        catch (err) {
+            // A guard error must never break the agent — log and allow. (The memory
+            // pipeline is the hard-fail path; the action guard is best-effort.)
+            log.warn(`[shieldcortex] ⚠️ action-guard error (allowing ${context.toolName}): ${err instanceof Error ? err.message : err}`);
+            return;
+        }
+        if (v.decision === 'allow')
+            return;
+        const preview = `${context.toolName} :: ${summariseToolArgs(context.arguments)}`;
+        const base = guardAuditBase(context.toolName, v, preview);
+        const severity = v.severity === 'catastrophic' ? 'critical' : 'high';
+        // 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.
+        if (!actionGuardCfg.enforce) {
+            log.warn(`[shieldcortex] ⚠️ Action Guard: ${context.toolName} — ${v.reason}`);
+            emitAudit({ ...base, action: 'warn', outcome: 'warned' });
+            return;
+        }
+        if (typeof context.requireApproval !== 'function') {
+            const failAction = config.failurePolicy[severity];
+            emitAudit({ ...base, action: 'require_approval', outcome: failAction === 'deny' ? 'failure_denied' : 'failure_allowed' });
+            if (failAction === 'deny') {
+                throw new Error(`ShieldCortex: tool call blocked — ${v.reason} (no approver, failure policy: deny)`);
+            }
+            return;
+        }
+        if (!rateLimiter.shouldAllow()) {
+            emitAudit({ ...base, action: 'rate_limit', outcome: 'auto_denied' });
+            throw new Error('ShieldCortex: tool call auto-denied (approval rate limit exceeded)');
+        }
+        let approved;
+        try {
+            approved = await context.requireApproval(formatActionGuardPrompt(context.toolName, v));
+        }
+        catch (err) {
+            const failAction = config.failurePolicy[severity];
+            log.warn(`[shieldcortex] ⚠️ requireApproval error: ${err instanceof Error ? err.message : err} — failure policy: ${failAction}`);
+            emitAudit({ ...base, action: 'require_approval', outcome: failAction === 'deny' ? 'failure_denied' : 'failure_allowed' });
+            if (failAction === 'deny') {
+                throw new Error('ShieldCortex: tool call blocked — approval error, failure policy: deny');
+            }
+            return;
+        }
+        if (approved) {
+            emitAudit({ ...base, action: 'require_approval', outcome: 'approved' });
+            return;
+        }
+        emitAudit({ ...base, action: 'require_approval', outcome: 'denied' });
+        throw new Error('ShieldCortex: tool call denied by user');
+    }
     async function handleToolCall(context) {
-        if (!WATCHED_TOOLS.includes(context.toolName))
+        // Non-memory tools go through the Action Guard (what the agent DOES); the
+        // memory-write tools continue through the content defence pipeline below.
+        if (!WATCHED_TOOLS.includes(context.toolName)) {
+            await runActionGuard(context);
             return;
+        }
         const { title, content } = extractContent(context.toolName, context.arguments);
         const fullContent = [title, content].filter(Boolean).join(' ');
         if (!fullContent.trim())

package/dist/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.42.4",
+  "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 {
@@ -794,6 +880,7 @@ export default {
             enabled: rawInterceptorConfig.enabled ?? DEFAULT_INTERCEPTOR_CONFIG.enabled,
             severityActions: { ...DEFAULT_INTERCEPTOR_CONFIG.severityActions, ...rawInterceptorConfig.severityActions },
             failurePolicy: { ...DEFAULT_INTERCEPTOR_CONFIG.failurePolicy, ...rawInterceptorConfig.failurePolicy },
+            actionGuard: { ...(DEFAULT_INTERCEPTOR_CONFIG.actionGuard ?? { enabled: true, enforce: false }), ...(rawInterceptorConfig.actionGuard ?? {}) },
           } : {}),
           logger: { info: api.logger?.info ?? console.log, warn: (api.logger as any)?.warn ?? console.warn },
         };
@@ -812,13 +899,19 @@ export default {
         if (typeof defenceMod.runDefencePipeline !== 'function') return null;
 
         interceptorReady = createInterceptor(interceptorConfig, defenceMod.runDefencePipeline as Parameters<typeof createInterceptor>[1], {
+          evaluateToolCall: typeof (defenceMod as any).evaluateToolCall === 'function'
+            ? ((defenceMod as any).evaluateToolCall as Parameters<typeof createInterceptor>[2] extends { evaluateToolCall?: infer E } ? E : never)
+            : undefined,
           onAuditEntry: (entry) => syncInterceptEvent(entry, {
             cloudApiKey: (scConfig as any).cloudApiKey ?? '',
             cloudBaseUrl: (scConfig as any).cloudBaseUrl ?? 'https://api.shieldcortex.ai',
             cloudEnabled: (scConfig as any).cloudEnabled ?? false,
           }),
         });
-        api.logger?.info?.('[shieldcortex] Interceptor active — watching: remember, mcp__memory__remember');
+        const guardState = interceptorConfig.actionGuard?.enabled
+          ? (interceptorConfig.actionGuard.enforce ? 'Action Guard: enforce' : 'Action Guard: warn')
+          : 'Action Guard: off';
+        api.logger?.info?.(`[shieldcortex] Interceptor active — memory writes + ${guardState} (shell/file/network/git)`);
         return interceptorReady;
       } catch (err) {
         (api.logger as any)?.warn?.(`[shieldcortex] Interceptor init failed: ${err instanceof Error ? err.message : err}`);
@@ -826,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

@@ -7,10 +7,37 @@ export type Severity = 'low' | 'medium' | 'high' | 'critical';
 export type InterceptAction = 'log' | 'warn' | 'require_approval';
 export type FailureAction = 'allow' | 'deny';
 
+/**
+ * Action Guard config — gates what the agent DOES (shell/file/network/git),
+ * not just what it remembers. Catastrophic operations (rm -rf /, fork bombs,
+ * disk wipes, secret exfil) are always blocked when `enabled`; recognised
+ * dangerous ops require approval when `enforce` is set, otherwise they are
+ * surfaced (warn + audit) but allowed through — so the guard never nags on
+ * routine work by default.
+ */
+export interface ActionGuardConfig {
+  enabled: boolean;
+  enforce: boolean;
+}
+
+/** Structural shape of a Tool Action Guard verdict (kept local to avoid a
+ * compile-time dependency on the main package across the plugin build boundary;
+ * the real `evaluateToolCall` from `shieldcortex/defence` is compatible). */
+export interface ToolGuardVerdictLike {
+  decision: 'allow' | 'require_approval' | 'block';
+  severity: 'benign' | 'sensitive' | 'dangerous' | 'catastrophic' | string;
+  family: string;
+  action: string;
+  reason: string;
+  signals: string[];
+}
+export type ToolGuardEvaluator = (toolName: string, args: Record<string, unknown>) => ToolGuardVerdictLike;
+
 export interface InterceptorConfig {
   enabled: boolean;
   severityActions: Record<Severity, InterceptAction>;
   failurePolicy: Record<Severity, FailureAction>;
+  actionGuard?: ActionGuardConfig;
   logger?: { info: (msg: string) => void; warn: (msg: string) => void };
 }
 
@@ -63,6 +90,12 @@ const DEFAULT_CONFIG: InterceptorConfig = {
     high: 'deny',
     critical: 'deny',
   },
+  // Action Guard on by default: catastrophic ops are blocked out of the box;
+  // dangerous ops are surfaced (warn+audit) but allowed unless `enforce` is set.
+  actionGuard: {
+    enabled: true,
+    enforce: false,
+  },
 };
 
 export { WATCHED_TOOLS, CONTENT_FIELDS, DEFAULT_CONFIG };
@@ -202,6 +235,32 @@ export function formatApprovalPrompt(input: ApprovalPromptInput): string {
   ].join('\n');
 }
 
+/** One-line summary of tool args for audit previews (bounded, no secrets dumped). */
+export function summariseToolArgs(args: Record<string, unknown> | undefined): string {
+  if (!args) return '';
+  const parts: string[] = [];
+  for (const [k, val] of Object.entries(args)) {
+    if (typeof val === 'string') parts.push(`${k}=${val.slice(0, 80)}`);
+    else if (typeof val === 'number' || typeof val === 'boolean') parts.push(`${k}=${val}`);
+  }
+  return parts.join(' ').slice(0, 160);
+}
+
+/** Operator-facing approval prompt for a gated action (not a memory write). */
+export function formatActionGuardPrompt(toolName: string, v: ToolGuardVerdictLike): string {
+  return [
+    '🛡️ ShieldCortex — Action Intercepted',
+    '',
+    `Tool:       ${toolName}`,
+    `Action:     ${v.action}`,
+    `Risk:       ${v.severity}`,
+    `Signals:    ${v.signals.join(', ') || 'none'}`,
+    `Reason:     ${v.reason}`,
+    '',
+    '[Approve]  [Deny]',
+  ].join('\n');
+}
+
 // --- Audit Logging (local JSONL) ---
 
 const AUDIT_DIR = join(homedir(), '.shieldcortex', 'audit');
@@ -297,6 +356,8 @@ type PipelineRunner = (content: string, title: string, source: { type: string; i
 interface InterceptorOptions {
   maxPromptsPerMinute?: number;
   onAuditEntry?: (entry: InterceptAuditEntry) => void;
+  /** Tool Action Guard evaluator, injected from `shieldcortex/defence` at runtime. */
+  evaluateToolCall?: ToolGuardEvaluator;
 }
 
 export function createInterceptor(
@@ -311,14 +372,104 @@ export function createInterceptor(
   const rateLimiter = new RateLimiter(options?.maxPromptsPerMinute ?? 5);
   const log = config.logger ?? { info: console.log, warn: console.warn };
   const onAuditEntry = options?.onAuditEntry;
+  const actionGuardCfg: ActionGuardConfig = config.actionGuard ?? { enabled: true, enforce: false };
+  const evaluateToolCall = options?.evaluateToolCall;
 
   function emitAudit(entry: InterceptAuditEntry): void {
     writeAuditEntry(entry);
     onAuditEntry?.(entry);
   }
 
+  function guardAuditBase(toolName: string, v: ToolGuardVerdictLike, preview: string): Omit<InterceptAuditEntry, 'action' | 'outcome'> {
+    return {
+      type: 'intercept', tool: toolName,
+      severity: v.severity === 'catastrophic' ? 'critical' : 'high',
+      firewallResult: 'ACTION_GUARD', threats: v.signals,
+      anomalyScore: v.decision === 'block' ? 1 : 0.6,
+      trustScore: 0, sensitivityLevel: 'INTERNAL', fragmentationScore: null, pipelineDurationMs: 0,
+      preview: preview.slice(0, 200), ts: new Date().toISOString(),
+    };
+  }
+
+  // Action Guard: gates non-memory tool calls (shell / file / network / git).
+  // This is what makes "Iron Dome protects what the agent DOES" true at runtime.
+  async function runActionGuard(context: ToolCallContext): Promise<void> {
+    if (!actionGuardCfg.enabled || typeof evaluateToolCall !== 'function') return;
+
+    let v: ToolGuardVerdictLike;
+    try {
+      v = evaluateToolCall(context.toolName, context.arguments || {});
+    } catch (err) {
+      // A guard error must never break the agent — log and allow. (The memory
+      // pipeline is the hard-fail path; the action guard is best-effort.)
+      log.warn(`[shieldcortex] ⚠️ action-guard error (allowing ${context.toolName}): ${err instanceof Error ? err.message : err}`);
+      return;
+    }
+    if (v.decision === 'allow') return;
+
+    const preview = `${context.toolName} :: ${summariseToolArgs(context.arguments)}`;
+    const base = guardAuditBase(context.toolName, v, preview);
+    const severity: Severity = v.severity === 'catastrophic' ? 'critical' : 'high';
+
+    // 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.
+    if (!actionGuardCfg.enforce) {
+      log.warn(`[shieldcortex] ⚠️ Action Guard: ${context.toolName} — ${v.reason}`);
+      emitAudit({ ...base, action: 'warn', outcome: 'warned' });
+      return;
+    }
+
+    if (typeof context.requireApproval !== 'function') {
+      const failAction = config.failurePolicy[severity];
+      emitAudit({ ...base, action: 'require_approval', outcome: failAction === 'deny' ? 'failure_denied' : 'failure_allowed' });
+      if (failAction === 'deny') {
+        throw new Error(`ShieldCortex: tool call blocked — ${v.reason} (no approver, failure policy: deny)`);
+      }
+      return;
+    }
+
+    if (!rateLimiter.shouldAllow()) {
+      emitAudit({ ...base, action: 'rate_limit', outcome: 'auto_denied' });
+      throw new Error('ShieldCortex: tool call auto-denied (approval rate limit exceeded)');
+    }
+
+    let approved: boolean;
+    try {
+      approved = await context.requireApproval(formatActionGuardPrompt(context.toolName, v));
+    } catch (err) {
+      const failAction = config.failurePolicy[severity];
+      log.warn(`[shieldcortex] ⚠️ requireApproval error: ${err instanceof Error ? err.message : err} — failure policy: ${failAction}`);
+      emitAudit({ ...base, action: 'require_approval', outcome: failAction === 'deny' ? 'failure_denied' : 'failure_allowed' });
+      if (failAction === 'deny') {
+        throw new Error('ShieldCortex: tool call blocked — approval error, failure policy: deny');
+      }
+      return;
+    }
+
+    if (approved) {
+      emitAudit({ ...base, action: 'require_approval', outcome: 'approved' });
+      return;
+    }
+    emitAudit({ ...base, action: 'require_approval', outcome: 'denied' });
+    throw new Error('ShieldCortex: tool call denied by user');
+  }
+
   async function handleToolCall(context: ToolCallContext): Promise<void> {
-    if (!(WATCHED_TOOLS as readonly string[]).includes(context.toolName)) return;
+    // Non-memory tools go through the Action Guard (what the agent DOES); the
+    // memory-write tools continue through the content defence pipeline below.
+    if (!(WATCHED_TOOLS as readonly string[]).includes(context.toolName)) {
+      await runActionGuard(context);
+      return;
+    }
 
     const { title, content } = extractContent(context.toolName, context.arguments);
     const fullContent = [title, content].filter(Boolean).join(' ');

package/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.42.4",
+  "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.42.4",
+  "version": "4.44.0",
   "description": "OpenClaw plugin for ShieldCortex real-time defence scanning and optional memory extraction.",
   "type": "module",
   "main": "./dist/index.js",