@drakon-systems/shieldcortex-realtime 4.54.7 → 4.54.9

package/dist/index.js

@@ -2764,6 +2764,12 @@ function handleLlmOutput(event, ctx) {
 }
 class TypedApprovalRequest extends Error {
     request;
+    /** #372 — one-shot audit writer the interceptor hangs on this error at hold
+     *  time, carrying the guard's audit base and the session the hold belongs to.
+     *  Both mint sites attach it (action-guard and memory-write pipelines).
+     *  Absent only for an older installed interceptor: then no `onResolution`
+     *  is wired at all and the card behaves exactly as it did before #372. */
+    decisionAudit;
     constructor(message, request) {
         super(message);
         this.name = "TypedApprovalRequest";
@@ -2776,6 +2782,18 @@ function truncateApprovalText(text, maxLength) {
         return normalized;
     return `${normalized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
 }
+/** A held command can itself contain the credential that tripped the guard, and
+ *  an approval card is a chat surface. Same rule, same phrasing and same
+ *  trade as the Telegram card path (isSecretEgress / buildCardFields in
+ *  src/defence/iron-dome/openclaw-approval-channel.ts): the operator keeps the
+ *  tool, the signals and the severity, and loses exactly the text that must not
+ *  be forwarded. */
+const SECRET_EGRESS_PROMPT = /secret|credential/iu;
+const WITHHELD_COMMAND_TEXT = "(command withheld — contains credential material)";
+/** Prompt lines safe to forward on a secret-egress hold — label-only metadata.
+ *  `Reason:` (action guard) and `Content:` (memory write) are the two lines
+ *  that quote the payload, so anything not on this list is dropped. */
+const SAFE_APPROVAL_LINE = /^(?:Tool|Action|Risk|Signals|Threats):/iu;
 function buildTypedApprovalRequest(message) {
     const lines = message
         .split(/\r?\n/u)
@@ -2783,7 +2801,11 @@ function buildTypedApprovalRequest(message) {
         .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 detailLines = lines.slice(1);
+    const withholdPayload = SECRET_EGRESS_PROMPT.test(message);
+    const details = (withholdPayload
+        ? [WITHHELD_COMMAND_TEXT, ...detailLines.filter((line) => SAFE_APPROVAL_LINE.test(line))]
+        : detailLines).join(" | ") || rawTitle;
     const riskText = message.toLowerCase();
     const severity = /\b(?:critical|catastrophic|auto[-_\s]?deny|exfil|rm\s+-rf)\b/u.test(riskText)
         ? "critical"
@@ -2794,24 +2816,82 @@ function buildTypedApprovalRequest(message) {
         title: truncateApprovalText(rawTitle, 80),
         description: truncateApprovalText(details, 256),
         severity,
-        timeoutMs: 120_000,
+        // The host's own ceiling (MAX_PLUGIN_APPROVAL_TIMEOUT_MS), matching
+        // CARD_TIMEOUT_MS on the Telegram card path. 120s was the old bridge's
+        // number and it expired cards the operator was still walking back to.
+        timeoutMs: 600_000,
         timeoutBehavior: "deny",
         allowedDecisions: ["allow-once", "deny"],
     };
 }
-async function handleTypedBeforeToolCall(event, interceptor, logger, sessionId) {
+export const __buildTypedApprovalRequestForTest = buildTypedApprovalRequest;
+/** #372 — the operator's answer, as the audit stream records it.
+ *
+ * `allow-always` is defensive: today's card only offers allow-once/deny (see
+ * `allowedDecisions`), but a host that grows the button must not be able to
+ * produce an approval nobody can find afterwards. It maps to `approved_once`
+ * rather than a sticky outcome because ShieldCortex grants nothing durable
+ * here — the next call is gated again. */
+/** The decision label as it may appear in a gateway log line. Host-supplied,
+ *  so it is reduced to an identifier shape first — a log line is not a place to
+ *  render whatever a caller passed. */
+function safeDecisionLabel(decision) {
+    return String(decision).replace(/[^A-Za-z0-9_.:-]/gu, "?").slice(0, 32) || "unknown";
+}
+const CARD_DECISION_OUTCOME = {
+    "allow-once": "approved_once",
+    "allow-always": "approved_once",
+    deny: "card_denied",
+    timeout: "card_timeout",
+    cancelled: "card_cancelled",
+};
+async function handleTypedBeforeToolCall(event, interceptor, logger, ctx) {
+    const sessionId = resolveHookSessionId(event, ctx);
+    // #310: a card is only worth minting when a human is there to tap it. Cron
+    // and heartbeat runs are host-keyed automation with no operator attached, so
+    // offering OpenClaw an approval request there recreates #112 exactly — the
+    // turn waits out the timeout on a decision nobody can give. Withholding
+    // `requireApproval` puts the interceptor on its unattended branch instead,
+    // which denies on the failure policy immediately and loudly.
+    const attended = !isTrustedAutomationSession(sessionId);
     try {
         await interceptor.handleToolCall({
             toolName: event.toolName,
             arguments: event.params ?? {},
             sessionId,
-            requireApproval: async (message) => {
-                throw new TypedApprovalRequest(message, buildTypedApprovalRequest(message));
-            },
+            ...(attended
+                ? {
+                    requireApproval: async (message) => {
+                        throw new TypedApprovalRequest(message, buildTypedApprovalRequest(message));
+                    },
+                }
+                : {}),
         });
     }
     catch (err) {
         if (err instanceof TypedApprovalRequest) {
+            const decisionAudit = err.decisionAudit;
+            if (decisionAudit) {
+                // #372: the hold writes no row because no decision exists yet — THIS is
+                // where the operator's answer becomes one. The host owns this callback
+                // and awaits it, so it must never see a throw: a broken audit sink is
+                // not a reason to disturb a decision the operator already made.
+                err.request.onResolution = (decision) => {
+                    try {
+                        const outcome = Object.hasOwn(CARD_DECISION_OUTCOME, decision) ? CARD_DECISION_OUTCOME[decision] : undefined;
+                        if (!outcome) {
+                            // A decision this build does not know. Say so loudly rather than
+                            // guess — inventing an outcome would forge the operator's answer.
+                            logger?.warn?.(`[shieldcortex] unrecognised approval decision '${safeDecisionLabel(decision)}' — no audit row written`);
+                            return;
+                        }
+                        decisionAudit(outcome);
+                    }
+                    catch (auditErr) {
+                        logger?.warn?.(`[shieldcortex] approval decision audit failed (${safeDecisionLabel(decision)}): ${auditErr instanceof Error ? auditErr.message : auditErr}`);
+                    }
+                };
+            }
             return { requireApproval: err.request };
         }
         if (err instanceof Error && err.message.startsWith("ShieldCortex:")) {
@@ -3100,7 +3180,10 @@ export default {
                     // #233: the host supplies the session on the tool CONTEXT, not the
                     // event. Without it a taint cannot be matched to the call it should
                     // gate, so the escalation would silently never fire.
-                    return handleTypedBeforeToolCall(event, interceptor, api.logger, ctx?.sessionId);
+                    // #310: the WHOLE context, not just `sessionId` — resolveHookSessionId
+                    // also reads `sessionKey`, which is where a cron/heartbeat run's key
+                    // actually arrives, and that key decides whether a card is minted.
+                    return handleTypedBeforeToolCall(event, interceptor, api.logger, ctx);
                 }, { priority: 80, timeoutMs: 30_000 });
                 _beforeToolCallRegistered = true;
                 // NOTE: session_end is NOT registered here — it moved out of this guard

package/dist/interceptor.js

@@ -4,6 +4,11 @@ import { join, isAbsolute, resolve as resolvePath } from 'node:path';
 import { homedir } from 'node:os';
 import { createGatewayInvoker } from './broker-invoker.js';
 import { escalateForTaint } from './session-taint.js';
+/** #372 — the runtime mirror of ApprovalDecisionOutcome: the closure crosses a
+ *  plugin boundary, so the union is enforced with a Set, not just the compiler. */
+const CARD_AUDIT_OUTCOMES = new Set([
+    'approved_once', 'card_denied', 'card_timeout', 'card_cancelled',
+]);
 const WATCHED_TOOLS = ['remember', 'mcp__memory__remember'];
 const CONTENT_FIELDS = {
     remember: ['content', 'title'],
@@ -274,6 +279,22 @@ export function formatActionGuardPrompt(toolName, v) {
         '[Approve]  [Deny]',
     ].join('\n');
 }
+/**
+ * #310: the OpenClaw-native approval card is delivered by THROWING out of the
+ * injected `requireApproval` — the plugin's typed-hook bridge catches that
+ * throw and hands `{ requireApproval }` back to the host, which draws the card.
+ * So this particular rejection is control flow, not a failure, and the catch
+ * blocks below must let it pass straight through.
+ *
+ * Matched by NAME, not by class: the class lives in the plugin entrypoint
+ * (index.ts) and this file is deliberately free of a compile-time dependency on
+ * it, the same discipline as ToolGuardVerdictLike. Swallowing it as an approval
+ * error is exactly what turned every native card into a `failure_denied` the
+ * operator never saw.
+ */
+function isTypedApprovalRequest(err) {
+    return err instanceof Error && err.name === 'TypedApprovalRequest';
+}
 // --- Audit Logging (local JSONL) ---
 /** Resolve per write so isolated tests can redirect every realtime audit path.
  * The conversation hook already honours this variable; the interceptor did not,
@@ -522,14 +543,16 @@ export function createInterceptor(config, pipeline, options) {
     const judgeLimiter = new RateLimiter(options?.maxJudgeCallsPerMinute ?? 20);
     /** Bare tool names seen this session, newest last. See buildSessionSummary. */
     const recentTools = [];
-    function emitAudit(entry) {
-        const sessionKey = options?.sessionGuard?.keyFor(lastSessionId) ?? undefined;
+    /** The one write path every intercept row takes. `captured` is normally the
+     *  in-flight call (emitAudit below); #372 hands it a hold-time snapshot so a
+     *  decision that arrives after the turn moved on still lands on ITS call. */
+    function emitAuditWith(entry, captured) {
         const withOrigin = {
             ...entry,
             origin: 'openclaw-interceptor',
-            ...(sessionKey ? { sessionKey } : {}),
+            ...(captured.sessionKey ? { sessionKey: captured.sessionKey } : {}),
         };
-        const bound = bindAudit ? bindAudit(withOrigin, lastCallArgs) : withOrigin;
+        const bound = bindAudit ? bindAudit(withOrigin, captured.args) : withOrigin;
         writeAuditEntry(bound);
         try {
             options?.sessionGuard?.index(bound);
@@ -537,6 +560,62 @@ export function createInterceptor(config, pipeline, options) {
         catch { /* never wedge the turn */ }
         onAuditEntry?.(bound);
     }
+    function emitAudit(entry) {
+        emitAuditWith(entry, {
+            sessionKey: options?.sessionGuard?.keyFor(lastSessionId) ?? undefined,
+            args: lastCallArgs,
+        });
+    }
+    /**
+     * #372 — hang a one-shot decision writer on a minted approval card.
+     *
+     * The hold itself is still unaudited by design: no decision exists yet. What
+     * was missing is the other end — the host reports the operator's answer on
+     * the request's `onResolution`, and nothing on that path knew what the guard
+     * saw, so an operator-APPROVED dangerous action left no intercept row at all
+     * (invisible to the #260 session summaries).
+     *
+     * Everything the row needs is captured HERE: the guard's audit base, the
+     * session key, and the args behind the #224 actionKey. Nothing about the
+     * approval prompt is retained — the preview is the guard's own already-bounded
+     * one, so the secret-egress discipline the card copy follows holds here too.
+     */
+    function attachDecisionAudit(err, auditBase) {
+        let sessionKey;
+        // Resolving the key is new work on the card path — nothing used to call
+        // keyFor here. A throwing resolver costs the row its key; it must never
+        // turn a mintable card into an approval error.
+        try {
+            sessionKey = options?.sessionGuard?.keyFor(lastSessionId) ?? undefined;
+        }
+        catch { /* unkeyed row */ }
+        // Shallow-snapshot the args: reference capture would let in-place mutation
+        // of the params object between hold and resolution rewrite the one
+        // forensic binding this row exists to protect (review nit, both reviewers).
+        const captured = { sessionKey, args: lastCallArgs ? { ...lastCallArgs } : undefined };
+        const held = { ...auditBase };
+        let written = false;
+        err.decisionAudit = (outcome) => {
+            // The closure's type says CardAuditOutcome, but it crosses a plugin
+            // boundary — make the union real at runtime rather than trusting the
+            // caller's compiler (defence-in-depth, both reviewers).
+            if (!CARD_AUDIT_OUTCOMES.has(outcome))
+                return;
+            // The host resolves a card once. Enforcing it here is cheaper than
+            // trusting it: a duplicate row would double-count in every summary.
+            if (written)
+                return;
+            written = true;
+            // Never throws, by contract — even if the audit plumbing does. The latch
+            // is consumed either way: never-double-write beats a retried row.
+            try {
+                // ts is the DECISION time; the hold time stays in heldAtTs so
+                // forensics can see both ends of the operator's think.
+                emitAuditWith({ ...held, heldAtTs: held.ts, ts: new Date().toISOString(), action: 'require_approval', outcome }, captured);
+            }
+            catch { /* audit is best-effort; the decision itself already happened */ }
+        };
+    }
     function guardAuditBase(toolName, v, preview) {
         return {
             type: 'intercept', tool: toolName,
@@ -912,6 +991,15 @@ export function createInterceptor(config, pipeline, options) {
             approved = await withApprovalDeadline(context.requireApproval(formatActionGuardPrompt(context.toolName, v)), brokered ? brokerApprovalTimeoutMs(v.severity) : 0);
         }
         catch (err) {
+            // #310: a minted approval card, not an error. Re-thrown untouched so the
+            // typed-hook bridge can turn it into the operator's card; auditing it
+            // here would write a denial for a decision nobody has made yet.
+            if (isTypedApprovalRequest(err)) {
+                // #372: still no row for the hold — but the card leaves carrying the
+                // closure that writes one the moment the operator answers.
+                attachDecisionAudit(err, auditBase);
+                throw err;
+            }
             if (brokered && err instanceof ApprovalTimeout) {
                 // The asymmetric path. Silence is only ever a yes for something the
                 // broker already pre-cleared — and that returned long before here — so
@@ -1080,6 +1168,19 @@ export function createInterceptor(config, pipeline, options) {
             approved = await context.requireApproval(message);
         }
         catch (err) {
+            // #310: same bridge, same rule — the card request is not an approval
+            // failure. Everything else below stays fail-closed.
+            // #372: this path (memory-write pipeline) mints cards too — its
+            // operator decision must leave the same audit row as the action-guard
+            // lane, captured at hold time for the same attribution reasons.
+            if (isTypedApprovalRequest(err)) {
+                attachDecisionAudit(err, {
+                    type: 'intercept', tool: context.toolName, severity, firewallResult,
+                    threats, anomalyScore, trustScore, sensitivityLevel, fragmentationScore, pipelineDurationMs,
+                    preview: fullContent.slice(0, 200), ts: new Date().toISOString(),
+                });
+                throw err;
+            }
             const failAction = config.failurePolicy[severity];
             log.warn(`[shieldcortex] ⚠️ requireApproval error: ${err instanceof Error ? err.message : err} — failure policy: ${failAction}`);
             const entry = {

package/dist/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.54.7",
+  "version": "4.54.9",
   "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

@@ -38,7 +38,7 @@ import { isTaintingScanSummary, severityFromScanSummary } from './scan-taint-pol
 import { classifyConversationOrigin } from './conversation-trust.js';
 import type { ConversationTrustDecision } from './conversation-trust.js';
 import { createInterceptor, DEFAULT_CONFIG as DEFAULT_INTERCEPTOR_CONFIG } from './interceptor.js';
-import type { InterceptorConfig, BrokerRuntime } from './interceptor.js';
+import type { ApprovalDecisionAudit, ApprovalDecisionOutcome, InterceptorConfig, BrokerRuntime } from './interceptor.js';
 import { syncInterceptEvent } from './intercept-ingest.js';
 import { cloudSync } from './cloud-sync.js';
 import { createGatewayNotifyChannel } from './gateway-notify-channel.js';
@@ -400,7 +400,15 @@ type AgentCtx = {
 type TypedBeforeToolCallEvent = {
   toolName: string;
   params?: Record<string, unknown>;
+  // Not supplied by today's OpenClaw (the session rides on the tool context —
+  // see #233), but resolveHookSessionId prefers the event when a host does
+  // send one, and every other hook's event carries it.
+  sessionId?: string;
 };
+/** Every answer the host can report for a minted card. The first three are
+ *  buttons (a subset of which the card offers via `allowedDecisions`); the last
+ *  two are the host closing the card without one. */
+type CardDecision = "allow-once" | "allow-always" | "deny" | "timeout" | "cancelled";
 type TypedBeforeToolCallResult = {
   block?: boolean;
   blockReason?: string;
@@ -410,8 +418,8 @@ type TypedBeforeToolCallResult = {
     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;
+    allowedDecisions?: Array<Extract<CardDecision, "allow-once" | "allow-always" | "deny">>;
+    onResolution?: (decision: CardDecision) => Promise<void> | void;
   };
 };
 type PluginApi = {
@@ -3288,6 +3296,12 @@ function handleLlmOutput(event: LlmOutputEvent, ctx: AgentCtx): void {
 
 class TypedApprovalRequest extends Error {
   request: NonNullable<TypedBeforeToolCallResult["requireApproval"]>;
+  /** #372 — one-shot audit writer the interceptor hangs on this error at hold
+   *  time, carrying the guard's audit base and the session the hold belongs to.
+   *  Both mint sites attach it (action-guard and memory-write pipelines).
+   *  Absent only for an older installed interceptor: then no `onResolution`
+   *  is wired at all and the card behaves exactly as it did before #372. */
+  decisionAudit?: ApprovalDecisionAudit;
 
   constructor(message: string, request: NonNullable<TypedBeforeToolCallResult["requireApproval"]>) {
     super(message);
@@ -3302,6 +3316,19 @@ function truncateApprovalText(text: string, maxLength: number): string {
   return `${normalized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
 }
 
+/** A held command can itself contain the credential that tripped the guard, and
+ *  an approval card is a chat surface. Same rule, same phrasing and same
+ *  trade as the Telegram card path (isSecretEgress / buildCardFields in
+ *  src/defence/iron-dome/openclaw-approval-channel.ts): the operator keeps the
+ *  tool, the signals and the severity, and loses exactly the text that must not
+ *  be forwarded. */
+const SECRET_EGRESS_PROMPT = /secret|credential/iu;
+const WITHHELD_COMMAND_TEXT = "(command withheld — contains credential material)";
+/** Prompt lines safe to forward on a secret-egress hold — label-only metadata.
+ *  `Reason:` (action guard) and `Content:` (memory write) are the two lines
+ *  that quote the payload, so anything not on this list is dropped. */
+const SAFE_APPROVAL_LINE = /^(?:Tool|Action|Risk|Signals|Threats):/iu;
+
 function buildTypedApprovalRequest(message: string): NonNullable<TypedBeforeToolCallResult["requireApproval"]> {
   const lines = message
     .split(/\r?\n/u)
@@ -3309,7 +3336,13 @@ function buildTypedApprovalRequest(message: string): NonNullable<TypedBeforeTool
     .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 detailLines = lines.slice(1);
+  const withholdPayload = SECRET_EGRESS_PROMPT.test(message);
+  const details = (
+    withholdPayload
+      ? [WITHHELD_COMMAND_TEXT, ...detailLines.filter((line) => SAFE_APPROVAL_LINE.test(line))]
+      : detailLines
+  ).join(" | ") || rawTitle;
   const riskText = message.toLowerCase();
   const severity = /\b(?:critical|catastrophic|auto[-_\s]?deny|exfil|rm\s+-rf)\b/u.test(riskText)
     ? "critical"
@@ -3321,29 +3354,89 @@ function buildTypedApprovalRequest(message: string): NonNullable<TypedBeforeTool
     title: truncateApprovalText(rawTitle, 80),
     description: truncateApprovalText(details, 256),
     severity,
-    timeoutMs: 120_000,
+    // The host's own ceiling (MAX_PLUGIN_APPROVAL_TIMEOUT_MS), matching
+    // CARD_TIMEOUT_MS on the Telegram card path. 120s was the old bridge's
+    // number and it expired cards the operator was still walking back to.
+    timeoutMs: 600_000,
     timeoutBehavior: "deny",
     allowedDecisions: ["allow-once", "deny"],
   };
 }
 
+export const __buildTypedApprovalRequestForTest = buildTypedApprovalRequest;
+
+/** #372 — the operator's answer, as the audit stream records it.
+ *
+ * `allow-always` is defensive: today's card only offers allow-once/deny (see
+ * `allowedDecisions`), but a host that grows the button must not be able to
+ * produce an approval nobody can find afterwards. It maps to `approved_once`
+ * rather than a sticky outcome because ShieldCortex grants nothing durable
+ * here — the next call is gated again. */
+/** The decision label as it may appear in a gateway log line. Host-supplied,
+ *  so it is reduced to an identifier shape first — a log line is not a place to
+ *  render whatever a caller passed. */
+function safeDecisionLabel(decision: unknown): string {
+  return String(decision).replace(/[^A-Za-z0-9_.:-]/gu, "?").slice(0, 32) || "unknown";
+}
+
+const CARD_DECISION_OUTCOME: Record<CardDecision, ApprovalDecisionOutcome> = {
+  "allow-once": "approved_once",
+  "allow-always": "approved_once",
+  deny: "card_denied",
+  timeout: "card_timeout",
+  cancelled: "card_cancelled",
+};
+
 async function handleTypedBeforeToolCall(
   event: TypedBeforeToolCallEvent,
   interceptor: ReturnType<typeof createInterceptor>,
   logger: PluginApi["logger"],
-  sessionId?: string,
+  ctx?: AgentCtx,
 ): Promise<TypedBeforeToolCallResult | void> {
+  const sessionId = resolveHookSessionId(event, ctx);
+  // #310: a card is only worth minting when a human is there to tap it. Cron
+  // and heartbeat runs are host-keyed automation with no operator attached, so
+  // offering OpenClaw an approval request there recreates #112 exactly — the
+  // turn waits out the timeout on a decision nobody can give. Withholding
+  // `requireApproval` puts the interceptor on its unattended branch instead,
+  // which denies on the failure policy immediately and loudly.
+  const attended = !isTrustedAutomationSession(sessionId);
   try {
     await interceptor.handleToolCall({
       toolName: event.toolName,
       arguments: event.params ?? {},
       sessionId,
-      requireApproval: async (message: string) => {
-        throw new TypedApprovalRequest(message, buildTypedApprovalRequest(message));
-      },
+      ...(attended
+        ? {
+            requireApproval: async (message: string) => {
+              throw new TypedApprovalRequest(message, buildTypedApprovalRequest(message));
+            },
+          }
+        : {}),
     });
   } catch (err) {
     if (err instanceof TypedApprovalRequest) {
+      const decisionAudit = err.decisionAudit;
+      if (decisionAudit) {
+        // #372: the hold writes no row because no decision exists yet — THIS is
+        // where the operator's answer becomes one. The host owns this callback
+        // and awaits it, so it must never see a throw: a broken audit sink is
+        // not a reason to disturb a decision the operator already made.
+        err.request.onResolution = (decision: CardDecision) => {
+          try {
+            const outcome = Object.hasOwn(CARD_DECISION_OUTCOME, decision) ? CARD_DECISION_OUTCOME[decision] : undefined;
+            if (!outcome) {
+              // A decision this build does not know. Say so loudly rather than
+              // guess — inventing an outcome would forge the operator's answer.
+              (logger as any)?.warn?.(`[shieldcortex] unrecognised approval decision '${safeDecisionLabel(decision)}' — no audit row written`);
+              return;
+            }
+            decisionAudit(outcome);
+          } catch (auditErr) {
+            (logger as any)?.warn?.(`[shieldcortex] approval decision audit failed (${safeDecisionLabel(decision)}): ${auditErr instanceof Error ? auditErr.message : auditErr}`);
+          }
+        };
+      }
       return { requireApproval: err.request };
     }
 
@@ -3648,13 +3741,16 @@ export default {
     if (!interceptorDisabledInHostConfig) {
       // 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, ctx?: { sessionId?: string }) => {
+      api.on('before_tool_call', async (event: TypedBeforeToolCallEvent, ctx?: AgentCtx) => {
         const interceptor = await initInterceptor();
         if (!interceptor) return;
         // #233: the host supplies the session on the tool CONTEXT, not the
         // event. Without it a taint cannot be matched to the call it should
         // gate, so the escalation would silently never fire.
-        return handleTypedBeforeToolCall(event, interceptor, api.logger, ctx?.sessionId);
+        // #310: the WHOLE context, not just `sessionId` — resolveHookSessionId
+        // also reads `sessionKey`, which is where a cron/heartbeat run's key
+        // actually arrives, and that key decides whether a card is minted.
+        return handleTypedBeforeToolCall(event, interceptor, api.logger, ctx);
       }, { priority: 80, timeoutMs: 30_000 });
       _beforeToolCallRegistered = true;
       // NOTE: session_end is NOT registered here — it moved out of this guard

package/interceptor.ts

@@ -198,9 +198,55 @@ export interface ToolCallContext {
   sessionId?: string;
 }
 
+/**
+ * #372 — outcomes only an OpenClaw-native approval card can produce.
+ *
+ * The card is minted by throwing (see isTypedApprovalRequest) and the
+ * operator's answer comes back through the host minutes later, long after the
+ * hook returned. These outcomes are deliberately distinct from the synchronous
+ * `approved`/`denied` pair: a row that says `approved_once` is a human tapping
+ * a button on a card, not an approver function returning true inside the turn.
+ */
+export type ApprovalDecisionOutcome =
+  | 'approved_once'
+  | 'card_denied'
+  | 'card_timeout'
+  | 'card_cancelled';
+
+/** #372 — the runtime mirror of ApprovalDecisionOutcome: the closure crosses a
+ *  plugin boundary, so the union is enforced with a Set, not just the compiler. */
+const CARD_AUDIT_OUTCOMES: ReadonlySet<string> = new Set([
+  'approved_once', 'card_denied', 'card_timeout', 'card_cancelled',
+]);
+
+/** #372 — one-shot writer for the decision a held card eventually receives.
+ *  Hung on the thrown approval request by the interceptor; invoked by the
+ *  plugin bridge from the host's `onResolution`. Never throws. */
+export type ApprovalDecisionAudit = (outcome: ApprovalDecisionOutcome) => void;
+
+/** Structural view of the plugin's TypedApprovalRequest error. Matched by
+ *  shape and never imported — the same compile-time-independence discipline as
+ *  isTypedApprovalRequest and ToolGuardVerdictLike. */
+interface DecisionAuditCarrier {
+  decisionAudit?: ApprovalDecisionAudit;
+}
+
+/** #372 — what an audit row needs from the tool call that produced it,
+ *  snapshotted at hold time. A card decision lands minutes later, by which
+ *  point the interceptor's live `lastSessionId`/`lastCallArgs` may describe a
+ *  completely different call — attributing the decision to THAT call would be
+ *  a forgery in exactly the record forensics trusts. */
+interface CapturedAuditContext {
+  sessionKey?: string;
+  args?: Record<string, unknown>;
+}
+
 export interface InterceptAuditEntry {
   type: 'intercept';
   tool: string;
+  /** #372 — card decision rows only: when the action was HELD. `ts` on those
+   *  rows is the operator's decision time; the pair bounds the wait. */
+  heldAtTs?: string;
   severity: Severity;
   firewallResult: string;
   threats: string[];
@@ -210,7 +256,10 @@ export interface InterceptAuditEntry {
   fragmentationScore: number | null;  // from the pipeline result's fragmentation score, or null
   pipelineDurationMs: number;         // wall-clock ms around the runDefencePipeline call
   action: InterceptAction | 'auto_deny' | 'rate_limit' | 'allow' | 'gate_degraded';
-  outcome: 'approved' | 'denied' | 'auto_denied' | 'logged' | 'warned' | 'failure_allowed' | 'failure_denied' | 'allowed';
+  outcome: 'approved' | 'denied' | 'auto_denied' | 'logged' | 'warned' | 'failure_allowed' | 'failure_denied' | 'allowed'
+    // #372 — card-held decisions, written when the operator answers rather than
+    // when the hold is taken. `action` for these rows is 'require_approval'.
+    | ApprovalDecisionOutcome;
   preview: string;
   ts: string;
   /** The approval broker's record for this call (#143). Present on exactly the
@@ -547,6 +596,23 @@ export function formatActionGuardPrompt(toolName: string, v: ToolGuardVerdictLik
   ].join('\n');
 }
 
+/**
+ * #310: the OpenClaw-native approval card is delivered by THROWING out of the
+ * injected `requireApproval` — the plugin's typed-hook bridge catches that
+ * throw and hands `{ requireApproval }` back to the host, which draws the card.
+ * So this particular rejection is control flow, not a failure, and the catch
+ * blocks below must let it pass straight through.
+ *
+ * Matched by NAME, not by class: the class lives in the plugin entrypoint
+ * (index.ts) and this file is deliberately free of a compile-time dependency on
+ * it, the same discipline as ToolGuardVerdictLike. Swallowing it as an approval
+ * error is exactly what turned every native card into a `failure_denied` the
+ * operator never saw.
+ */
+function isTypedApprovalRequest(err: unknown): err is Error & DecisionAuditCarrier {
+  return err instanceof Error && err.name === 'TypedApprovalRequest';
+}
+
 // --- Audit Logging (local JSONL) ---
 
 /** Resolve per write so isolated tests can redirect every realtime audit path.
@@ -890,19 +956,79 @@ export function createInterceptor(
   /** Bare tool names seen this session, newest last. See buildSessionSummary. */
   const recentTools: string[] = [];
 
-  function emitAudit(entry: InterceptAuditEntry): void {
-    const sessionKey = options?.sessionGuard?.keyFor(lastSessionId) ?? undefined;
+  /** The one write path every intercept row takes. `captured` is normally the
+   *  in-flight call (emitAudit below); #372 hands it a hold-time snapshot so a
+   *  decision that arrives after the turn moved on still lands on ITS call. */
+  function emitAuditWith(entry: InterceptAuditEntry, captured: CapturedAuditContext): void {
     const withOrigin: InterceptAuditEntry = {
       ...entry,
       origin: 'openclaw-interceptor',
-      ...(sessionKey ? { sessionKey } : {}),
+      ...(captured.sessionKey ? { sessionKey: captured.sessionKey } : {}),
     };
-    const bound = bindAudit ? bindAudit(withOrigin, lastCallArgs) : withOrigin;
+    const bound = bindAudit ? bindAudit(withOrigin, captured.args) : withOrigin;
     writeAuditEntry(bound);
     try { options?.sessionGuard?.index(bound); } catch { /* never wedge the turn */ }
     onAuditEntry?.(bound);
   }
 
+  function emitAudit(entry: InterceptAuditEntry): void {
+    emitAuditWith(entry, {
+      sessionKey: options?.sessionGuard?.keyFor(lastSessionId) ?? undefined,
+      args: lastCallArgs,
+    });
+  }
+
+  /**
+   * #372 — hang a one-shot decision writer on a minted approval card.
+   *
+   * The hold itself is still unaudited by design: no decision exists yet. What
+   * was missing is the other end — the host reports the operator's answer on
+   * the request's `onResolution`, and nothing on that path knew what the guard
+   * saw, so an operator-APPROVED dangerous action left no intercept row at all
+   * (invisible to the #260 session summaries).
+   *
+   * Everything the row needs is captured HERE: the guard's audit base, the
+   * session key, and the args behind the #224 actionKey. Nothing about the
+   * approval prompt is retained — the preview is the guard's own already-bounded
+   * one, so the secret-egress discipline the card copy follows holds here too.
+   */
+  function attachDecisionAudit(
+    err: Error & DecisionAuditCarrier,
+    auditBase: Omit<InterceptAuditEntry, 'action' | 'outcome'>,
+  ): void {
+    let sessionKey: string | undefined;
+    // Resolving the key is new work on the card path — nothing used to call
+    // keyFor here. A throwing resolver costs the row its key; it must never
+    // turn a mintable card into an approval error.
+    try { sessionKey = options?.sessionGuard?.keyFor(lastSessionId) ?? undefined; } catch { /* unkeyed row */ }
+    // Shallow-snapshot the args: reference capture would let in-place mutation
+    // of the params object between hold and resolution rewrite the one
+    // forensic binding this row exists to protect (review nit, both reviewers).
+    const captured: CapturedAuditContext = { sessionKey, args: lastCallArgs ? { ...lastCallArgs } : undefined };
+    const held: Omit<InterceptAuditEntry, 'action' | 'outcome'> = { ...auditBase };
+    let written = false;
+    err.decisionAudit = (outcome) => {
+      // The closure's type says CardAuditOutcome, but it crosses a plugin
+      // boundary — make the union real at runtime rather than trusting the
+      // caller's compiler (defence-in-depth, both reviewers).
+      if (!CARD_AUDIT_OUTCOMES.has(outcome)) return;
+      // The host resolves a card once. Enforcing it here is cheaper than
+      // trusting it: a duplicate row would double-count in every summary.
+      if (written) return;
+      written = true;
+      // Never throws, by contract — even if the audit plumbing does. The latch
+      // is consumed either way: never-double-write beats a retried row.
+      try {
+        // ts is the DECISION time; the hold time stays in heldAtTs so
+        // forensics can see both ends of the operator's think.
+        emitAuditWith(
+          { ...held, heldAtTs: held.ts, ts: new Date().toISOString(), action: 'require_approval', outcome },
+          captured,
+        );
+      } catch { /* audit is best-effort; the decision itself already happened */ }
+    };
+  }
+
   function guardAuditBase(toolName: string, v: ToolGuardVerdictLike, preview: string): Omit<InterceptAuditEntry, 'action' | 'outcome'> {
     return {
       type: 'intercept', tool: toolName,
@@ -1297,6 +1423,15 @@ export function createInterceptor(
         brokered ? brokerApprovalTimeoutMs(v.severity) : 0,
       );
     } catch (err) {
+      // #310: a minted approval card, not an error. Re-thrown untouched so the
+      // typed-hook bridge can turn it into the operator's card; auditing it
+      // here would write a denial for a decision nobody has made yet.
+      if (isTypedApprovalRequest(err)) {
+        // #372: still no row for the hold — but the card leaves carrying the
+        // closure that writes one the moment the operator answers.
+        attachDecisionAudit(err, auditBase);
+        throw err;
+      }
       if (brokered && err instanceof ApprovalTimeout) {
         // The asymmetric path. Silence is only ever a yes for something the
         // broker already pre-cleared — and that returned long before here — so
@@ -1477,6 +1612,19 @@ export function createInterceptor(
     try {
       approved = await context.requireApproval(message);
     } catch (err) {
+      // #310: same bridge, same rule — the card request is not an approval
+      // failure. Everything else below stays fail-closed.
+      // #372: this path (memory-write pipeline) mints cards too — its
+      // operator decision must leave the same audit row as the action-guard
+      // lane, captured at hold time for the same attribution reasons.
+      if (isTypedApprovalRequest(err)) {
+        attachDecisionAudit(err, {
+          type: 'intercept', tool: context.toolName, severity, firewallResult,
+          threats, anomalyScore, trustScore, sensitivityLevel, fragmentationScore, pipelineDurationMs,
+          preview: fullContent.slice(0, 200), ts: new Date().toISOString(),
+        });
+        throw err;
+      }
       const failAction = config.failurePolicy[severity];
       log.warn(`[shieldcortex] ⚠️ requireApproval error: ${err instanceof Error ? err.message : err} — failure policy: ${failAction}`);
       const entry: InterceptAuditEntry = {

package/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "shieldcortex-realtime",
-  "version": "4.54.7",
+  "version": "4.54.9",
   "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.54.7",
+  "version": "4.54.9",
   "description": "OpenClaw plugin for ShieldCortex real-time defence scanning and optional memory extraction.",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,7 +27,7 @@
     "prepublishOnly": "node -e \"if(!require('fs').existsSync('dist/index.js'))throw new Error('plugin dist/index.js missing — run `npm run build:ts` from the repo root before publishing')\""
   },
   "peerDependencies": {
-    "shieldcortex": "^4.54.6",
+    "shieldcortex": "^4.54.8",
     "openclaw": ">=2026.3.22"
   },
   "peerDependenciesMeta": {