@drakon-systems/shieldcortex-realtime 4.50.0 → 4.51.0

package/README.md

@@ -32,7 +32,8 @@ The defensive root `openclaw.plugin.json` is kept for one release on the main pa
 | `before_agent_run` | **The conversation firewall's enforcement point.** The documented input gate — it is awaited and its result decides whether the run proceeds. Behaviour is set by `interceptor.conversation.posture` (see [Conversation firewall](#conversation-firewall)). |
 | `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 always blocked. Recognised-dangerous actions are **enforced by default**: attended sessions get an approval prompt, unattended sessions fail closed per `failurePolicy`. Set `actionGuard.enforce: false` to opt down to warn-and-allow, or pre-approve specific operations with `actionGuard.autoApprove`. |
-| `session_end` | Resets the interceptor's per-session caches and releases that session's scan-unavailable alert window. Registered even when `interceptor.enabled` is `false`, because the conversation gate keeps per-session state regardless. |
+| `session_end` | Resets the interceptor's per-session caches, releases that session's scan-unavailable alert window, and (with `agent_end`) writes `action_guard_degraded` when the Action Guard denied or warned during the session. Registered even when `interceptor.enabled` is `false`, because the conversation gate keeps per-session state regardless. Neither hook can block, approve, or delay a turn. |
+| `agent_end` | Same degraded-run summariser as `session_end`, idempotent with it. Present on OpenClaw 2026.5.7+; an older host warns-and-returns and `session_end` still summarises. |
 | `/shieldcortex-status` | Slash command reporting the plugin's runtime state. |
 
 The scanning and memory paths are fire-and-forget: they do not stall the OpenClaw turn loop if ShieldCortex is unavailable. The Action Guard is the deliberate exception — it gates tool calls inline, and since 4.47.5 a guard that fails to load falls back to a dependency-free scanner that still denies unambiguous catastrophic operations (fail-closed) rather than allowing everything.

package/dist/index.js

@@ -239,6 +239,24 @@ export function __setDefenceModuleForTest(mod) {
     _defenceModOverride = mod;
     _defenceModPromise = null;
 }
+/** #260 — emit action_guard_degraded for this session. Never throws, never
+ *  waits when the defence module is already injected (the test / in-process
+ *  path). A missing module is a silent no-op: session_end cannot block (#112). */
+function summariseGuardSession(sessionId, origin) {
+    if (!sessionId)
+        return;
+    const run = (mod) => {
+        try {
+            mod?.recordActionGuardDegraded?.(sessionId, { origin });
+        }
+        catch { /* never wedge */ }
+    };
+    if (_defenceModOverride !== undefined) {
+        run(_defenceModOverride);
+        return;
+    }
+    void getDefenceModule().then(run).catch(() => { });
+}
 export function __setRuntimeForTest(runtime) {
     _runtimeOverride = runtime;
     if (runtime)
@@ -1690,8 +1708,23 @@ const MIN_NOVELTY_CHARS = 40;
 async function auditLog(entry) {
     const dir = auditDir();
     try {
+        const hookName = typeof entry.hook === 'string' && entry.hook ? entry.hook : 'llm_input';
+        const plane = hookName === 'before_tool_call' ? 'action_guard' : 'conversation_firewall';
+        let bound = entry;
+        try {
+            const defenceMod = await getDefenceModule();
+            if (typeof defenceMod?.attachEnforcementBinding === 'function') {
+                bound = defenceMod.attachEnforcementBinding(entry, {
+                    plane,
+                    hookName,
+                    pluginId: 'shieldcortex-realtime',
+                    actionKey: typeof entry.actionKey === 'string' ? entry.actionKey : `conversation:${hookName}`,
+                });
+            }
+        }
+        catch { /* older package / bind failure — write the unbound row */ }
         await fs.mkdir(dir, { recursive: true });
-        await fs.appendFile(path.join(dir, `realtime-${new Date().toISOString().slice(0, 10)}.jsonl`), JSON.stringify(entry) + "\n");
+        await fs.appendFile(path.join(dir, `realtime-${new Date().toISOString().slice(0, 10)}.jsonl`), JSON.stringify(bound) + "\n");
         return true;
     }
     catch (err) {
@@ -2910,11 +2943,31 @@ export default {
                         releaseActionLease: typeof defenceMod.releaseToolCallLease === 'function'
                             ? (toolName, args, sessionId) => defenceMod.releaseToolCallLease(toolName, args, { self: sessionId ?? '' })
                             : undefined,
+                        // #260: the session-guard index. Same formula as the Claude Code
+                        // hook. Absent on an older dist — then emitAudit still stamps origin
+                        // but does not write an index nobody would summarise.
+                        sessionGuard: typeof defenceMod.sessionKeyFor === 'function' && typeof defenceMod.appendSessionGuardIndex === 'function'
+                            ? {
+                                keyFor: (sessionId) => defenceMod.sessionKeyFor(sessionId),
+                                index: (entry) => {
+                                    defenceMod.appendSessionGuardIndex({ entry: { ...entry } });
+                                },
+                            }
+                            : undefined,
                         onAuditEntry: (entry) => syncInterceptEvent(entry, {
                             cloudApiKey: scConfig.cloudApiKey ?? '',
                             cloudBaseUrl: scConfig.cloudBaseUrl ?? 'https://api.shieldcortex.ai',
                             cloudEnabled: scConfig.cloudEnabled ?? false,
                         }),
+                        bindAudit: typeof defenceMod.attachEnforcementBinding === 'function'
+                            ? (entry, args) => defenceMod.attachEnforcementBinding(entry, {
+                                plane: 'action_guard',
+                                hookName: 'before_tool_call',
+                                pluginId: 'shieldcortex-realtime',
+                                tool: entry.tool,
+                                args: args ?? {},
+                            })
+                            : undefined,
                     });
                     const guardState = interceptorConfig.actionGuard?.enabled
                         ? (interceptorConfig.actionGuard.enforce ? 'Action Guard: enforce' : 'Action Guard: warn')
@@ -2976,8 +3029,9 @@ export default {
             // `before_tool_call`: a registered approval hook changes how OpenClaw
             // resolves tool-call approvals for unattended Codex agents, so an
             // unattended turn waited 120s on a decision nobody could give. `session_end`
-            // is a notification — it cannot block, approve, or delay anything — and its
-            // handler here only frees local state.
+            // is a notification — it cannot block, approve, or delay anything. It frees
+            // local state and, since #260, best-effort summarises a degraded Action
+            // Guard session. That write is not a decision and cannot stall the host.
             try {
                 api.on('session_end', (event, ctx) => {
                     interceptorReady?.resetSession();
@@ -2991,11 +3045,28 @@ export default {
                     // per-session rule, for the same reason.
                     if (endedSession)
                         sessionTaint.clear(endedSession);
+                    // #260: plane-native summariser. session_end cannot block (#112) —
+                    // this is a notification hook. The write is best-effort and
+                    // idempotent with agent_end below.
+                    summariseGuardSession(endedSession, 'openclaw-session-end');
                 });
             }
             catch {
                 // session_end may not be a supported hook — TTL safety net handles this
             }
+            // #260: agent_end exists on the engine floor (2026.5.7 already declared
+            // it). An unknown typed hook is warn-and-return, not a throw, so we still
+            // wrap registration. Same summariser as session_end — whichever fires
+            // first writes, the other is a no-op. Do not invent a third sink.
+            try {
+                api.on('agent_end', (event, ctx) => {
+                    const endedSession = ctx?.sessionId ?? ctx?.sessionKey ?? event?.sessionId ?? event?.sessionKey ?? null;
+                    summariseGuardSession(endedSession, 'openclaw-session-end');
+                });
+            }
+            catch {
+                // Host predates agent_end — session_end is the load-bearing summariser.
+            }
             // llm_input/llm_output are CONVERSATION hooks: OpenClaw drops them at
             // registration for a non-bundled plugin unless the host grants
             // plugins.entries.<id>.hooks.allowConversationAccess = true. Registration is

package/dist/interceptor.js

@@ -509,6 +509,10 @@ 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;
+    let lastSessionId;
+    const bindAudit = options?.bindAudit;
+    /** Args of the in-flight tool call — used only to mint #224 actionKey. */
+    let lastCallArgs;
     const actionGuardCfg = config.actionGuard ?? { enabled: true, enforce: true, autoApprove: [] };
     const evaluateToolCall = options?.evaluateToolCall;
     const broker = options?.broker;
@@ -519,8 +523,19 @@ export function createInterceptor(config, pipeline, options) {
     /** Bare tool names seen this session, newest last. See buildSessionSummary. */
     const recentTools = [];
     function emitAudit(entry) {
-        writeAuditEntry(entry);
-        onAuditEntry?.(entry);
+        const sessionKey = options?.sessionGuard?.keyFor(lastSessionId) ?? undefined;
+        const withOrigin = {
+            ...entry,
+            origin: 'openclaw-interceptor',
+            ...(sessionKey ? { sessionKey } : {}),
+        };
+        const bound = bindAudit ? bindAudit(withOrigin, lastCallArgs) : withOrigin;
+        writeAuditEntry(bound);
+        try {
+            options?.sessionGuard?.index(bound);
+        }
+        catch { /* never wedge the turn */ }
+        onAuditEntry?.(bound);
     }
     function guardAuditBase(toolName, v, preview) {
         return {
@@ -910,6 +925,8 @@ export function createInterceptor(config, pipeline, options) {
         throw new Error('ShieldCortex: tool call denied by user');
     }
     async function handleToolCall(context) {
+        lastSessionId = context.sessionId;
+        lastCallArgs = context.arguments;
         // Remember the NAME only. This is the entirety of what the approval broker's
         // judge will ever learn about the session — see buildSessionSummary.
         noteToolForSession(context.toolName);

package/dist/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.50.0",
+  "version": "4.51.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,
@@ -18,7 +18,8 @@
       "llm_output",
       "before_agent_run",
       "before_tool_call",
-      "session_end"
+      "session_end",
+      "agent_end"
     ],
     "commands": [
       "shieldcortex-status"

package/index.ts

@@ -100,6 +100,27 @@ type DefenceModule = {
     notification: unknown,
     deps: { channels: NotifyChannelLike[]; timeoutMs?: number },
   ) => Promise<{ deliveredVia: string | null; attempts: Array<{ channel: string; result: { delivered: boolean; reason?: string } }> }>;
+  /** #260 — session-guard index + degraded-run summary. Optional so an older
+   *  installed dist degrades to "no index" rather than crashing the hook. */
+  sessionKeyFor?: (value: string | undefined, opts?: { home?: string; salt?: string }) => string | null;
+  appendSessionGuardIndex?: (opts: { home?: string; entry: Record<string, unknown> }) => boolean;
+  recordActionGuardDegraded?: (
+    rawSessionId: string | undefined,
+    opts?: { home?: string; salt?: string; origin?: string },
+  ) => { recorded: boolean; count: number; sessionKey?: string; existing?: boolean };
+  /** #224 — stamp binding fields on a realtime audit row. Optional so an
+   *  older installed package degrades to unbound records, not a crash. */
+  attachEnforcementBinding?: (
+    entry: Record<string, unknown>,
+    ctx: {
+      plane: 'action_guard' | 'conversation_firewall';
+      hookName: string;
+      pluginId: string;
+      tool?: string;
+      args?: Record<string, unknown>;
+      actionKey?: string;
+    },
+  ) => Record<string, unknown>;
 };
 
 let runtimePromise: Promise<OpenClawRuntime> | null = null;
@@ -322,6 +343,21 @@ export function __setDefenceModuleForTest(mod: DefenceModule | null | undefined)
   _defenceModOverride = mod;
   _defenceModPromise = null;
 }
+
+/** #260 — emit action_guard_degraded for this session. Never throws, never
+ *  waits when the defence module is already injected (the test / in-process
+ *  path). A missing module is a silent no-op: session_end cannot block (#112). */
+function summariseGuardSession(sessionId: string | null, origin: string): void {
+  if (!sessionId) return;
+  const run = (mod: DefenceModule | null) => {
+    try { mod?.recordActionGuardDegraded?.(sessionId, { origin }); } catch { /* never wedge */ }
+  };
+  if (_defenceModOverride !== undefined) {
+    run(_defenceModOverride);
+    return;
+  }
+  void getDefenceModule().then(run).catch(() => {});
+}
 export function __setRuntimeForTest(runtime: OpenClawRuntime | null): void {
   _runtimeOverride = runtime;
   if (runtime) runtimePromise = null;
@@ -2036,10 +2072,24 @@ const MIN_NOVELTY_CHARS = 40;
 async function auditLog(entry: Record<string, unknown>): Promise<boolean> {
   const dir = auditDir();
   try {
+    const hookName = typeof entry.hook === 'string' && entry.hook ? entry.hook : 'llm_input';
+    const plane = hookName === 'before_tool_call' ? 'action_guard' : 'conversation_firewall';
+    let bound = entry;
+    try {
+      const defenceMod = await getDefenceModule();
+      if (typeof defenceMod?.attachEnforcementBinding === 'function') {
+        bound = defenceMod.attachEnforcementBinding(entry, {
+          plane,
+          hookName,
+          pluginId: 'shieldcortex-realtime',
+          actionKey: typeof entry.actionKey === 'string' ? entry.actionKey : `conversation:${hookName}`,
+        });
+      }
+    } catch { /* older package / bind failure — write the unbound row */ }
     await fs.mkdir(dir, { recursive: true });
     await fs.appendFile(
       path.join(dir, `realtime-${new Date().toISOString().slice(0, 10)}.jsonl`),
-      JSON.stringify(entry) + "\n",
+      JSON.stringify(bound) + "\n",
     );
     return true;
   } catch (err) {
@@ -3443,11 +3493,31 @@ export default {
             ? (toolName, args, sessionId) =>
                 (defenceMod as any).releaseToolCallLease(toolName, args, { self: sessionId ?? '' })
             : undefined,
+          // #260: the session-guard index. Same formula as the Claude Code
+          // hook. Absent on an older dist — then emitAudit still stamps origin
+          // but does not write an index nobody would summarise.
+          sessionGuard: typeof defenceMod.sessionKeyFor === 'function' && typeof defenceMod.appendSessionGuardIndex === 'function'
+            ? {
+                keyFor: (sessionId) => defenceMod.sessionKeyFor!(sessionId),
+                index: (entry) => {
+                  defenceMod.appendSessionGuardIndex!({ entry: { ...entry } as Record<string, unknown> });
+                },
+              }
+            : 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,
           }),
+          bindAudit: typeof (defenceMod as any).attachEnforcementBinding === 'function'
+            ? (entry, args) => (defenceMod as any).attachEnforcementBinding(entry, {
+                plane: 'action_guard',
+                hookName: 'before_tool_call',
+                pluginId: 'shieldcortex-realtime',
+                tool: entry.tool,
+                args: args ?? {},
+              }) as typeof entry
+            : undefined,
         });
         const guardState = interceptorConfig.actionGuard?.enabled
           ? (interceptorConfig.actionGuard.enforce ? 'Action Guard: enforce' : 'Action Guard: warn')
@@ -3509,8 +3579,9 @@ export default {
     // `before_tool_call`: a registered approval hook changes how OpenClaw
     // resolves tool-call approvals for unattended Codex agents, so an
     // unattended turn waited 120s on a decision nobody could give. `session_end`
-    // is a notification — it cannot block, approve, or delay anything — and its
-    // handler here only frees local state.
+    // is a notification — it cannot block, approve, or delay anything. It frees
+    // local state and, since #260, best-effort summarises a degraded Action
+    // Guard session. That write is not a decision and cannot stall the host.
     try {
       api.on('session_end', (event?: { sessionId?: string; sessionKey?: string }, ctx?: AgentCtx) => {
         interceptorReady?.resetSession();
@@ -3523,11 +3594,28 @@ export default {
         // #233: a taint must not outlive the conversation that earned it. Same
         // per-session rule, for the same reason.
         if (endedSession) sessionTaint.clear(endedSession);
+        // #260: plane-native summariser. session_end cannot block (#112) —
+        // this is a notification hook. The write is best-effort and
+        // idempotent with agent_end below.
+        summariseGuardSession(endedSession, 'openclaw-session-end');
       });
     } catch {
       // session_end may not be a supported hook — TTL safety net handles this
     }
 
+    // #260: agent_end exists on the engine floor (2026.5.7 already declared
+    // it). An unknown typed hook is warn-and-return, not a throw, so we still
+    // wrap registration. Same summariser as session_end — whichever fires
+    // first writes, the other is a no-op. Do not invent a third sink.
+    try {
+      api.on('agent_end', (event?: { sessionId?: string; sessionKey?: string }, ctx?: AgentCtx) => {
+        const endedSession = ctx?.sessionId ?? ctx?.sessionKey ?? event?.sessionId ?? event?.sessionKey ?? null;
+        summariseGuardSession(endedSession, 'openclaw-session-end');
+      });
+    } catch {
+      // Host predates agent_end — session_end is the load-bearing summariser.
+    }
+
     // llm_input/llm_output are CONVERSATION hooks: OpenClaw drops them at
     // registration for a non-bundled plugin unless the host grants
     // plugins.entries.<id>.hooks.allowConversationAccess = true. Registration is

package/interceptor.ts

@@ -202,6 +202,17 @@ export interface InterceptAuditEntry {
   escalated?: { by: 'session-taint'; from: string; to: string; reason: string };
   /** Files the reviewed-script allowlist exempted from folding (#189). */
   reviewedScripts?: string[];
+  /** #260 — plane origin so the session-guard summariser can find this row. */
+  origin?: 'openclaw-interceptor';
+  sessionKey?: string;
+  /** #224 — binding fields. Present once the host injects `bindAudit`. */
+  plane?: 'action_guard' | 'conversation_firewall';
+  gatewayInstanceId?: string;
+  hookName?: string;
+  pluginId?: string;
+  nonce?: string;
+  seq?: number;
+  actionKey?: string;
 }
 
 const WATCHED_TOOLS = ['remember', 'mcp__memory__remember'] as const;
@@ -798,6 +809,15 @@ interface InterceptorOptions {
    *  limit, so a looping or compromised agent must not be able to spend it
    *  without bound. Exhausting it yields no judge, which yields a hold. */
   maxJudgeCallsPerMinute?: number;
+  /** #260 — session-guard index. Injected from `shieldcortex/defence`. */
+  sessionGuard?: {
+    keyFor: (sessionId: string | undefined) => string | null;
+    index: (entry: InterceptAuditEntry) => void;
+  };
+  /** #224 — stamp plane/instance/hook/nonce/seq/actionKey before the row hits
+   *  disk. Injected from `shieldcortex/defence` at runtime so this plugin does
+   *  not grow a second schema. Absent = unbound (older installed package). */
+  bindAudit?: (entry: InterceptAuditEntry, args?: Record<string, unknown>) => InterceptAuditEntry;
 }
 
 /** How many recent tool NAMES the judge is told about. Names only, never
@@ -820,6 +840,10 @@ export function createInterceptor(
   const rateLimiter = new RateLimiter(options?.maxPromptsPerMinute ?? 5);
   const log = config.logger ?? { info: console.log, warn: console.warn };
   const onAuditEntry = options?.onAuditEntry;
+  let lastSessionId: string | undefined;
+  const bindAudit = options?.bindAudit;
+  /** Args of the in-flight tool call — used only to mint #224 actionKey. */
+  let lastCallArgs: Record<string, unknown> | undefined;
   const actionGuardCfg: ActionGuardConfig = config.actionGuard ?? { enabled: true, enforce: true, autoApprove: [] };
   const evaluateToolCall = options?.evaluateToolCall;
   const broker = options?.broker;
@@ -831,8 +855,16 @@ export function createInterceptor(
   const recentTools: string[] = [];
 
   function emitAudit(entry: InterceptAuditEntry): void {
-    writeAuditEntry(entry);
-    onAuditEntry?.(entry);
+    const sessionKey = options?.sessionGuard?.keyFor(lastSessionId) ?? undefined;
+    const withOrigin: InterceptAuditEntry = {
+      ...entry,
+      origin: 'openclaw-interceptor',
+      ...(sessionKey ? { sessionKey } : {}),
+    };
+    const bound = bindAudit ? bindAudit(withOrigin, lastCallArgs) : withOrigin;
+    writeAuditEntry(bound);
+    try { options?.sessionGuard?.index(bound); } catch { /* never wedge the turn */ }
+    onAuditEntry?.(bound);
   }
 
   function guardAuditBase(toolName: string, v: ToolGuardVerdictLike, preview: string): Omit<InterceptAuditEntry, 'action' | 'outcome'> {
@@ -1249,6 +1281,8 @@ export function createInterceptor(
   }
 
   async function handleToolCall(context: ToolCallContext): Promise<void> {
+    lastSessionId = context.sessionId;
+    lastCallArgs = context.arguments;
     // Remember the NAME only. This is the entirety of what the approval broker's
     // judge will ever learn about the session — see buildSessionSummary.
     noteToolForSession(context.toolName);

package/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.50.0",
+  "version": "4.51.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,
@@ -18,7 +18,8 @@
       "llm_output",
       "before_agent_run",
       "before_tool_call",
-      "session_end"
+      "session_end",
+      "agent_end"
     ],
     "commands": [
       "shieldcortex-status"

package/package.json

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