@drakon-systems/shieldcortex-realtime 4.49.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) {
@@ -2900,11 +2933,41 @@ export default {
                             const rec = sessionId ? sessionTaint.get(sessionId) : null;
                             return rec ? { reason: rec.reason } : null;
                         },
+                        // #227: session action lease — the fs-backed shared implementation,
+                        // injected through the same runtime seam as evaluateToolCall. Older
+                        // installed packages without the export simply leave the option
+                        // undefined (no lease plane — the capability-honesty surface says so).
+                        checkActionLease: typeof defenceMod.evaluateToolCallLease === 'function'
+                            ? (toolName, args, sessionId) => defenceMod.evaluateToolCallLease(toolName, args, { self: sessionId ?? '' })
+                            : undefined,
+                        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')
@@ -2966,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();
@@ -2981,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

@@ -203,6 +203,8 @@ const FALLBACK_DANGEROUS_PATTERNS = [
     { re: /\/etc\/(passwd|shadow|sudoers)|~\/\.ssh|id_rsa|\.aws\/credentials|\.env\b/i, signal: 'touch-sensitive-path' },
     // Guard's own approval store (#118): agent-side writes here mint approvals.
     { re: /\.shieldcortex[\\/]+approvals\b/i, signal: 'touch-approval-store' },
+    // Session-lease ledger + store (#227): a freeze an agent can edit is not a freeze.
+    { re: /\.shieldcortex[\\/]+(?:DECISIONS\.md|leases)\b/i, signal: 'touch-decisions-ledger' },
     { re: /(?:^|[;&|(\n]|\$\()\s*(?:\w+=\S*\s+)*(?:sudo\s+)?uvx\b/i, signal: 'registry-code-exec' },
     { re: /(?:^|[;&|(\n]|\$\()\s*(?:\w+=\S*\s+)*(?:sudo\s+)?(?:pnpm|yarn)\b[^|;&\n]*\bdlx\b/i, signal: 'registry-code-exec' },
     { re: /\b(?:base64|openssl|xxd|cat|http)\b[^\n|]*\|(?:[^\n|]*\|)*\s*(?:\w+=\S*\s+)*(?:sudo\s+)?(?:bash|sh|zsh|ksh|python\d?|perl|ruby|node)\b(?:\s+-)?\s*(?:[;&|\n]|$)/i, signal: 'decode-pipe-to-shell' },
@@ -507,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;
@@ -517,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 {
@@ -680,6 +697,34 @@ export function createInterceptor(config, pipeline, options) {
     async function runActionGuard(context) {
         if (!actionGuardCfg.enabled)
             return;
+        // Session action lease (#227) — EARLY, before the guard evaluator (which may
+        // be unwired or throw). A freeze is a HARD control and must bind regardless
+        // of the guard's own state; running it only after a successful evaluation
+        // would let a frozen action through the guard-unavailable path. Unscoped
+        // calls return null and cost nothing; a THROW is treated as no-lease (a
+        // broken lease layer must not deny everything); state unreadability fails
+        // closed to 'unknown' inside the store.
+        let leaseGate = null;
+        try {
+            leaseGate = options?.checkActionLease?.(context.toolName, context.arguments || {}, context.sessionId) ?? null;
+            if (leaseGate?.ledgerChanged) {
+                log.warn(`[shieldcortex] DECISIONS.md changed since last read (${leaseGate.ledgerChanged.fromHash.slice(0, 12)} → ${leaseGate.ledgerChanged.toHash.slice(0, 12)}) — tamper evidence, review the ledger`);
+            }
+            if (leaseGate && leaseGate.decision.verdict !== 'allow') {
+                emitAudit({
+                    ...guardAuditBase(context.toolName, { decision: 'block', severity: 'high', family: 'exec', action: `session-lease:${leaseGate.scope}`, reason: leaseGate.decision.reason, signals: ['session-lease', leaseGate.decision.verdict] }, `${context.toolName} :: ${summariseToolArgs(context.arguments)}`),
+                    action: 'auto_deny', outcome: 'auto_denied',
+                });
+                log.warn(`[shieldcortex] action-guard SESSION-LEASE refused ${context.toolName} [${leaseGate.scope}/${leaseGate.decision.verdict}]: ${leaseGate.decision.reason}`);
+                throw new Error(`ShieldCortex: tool call blocked — ${leaseGate.decision.reason}`);
+            }
+        }
+        catch (err) {
+            // A ShieldCortex refusal must propagate; a lease-layer malfunction must not.
+            if (err instanceof Error && err.message.startsWith('ShieldCortex:'))
+                throw err;
+            leaseGate = null;
+        }
         if (typeof evaluateToolCall !== 'function') {
             handleGuardUnavailable(context, 'evaluateToolCall not wired');
             return;
@@ -757,6 +802,14 @@ export function createInterceptor(config, pipeline, options) {
         const severity = v.severity === 'catastrophic' ? 'critical' : 'high';
         // Catastrophic / exfil — hard block, always enforced when the guard is enabled.
         if (v.decision === 'block') {
+            // #227: release any lease this call minted early — a blocked action must
+            // not leave a hold on that scope (self-heals at TTL if release fails).
+            if (leaseGate?.acquired) {
+                try {
+                    options?.releaseActionLease?.(context.toolName, context.arguments || {}, context.sessionId);
+                }
+                catch { /* self-heals */ }
+            }
             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
@@ -872,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.49.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) {
@@ -3431,11 +3481,43 @@ export default {
             const rec = sessionId ? sessionTaint.get(sessionId) : null;
             return rec ? { reason: rec.reason } : null;
           },
+          // #227: session action lease — the fs-backed shared implementation,
+          // injected through the same runtime seam as evaluateToolCall. Older
+          // installed packages without the export simply leave the option
+          // undefined (no lease plane — the capability-honesty surface says so).
+          checkActionLease: typeof (defenceMod as any).evaluateToolCallLease === 'function'
+            ? (toolName, args, sessionId) =>
+                (defenceMod as any).evaluateToolCallLease(toolName, args, { self: sessionId ?? '' })
+            : undefined,
+          releaseActionLease: typeof (defenceMod as any).releaseToolCallLease === 'function'
+            ? (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')
@@ -3497,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();
@@ -3511,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;
@@ -438,6 +449,8 @@ const FALLBACK_DANGEROUS_PATTERNS: Array<{ re: RegExp; signal: string }> = [
   { re: /\/etc\/(passwd|shadow|sudoers)|~\/\.ssh|id_rsa|\.aws\/credentials|\.env\b/i, signal: 'touch-sensitive-path' },
   // Guard's own approval store (#118): agent-side writes here mint approvals.
   { re: /\.shieldcortex[\\/]+approvals\b/i, signal: 'touch-approval-store' },
+  // Session-lease ledger + store (#227): a freeze an agent can edit is not a freeze.
+  { re: /\.shieldcortex[\\/]+(?:DECISIONS\.md|leases)\b/i, signal: 'touch-decisions-ledger' },
   { re: /(?:^|[;&|(\n]|\$\()\s*(?:\w+=\S*\s+)*(?:sudo\s+)?uvx\b/i, signal: 'registry-code-exec' },
   { re: /(?:^|[;&|(\n]|\$\()\s*(?:\w+=\S*\s+)*(?:sudo\s+)?(?:pnpm|yarn)\b[^|;&\n]*\bdlx\b/i, signal: 'registry-code-exec' },
   { re: /\b(?:base64|openssl|xxd|cat|http)\b[^\n|]*\|(?:[^\n|]*\|)*\s*(?:\w+=\S*\s+)*(?:sudo\s+)?(?:bash|sh|zsh|ksh|python\d?|perl|ruby|node)\b(?:\s+-)?\s*(?:[;&|\n]|$)/i, signal: 'decode-pipe-to-shell' },
@@ -770,6 +783,24 @@ interface InterceptorOptions {
    *  (or throwing) means no escalation — a broken scanner must never become a
    *  new source of denials. */
   sessionTaint?: (sessionId: string | undefined) => { reason: string } | null;
+  /** #227: session action lease — injected from `shieldcortex/defence` at
+   *  runtime (evaluateToolCallLease). Null for unscoped calls (the common
+   *  case); a non-allow decision for a scoped call is a refusal that must
+   *  precede every approval affordance. A THROW is treated as no-lease; state
+   *  unreadability fails closed INSIDE the implementation. */
+  checkActionLease?: (
+    toolName: string,
+    args: Record<string, unknown>,
+    sessionId: string | undefined,
+  ) => {
+    scope: string;
+    decision: { verdict: string; reason: string };
+    acquired?: boolean;
+    ledgerChanged?: { fromHash: string; toHash: string };
+  } | null;
+  /** #227: release a lease this call minted early, when the guard then blocks
+   *  the action. Best-effort; a hold self-heals at its TTL if this is absent. */
+  releaseActionLease?: (toolName: string, args: Record<string, unknown>, sessionId: string | undefined) => void;
   /** Approval broker (#143), injected from `shieldcortex/defence` at runtime.
    *  Absent, or present with `config.enabled: false`, means no model is ever
    *  consulted and the guard behaves exactly as it did before #143. */
@@ -778,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
@@ -800,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;
@@ -811,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'> {
@@ -983,6 +1035,38 @@ export function createInterceptor(
   async function runActionGuard(context: ToolCallContext): Promise<void> {
     if (!actionGuardCfg.enabled) return;
 
+    // Session action lease (#227) — EARLY, before the guard evaluator (which may
+    // be unwired or throw). A freeze is a HARD control and must bind regardless
+    // of the guard's own state; running it only after a successful evaluation
+    // would let a frozen action through the guard-unavailable path. Unscoped
+    // calls return null and cost nothing; a THROW is treated as no-lease (a
+    // broken lease layer must not deny everything); state unreadability fails
+    // closed to 'unknown' inside the store.
+    let leaseGate: {
+      scope: string; decision: { verdict: string; reason: string };
+      acquired?: boolean; ledgerChanged?: { fromHash: string; toHash: string };
+    } | null = null;
+    try {
+      leaseGate = options?.checkActionLease?.(context.toolName, context.arguments || {}, context.sessionId) ?? null;
+      if (leaseGate?.ledgerChanged) {
+        log.warn(
+          `[shieldcortex] DECISIONS.md changed since last read (${leaseGate.ledgerChanged.fromHash.slice(0, 12)} → ${leaseGate.ledgerChanged.toHash.slice(0, 12)}) — tamper evidence, review the ledger`,
+        );
+      }
+      if (leaseGate && leaseGate.decision.verdict !== 'allow') {
+        emitAudit({
+          ...guardAuditBase(context.toolName, { decision: 'block', severity: 'high', family: 'exec', action: `session-lease:${leaseGate.scope}`, reason: leaseGate.decision.reason, signals: ['session-lease', leaseGate.decision.verdict] } as ToolGuardVerdictLike, `${context.toolName} :: ${summariseToolArgs(context.arguments)}`),
+          action: 'auto_deny', outcome: 'auto_denied',
+        });
+        log.warn(`[shieldcortex] action-guard SESSION-LEASE refused ${context.toolName} [${leaseGate.scope}/${leaseGate.decision.verdict}]: ${leaseGate.decision.reason}`);
+        throw new Error(`ShieldCortex: tool call blocked — ${leaseGate.decision.reason}`);
+      }
+    } catch (err) {
+      // A ShieldCortex refusal must propagate; a lease-layer malfunction must not.
+      if (err instanceof Error && err.message.startsWith('ShieldCortex:')) throw err;
+      leaseGate = null;
+    }
+
     if (typeof evaluateToolCall !== 'function') {
       handleGuardUnavailable(context, 'evaluateToolCall not wired');
       return;
@@ -1065,6 +1149,11 @@ export function createInterceptor(
 
     // Catastrophic / exfil — hard block, always enforced when the guard is enabled.
     if (v.decision === 'block') {
+      // #227: release any lease this call minted early — a blocked action must
+      // not leave a hold on that scope (self-heals at TTL if release fails).
+      if (leaseGate?.acquired) {
+        try { options?.releaseActionLease?.(context.toolName, context.arguments || {}, context.sessionId); } catch { /* self-heals */ }
+      }
       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
@@ -1192,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.49.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.49.0",
+  "version": "4.51.0",
   "description": "OpenClaw plugin for ShieldCortex real-time defence scanning and optional memory extraction.",
   "type": "module",
   "main": "./dist/index.js",