@drakon-systems/shieldcortex-realtime 4.47.17 → 4.47.19

package/dist/broker-invoker.js

@@ -0,0 +1,118 @@
+/**
+ * ShieldCortex — the OpenClaw judge transport for the approval broker (#143).
+ *
+ * Design: docs/design/2026-07-31-ai-approval-broker.md
+ *
+ * The design decided (Michael, 31 Jul 2026) that the broker rides the host's
+ * existing model pool: no API key of its own, no login, no second bill. On the
+ * gateway that means "ask OpenClaw for one completion through the pool the
+ * operator already pays for and already governs".
+ *
+ * The gateway does not expose a completion seam to plugins today. Rather than
+ * inventing credentials or importing an SDK — either of which would make
+ * ShieldCortex a second, unaudited path to a model using the operator's
+ * money — this defines the narrowest seam that could satisfy the design and
+ * fails closed when it is absent:
+ *
+ *   no `context.invokeModel` → no invoker → no judge → the broker HOLDS.
+ *
+ * Which is exactly today's behaviour: the operator gets asked. When a gateway
+ * build starts offering `invokeModel`, the broker lights up with no change here.
+ *
+ * The second half of the contract is what the seam is NOT given. The request is
+ * a system prompt and one block of text, and the exported key allowlist is
+ * asserted by test — because the failure mode this guards against is somebody
+ * later adding `messages` or `session` "for context" and quietly handing the
+ * judge the poisoned transcript it exists to be immune to.
+ *
+ * Types are declared locally rather than imported from `shieldcortex/defence`:
+ * this file is built by tsconfig.openclaw-plugin.json across the plugin
+ * boundary, the same reason `ToolGuardVerdictLike` is structural in
+ * interceptor.ts.
+ */
+/** The exact key set of a request. Pinned by test — see the header. */
+export const GATEWAY_REQUEST_KEYS = ['system', 'prompt', 'toolless', 'model', 'timeoutMs'];
+/** A judge reply is one small JSON object; anything past this is noise. */
+const MAX_COMPLETION_CHARS = 65_536;
+/** Duplicated from broker-config.ts's MODEL_NAME — the plugin build cannot
+ *  import across the package boundary, and a hostile model string must be
+ *  refused on both sides of it. Kept in sync there. */
+const MODEL_NAME = /^[A-Za-z0-9][A-Za-z0-9._:@/-]*$/;
+function safeModel(model) {
+    if (typeof model !== 'string')
+        return undefined;
+    const trimmed = model.trim();
+    if (!trimmed || trimmed.length > 64 || !MODEL_NAME.test(trimmed))
+        return undefined;
+    return trimmed;
+}
+/**
+ * Read text out of whatever the host's pool returned.
+ *
+ * Deliberately permissive about SHAPE (a gateway may hand back a string, an
+ * Anthropic-style content array, or an OpenAI-style message) and deliberately
+ * strict about SUBSTANCE: anything that is not readable text is null, and null
+ * becomes a rejection, which becomes a hold. A response we cannot read is never
+ * optimistically treated as approval.
+ */
+export function coerceCompletion(raw) {
+    const bound = (s) => (s.length > MAX_COMPLETION_CHARS ? s.slice(0, MAX_COMPLETION_CHARS) : s);
+    if (typeof raw === 'string')
+        return bound(raw);
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const o = raw;
+    for (const key of ['text', 'completion', 'output']) {
+        if (typeof o[key] === 'string')
+            return bound(o[key]);
+    }
+    if (typeof o.content === 'string')
+        return bound(o.content);
+    if (Array.isArray(o.content)) {
+        const parts = o.content
+            .filter((b) => !!b && typeof b === 'object')
+            .filter(b => b.type === 'text' && typeof b.text === 'string')
+            .map(b => b.text);
+        return parts.length ? bound(parts.join('')) : null;
+    }
+    if (o.message && typeof o.message === 'object')
+        return coerceCompletion(o.message);
+    return null;
+}
+/**
+ * Build a judge transport from the gateway's completion seam, or null when the
+ * gateway does not offer one.
+ *
+ * Null is not an error state — it is the honest answer on every gateway build
+ * that ships today, and the broker's response to it (hold for the operator) is
+ * the behaviour ShieldCortex already had.
+ */
+export function createGatewayInvoker(context, opts = {}) {
+    if (!context || typeof context !== 'object')
+        return null;
+    const invokeModel = context.invokeModel;
+    if (typeof invokeModel !== 'function')
+        return null;
+    const model = safeModel(opts.model);
+    return async (system, user) => {
+        const req = {
+            system,
+            prompt: user,
+            toolless: true,
+        };
+        if (model)
+            req.model = model;
+        if (typeof opts.timeoutMs === 'number' && Number.isFinite(opts.timeoutMs))
+            req.timeoutMs = opts.timeoutMs;
+        // A throw here propagates: runJudge catches it and returns null, which the
+        // broker reads as "hold". Swallowing it into a default would be the one
+        // failure mode this whole layer exists to avoid.
+        const raw = await invokeModel(req);
+        const text = coerceCompletion(raw);
+        if (text === null)
+            throw new Error('gateway returned an unreadable completion');
+        if (!text.trim())
+            throw new Error('gateway returned an empty completion');
+        return text;
+    };
+}

package/dist/index.js

@@ -215,6 +215,16 @@ const PLUGIN_CONFIG_UI_HINTS = {
         help: "Write an audit entry when the guard evaluates a recognised operation and allows it.",
         advanced: true,
     },
+    "interceptor.actionGuard.broker.enabled": {
+        label: "AI Approval Broker",
+        help: "Let a fast model judge dangerous-tier approvals before they reach you: it can deny outright when it sees injection, and release reversible, in-context, high-confidence actions without waiting. Never applies to catastrophic operations. Off by default.",
+        advanced: true,
+    },
+    "interceptor.actionGuard.broker.allowPreClear": {
+        label: "Allow Broker Pre-clear",
+        help: "Off = every dangerous-tier action still waits for you; the broker can then only harden, never release.",
+        advanced: true,
+    },
 };
 const SEVERITY_ACTION_SCHEMA = {
     type: "object",
@@ -241,6 +251,28 @@ const INTERCEPTOR_JSON_SCHEMA = {
                 enforce: { type: "boolean" },
                 autoApprove: { type: "array", items: { type: "string" } },
                 auditAllows: { type: "boolean" },
+                // #143. Mirrors normaliseBrokerConfig's allowlist; that function still
+                // has the last word, so a value that slips past the schema is still
+                // range-checked (and dropped) before the broker sees it.
+                broker: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        enabled: { type: "boolean" },
+                        allowPreClear: { type: "boolean" },
+                        preClearConfidence: { type: "number", minimum: 0.9, maximum: 1 },
+                        judgeTimeoutMs: { type: "number", minimum: 500, maximum: 60000 },
+                        approvalTimeoutMs: {
+                            type: "object",
+                            additionalProperties: false,
+                            properties: {
+                                sensitive: { type: "number", minimum: 1000, maximum: 3600000 },
+                                dangerous: { type: "number", minimum: 1000, maximum: 3600000 },
+                            },
+                        },
+                        model: { type: "string" },
+                    },
+                },
             },
         },
     },
@@ -375,6 +407,12 @@ function normaliseInterceptorConfig(raw) {
         if (Array.isArray(rawGuard.autoApprove) && rawGuard.autoApprove.every((entry) => typeof entry === "string")) {
             guard.autoApprove = rawGuard.autoApprove;
         }
+        // Carried through untouched — normaliseBrokerConfig is the boundary, and
+        // splitting that job across two files is how one of the halves ends up
+        // being the lenient one.
+        if (rawGuard.broker && typeof rawGuard.broker === "object" && !Array.isArray(rawGuard.broker)) {
+            guard.broker = rawGuard.broker;
+        }
         if (Object.keys(guard).length > 0)
             out.actionGuard = guard;
     }
@@ -848,6 +886,48 @@ async function handleTypedBeforeToolCall(event, interceptor, logger) {
     }
 }
 // ==================== PLUGIN EXPORT ====================
+/**
+ * Assemble the approval broker (#143) from the main package, or return
+ * undefined.
+ *
+ * Undefined is the normal answer and a safe one: no broker means the guard
+ * behaves exactly as it did before #143 — every dangerous-tier call goes to the
+ * operator. It is returned whenever the broker is not switched on, and whenever
+ * the installed `shieldcortex` build is older than the broker (a version skew
+ * this plugin has to survive, which is why every piece is looked up by name
+ * rather than imported).
+ *
+ * All four pieces are required together. A half-wired broker — a decision core
+ * with no config normaliser, say — would be a policy consuming unvalidated
+ * input, which is the one shape this feature must never take.
+ */
+function resolveBrokerRuntime(defenceMod, rawBrokerConfig, api) {
+    try {
+        const needed = ['normaliseBrokerConfig', 'brokerDecision', 'runJudge', 'timeoutOutcome'];
+        if (needed.some((fn) => typeof defenceMod?.[fn] !== 'function')) {
+            if (rawBrokerConfig?.enabled === true) {
+                api.logger?.warn?.('[shieldcortex] approval broker requested but this shieldcortex build does not provide it — every dangerous action still goes to you');
+            }
+            return undefined;
+        }
+        const config = defenceMod.normaliseBrokerConfig(rawBrokerConfig);
+        if (!config?.enabled)
+            return undefined;
+        api.logger?.info?.(`[shieldcortex] approval broker ON — judge via the gateway model pool${config.model ? ` (${config.model})` : ''}, pre-clear ${config.allowPreClear ? `at ≥${config.preClearConfidence}` : 'disabled'}`);
+        return {
+            config,
+            runJudge: defenceMod.runJudge,
+            brokerDecision: defenceMod.brokerDecision,
+            timeoutOutcome: defenceMod.timeoutOutcome,
+            approvalTimeoutMs: typeof defenceMod.approvalTimeoutMs === 'function' ? defenceMod.approvalTimeoutMs : undefined,
+        };
+    }
+    catch (err) {
+        api.logger?.warn?.(`[shieldcortex] approval broker unavailable: ${err instanceof Error ? err.message : err} — holding every dangerous action for you`);
+        return undefined;
+    }
+}
+export const __testables = { resolveBrokerRuntime };
 export default {
     id: PLUGIN_ID,
     name: "ShieldCortex Real-time Scanner",
@@ -905,6 +985,7 @@ export default {
                         evaluateToolCall: typeof defenceMod.evaluateToolCall === 'function'
                             ? defenceMod.evaluateToolCall
                             : undefined,
+                        broker: resolveBrokerRuntime(defenceMod, interceptorConfig.actionGuard?.broker, api),
                         onAuditEntry: (entry) => syncInterceptEvent(entry, {
                             cloudApiKey: scConfig.cloudApiKey ?? '',
                             cloudBaseUrl: scConfig.cloudBaseUrl ?? 'https://api.shieldcortex.ai',

package/dist/interceptor.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { mkdirSync, appendFileSync, readFileSync, statSync } from 'node:fs';
 import { join, isAbsolute, resolve as resolvePath } from 'node:path';
 import { homedir } from 'node:os';
+import { createGatewayInvoker } from './broker-invoker.js';
 const WATCHED_TOOLS = ['remember', 'mcp__memory__remember'];
 const CONTENT_FIELDS = {
     remember: ['content', 'title'],
@@ -199,6 +200,8 @@ const FALLBACK_DANGEROUS_PATTERNS = [
     { re: /\btruncate\b[^|;&\n]*(?:-s\s*0\b|--size(?:=|\s+)0\b)/i, signal: 'truncate-to-zero' },
     { re: /\bhistory\s+-c\b|\.bash_history|truncate\b[^|\n]*\.log/i, signal: 'wipe-history-or-logs' },
     { 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' },
     { 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' },
@@ -374,6 +377,41 @@ export function createScriptSourceResolver(cwd) {
         }
     };
 }
+/** Raised when the operator never answered the approval card (#143). Distinct
+ *  from a transport error, because the two have opposite handling: an error
+ *  routes to failurePolicy, a timeout routes to the broker's asymmetric rule. */
+export class ApprovalTimeout extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`no approval answer within ${timeoutMs}ms`);
+        this.timeoutMs = timeoutMs;
+        this.name = 'ApprovalTimeout';
+    }
+}
+/**
+ * Race an approval against a deadline.
+ *
+ * `timeoutMs <= 0` means no deadline at all — the pre-#143 behaviour, where the
+ * gateway's own card owns the waiting. A deadline is only ever applied when the
+ * broker is in play, and it can only turn an unanswered card into the broker's
+ * timeout rule, which for everything but a pre-cleared call is a denial.
+ */
+export function withApprovalDeadline(approval, timeoutMs) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        return approval;
+    let timer;
+    // A card answered after we stopped listening must not surface as an unhandled
+    // rejection in the gateway process.
+    const guarded = approval.catch(err => { throw err; });
+    guarded.catch(() => { });
+    return Promise.race([
+        guarded,
+        new Promise((_resolve, reject) => {
+            timer = setTimeout(() => reject(new ApprovalTimeout(timeoutMs)), timeoutMs);
+        }),
+    ]).finally(() => { if (timer)
+        clearTimeout(timer); });
+}
 /** The cwd a tool call runs in, if the gateway or the call itself names one. */
 function toolCallCwd(context) {
     if (typeof context.cwd === 'string' && context.cwd)
@@ -385,6 +423,13 @@ function toolCallCwd(context) {
     }
     return undefined;
 }
+/** How many recent tool NAMES the judge is told about. Names only, never
+ *  arguments — see buildSessionSummary. */
+const SESSION_TOOL_MEMORY = 12;
+/** Tool names are registry-supplied, not free text, but an MCP server can name
+ *  a tool anything at all — so they are reduced to an identifier shape before
+ *  being placed anywhere near a prompt. */
+const TOOL_NAME_SAFE = /[^A-Za-z0-9_.:-]/g;
 export function createInterceptor(config, pipeline, options) {
     const denyCache = new DenyCache();
     const rateLimiter = new RateLimiter(options?.maxPromptsPerMinute ?? 5);
@@ -392,6 +437,13 @@ export function createInterceptor(config, pipeline, options) {
     const onAuditEntry = options?.onAuditEntry;
     const actionGuardCfg = config.actionGuard ?? { enabled: true, enforce: true, autoApprove: [] };
     const evaluateToolCall = options?.evaluateToolCall;
+    const broker = options?.broker;
+    // The judge rides the operator's own model pool, so its calls are their cost
+    // and their rate limit. Bounded per minute, and running out means "no judge",
+    // which the decision core reads as "hold for the human" — never as an allow.
+    const judgeLimiter = new RateLimiter(options?.maxJudgeCallsPerMinute ?? 20);
+    /** Bare tool names seen this session, newest last. See buildSessionSummary. */
+    const recentTools = [];
     function emitAudit(entry) {
         writeAuditEntry(entry);
         onAuditEntry?.(entry);
@@ -406,6 +458,97 @@ export function createInterceptor(config, pipeline, options) {
             preview: preview.slice(0, 200), ts: new Date().toISOString(),
         };
     }
+    // ── Approval broker (#143) ────────────────────────────────────────────────
+    /**
+     * The ONLY thing the judge is told about the session.
+     *
+     * The design's third open question was "what does the broker see of the
+     * session, and how do we stop *that* being the injection vector?" — a
+     * poisoned transcript arguing its own approval is the obvious attack. The
+     * answer here is the narrowest thing that still means anything: a list of
+     * bare tool NAMES, sanitised to an identifier shape. No arguments, no
+     * content, no memory text, no user or assistant turns.
+     *
+     * That is enough for "does this action fit what the session was doing?" —
+     * an `npm install` in a session of Read/Edit/Bash is in pattern; the same
+     * command as the first act of a session is not — and it carries no attacker
+     * prose, because there is nowhere in it for prose to live.
+     */
+    function buildSessionSummary() {
+        if (recentTools.length === 0)
+            return undefined;
+        const names = [...new Set(recentTools)].join(', ');
+        return `tools used in this session so far (names only, no arguments): ${names}`;
+    }
+    function noteToolForSession(toolName) {
+        const safe = String(toolName ?? '').replace(TOOL_NAME_SAFE, '').slice(0, 60);
+        if (!safe)
+            return;
+        recentTools.push(safe);
+        if (recentTools.length > SESSION_TOOL_MEMORY)
+            recentTools.shift();
+    }
+    /**
+     * One broker pass over a dangerous-tier verdict.
+     *
+     * Returns null when the broker is not in play at all — no runtime injected,
+     * or disabled by config — and the caller then behaves exactly as it did
+     * before #143. Every *failure* inside a pass (no model seam, pool down, junk
+     * reply, budget spent, core throwing) resolves to a decision of `hold` or to
+     * null, both of which route to the operator. There is no path here that
+     * produces an allow the guard would not otherwise have produced.
+     */
+    async function runBroker(context, v) {
+        if (!broker || broker.config?.enabled !== true)
+            return null;
+        try {
+            // No seam on this gateway build → no invoker → no judge. Not an error:
+            // it is the honest state of every gateway shipping today.
+            const invoke = createGatewayInvoker(context, {
+                model: broker.config.model,
+                timeoutMs: broker.config.judgeTimeoutMs,
+            });
+            let judge = null;
+            if (invoke && judgeLimiter.shouldAllow()) {
+                judge = await broker.runJudge({
+                    tool: context.toolName,
+                    toolInput: context.arguments,
+                    verdict: { severity: v.severity, action: v.action, reason: v.reason, signals: v.signals },
+                    sessionSummary: buildSessionSummary(),
+                }, invoke, { timeoutMs: broker.config.judgeTimeoutMs });
+            }
+            else if (invoke) {
+                log.warn(`[shieldcortex] approval broker: judge budget spent this minute — holding ${context.toolName} for the operator`);
+            }
+            const decision = broker.brokerDecision({
+                tool: context.toolName,
+                toolInput: context.arguments,
+                verdict: v,
+                judge,
+                policy: {
+                    allowPreClear: broker.config.allowPreClear,
+                    preClearConfidence: broker.config.preClearConfidence,
+                },
+            });
+            // A decision we cannot read is not a decision. Falling back to null puts
+            // the call on the pre-#143 path, which asks the human.
+            if (!decision || typeof decision.outcome !== 'string')
+                return null;
+            return decision;
+        }
+        catch (err) {
+            log.warn(`[shieldcortex] ⚠️ approval broker error: ${err instanceof Error ? err.message : err} — holding for the operator`);
+            return null;
+        }
+    }
+    /** How long to wait for a human once the broker is in play. */
+    function brokerApprovalTimeoutMs(severity) {
+        if (!broker)
+            return 0;
+        if (typeof broker.approvalTimeoutMs === 'function')
+            return broker.approvalTimeoutMs(broker.config, severity);
+        return Math.min(broker.config.approvalTimeoutMs.sensitive, broker.config.approvalTimeoutMs.dangerous);
+    }
     // WS2 fail-closed path (issue #59): when the real guard was never wired in or
     // throws, run the dependency-free fallback scan. Three tiers, so no dangerous
     // op is ever silently allowed on a scan failure — and every could-not-scan
@@ -526,44 +669,93 @@ export function createInterceptor(config, pipeline, options) {
             emitAudit({ ...base, action: 'warn', outcome: 'warned' });
             return;
         }
+        // ── AI-assisted approval broker (#143) ──────────────────────────────────
+        // Sits between the guard's verdict and the human, and can only move the
+        // answer toward caution. Off by default; when off, `brokered` is null and
+        // everything below is the pre-#143 code path unchanged.
+        const brokered = await runBroker(context, v);
+        // Every downstream audit row for a brokered call carries the broker's own
+        // record alongside the guard's, so one row answers "was a model consulted,
+        // what did it say, and what did that change?".
+        const auditBase = brokered ? { ...base, broker: brokered.audit } : base;
+        if (brokered?.outcome === 'harden') {
+            // The judge found something the rules did not. Deny outright rather than
+            // offer the operator a button to be socially-engineered into tapping.
+            emitAudit({ ...auditBase, action: 'require_approval', outcome: 'auto_denied' });
+            log.warn(`[shieldcortex] approval broker HARDENED ${context.toolName} to a denial: ${brokered.reason}`);
+            throw new Error(`ShieldCortex: tool call blocked — ${brokered.reason}`);
+        }
+        if (brokered?.outcome === 'pre_clear') {
+            // Reversible, on-host, in-context, judge-confident: proceed without
+            // waiting. Loud on purpose — a release nobody approved must never be a
+            // silent one, because the audit row is the only thing that will ever tell
+            // the operator it happened.
+            emitAudit({ ...auditBase, action: 'require_approval', outcome: 'approved' });
+            log.warn(`[shieldcortex] approval broker PRE-CLEARED ${context.toolName} without waiting for the operator: ${brokered.reason} [${v.signals.join(', ')}]`);
+            return;
+        }
         if (typeof context.requireApproval !== 'function') {
             // Unattended (no approver, e.g. cron/heartbeat): fail closed on the failure
             // policy. High-severity dangerous defaults to deny — surfaced loudly to the
             // gateway log so an operator sees it, because a silent no-op is exactly the
             // failure mode we are eliminating.
+            //
+            // With the broker in play this can only get STRICTER: no approver is the
+            // timeout case by definition, and `timeoutOutcome` answers 'approve' only
+            // for a pre-cleared call, which already returned above. So a brokered call
+            // that reaches here denies even where failurePolicy would have allowed.
             const failAction = config.failurePolicy[severity];
-            emitAudit({ ...base, action: 'require_approval', outcome: failAction === 'deny' ? 'failure_denied' : 'failure_allowed' });
-            if (failAction === 'deny') {
+            const brokerDenies = brokered ? broker.timeoutOutcome(brokered) === 'deny' : false;
+            const deny = failAction === 'deny' || brokerDenies;
+            emitAudit({ ...auditBase, action: 'require_approval', outcome: deny ? 'failure_denied' : 'failure_allowed' });
+            if (deny) {
                 log.warn(`[shieldcortex] action-guard DENIED (unattended, no approver) ${context.toolName}: ${v.reason} [${v.signals.join(", ")}]`);
                 throw new Error(`ShieldCortex: tool call blocked — ${v.reason} (no approver, failure policy: deny)`);
             }
             return;
         }
         if (!rateLimiter.shouldAllow()) {
-            emitAudit({ ...base, action: 'rate_limit', outcome: 'auto_denied' });
+            emitAudit({ ...auditBase, action: 'rate_limit', outcome: 'auto_denied' });
             throw new Error('ShieldCortex: tool call auto-denied (approval rate limit exceeded)');
         }
         let approved;
         try {
-            approved = await context.requireApproval(formatActionGuardPrompt(context.toolName, v));
+            approved = await withApprovalDeadline(context.requireApproval(formatActionGuardPrompt(context.toolName, v)), brokered ? brokerApprovalTimeoutMs(v.severity) : 0);
         }
         catch (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
+                // in practice this is always a deny. It reads the broker's own derived
+                // flag rather than re-deriving its own idea of what is safe.
+                const outcome = broker.timeoutOutcome(brokered);
+                emitAudit({ ...auditBase, action: 'require_approval', outcome: outcome === 'approve' ? 'approved' : 'auto_denied' });
+                if (outcome === 'approve') {
+                    log.warn(`[shieldcortex] approval broker: no answer in ${err.timeoutMs}ms — auto-approving pre-cleared ${context.toolName}`);
+                    return;
+                }
+                log.warn(`[shieldcortex] approval broker: no answer in ${err.timeoutMs}ms — DENYING ${context.toolName} (fail-closed)`);
+                throw new Error(`ShieldCortex: tool call blocked — no answer from the operator within ${err.timeoutMs}ms (fail-closed)`);
+            }
             const failAction = config.failurePolicy[severity];
             log.warn(`[shieldcortex] ⚠️ requireApproval error: ${err instanceof Error ? err.message : err} — failure policy: ${failAction}`);
-            emitAudit({ ...base, action: 'require_approval', outcome: failAction === 'deny' ? 'failure_denied' : 'failure_allowed' });
+            emitAudit({ ...auditBase, action: 'require_approval', outcome: failAction === 'deny' ? 'failure_denied' : 'failure_allowed' });
             if (failAction === 'deny') {
                 throw new Error('ShieldCortex: tool call blocked — approval error, failure policy: deny');
             }
             return;
         }
         if (approved) {
-            emitAudit({ ...base, action: 'require_approval', outcome: 'approved' });
+            emitAudit({ ...auditBase, action: 'require_approval', outcome: 'approved' });
             return;
         }
-        emitAudit({ ...base, action: 'require_approval', outcome: 'denied' });
+        emitAudit({ ...auditBase, action: 'require_approval', outcome: 'denied' });
         throw new Error('ShieldCortex: tool call denied by user');
     }
     async function handleToolCall(context) {
+        // 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);
         // Non-memory tools go through the Action Guard (what the agent DOES); the
         // memory-write tools continue through the content defence pipeline below.
         if (!WATCHED_TOOLS.includes(context.toolName)) {

package/dist/openclaw.plugin.json

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

@@ -16,7 +16,7 @@ import { homedir } from "node:os";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { createInterceptor, DEFAULT_CONFIG as DEFAULT_INTERCEPTOR_CONFIG } from './interceptor.js';
-import type { InterceptorConfig } from './interceptor.js';
+import type { InterceptorConfig, BrokerRuntime } from './interceptor.js';
 import { syncInterceptEvent } from './intercept-ingest.js';
 import { cloudSync } from './cloud-sync.js';
 
@@ -242,6 +242,11 @@ interface InterceptorUserConfig {
     enforce?: boolean;
     autoApprove?: string[];
     auditAllows?: boolean;
+    /** AI-assisted approval broker (#143). Passed through RAW: the real
+     *  validation is `normaliseBrokerConfig` in the main package, which is the
+     *  single place that knows which values would loosen an invariant. Off
+     *  unless `enabled: true`. */
+    broker?: Record<string, unknown>;
   };
 }
 
@@ -319,6 +324,16 @@ const PLUGIN_CONFIG_UI_HINTS = {
     help: "Write an audit entry when the guard evaluates a recognised operation and allows it.",
     advanced: true,
   },
+  "interceptor.actionGuard.broker.enabled": {
+    label: "AI Approval Broker",
+    help: "Let a fast model judge dangerous-tier approvals before they reach you: it can deny outright when it sees injection, and release reversible, in-context, high-confidence actions without waiting. Never applies to catastrophic operations. Off by default.",
+    advanced: true,
+  },
+  "interceptor.actionGuard.broker.allowPreClear": {
+    label: "Allow Broker Pre-clear",
+    help: "Off = every dangerous-tier action still waits for you; the broker can then only harden, never release.",
+    advanced: true,
+  },
 } as const;
 
 const SEVERITY_ACTION_SCHEMA = {
@@ -352,6 +367,28 @@ const INTERCEPTOR_JSON_SCHEMA = {
         enforce: { type: "boolean" },
         autoApprove: { type: "array", items: { type: "string" } },
         auditAllows: { type: "boolean" },
+        // #143. Mirrors normaliseBrokerConfig's allowlist; that function still
+        // has the last word, so a value that slips past the schema is still
+        // range-checked (and dropped) before the broker sees it.
+        broker: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            enabled: { type: "boolean" },
+            allowPreClear: { type: "boolean" },
+            preClearConfidence: { type: "number", minimum: 0.9, maximum: 1 },
+            judgeTimeoutMs: { type: "number", minimum: 500, maximum: 60000 },
+            approvalTimeoutMs: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                sensitive: { type: "number", minimum: 1000, maximum: 3600000 },
+                dangerous: { type: "number", minimum: 1000, maximum: 3600000 },
+              },
+            },
+            model: { type: "string" },
+          },
+        },
       },
     },
   },
@@ -491,6 +528,12 @@ function normaliseInterceptorConfig(raw: unknown): InterceptorUserConfig | undef
     if (Array.isArray(rawGuard.autoApprove) && rawGuard.autoApprove.every((entry) => typeof entry === "string")) {
       guard.autoApprove = rawGuard.autoApprove as string[];
     }
+    // Carried through untouched — normaliseBrokerConfig is the boundary, and
+    // splitting that job across two files is how one of the halves ends up
+    // being the lenient one.
+    if (rawGuard.broker && typeof rawGuard.broker === "object" && !Array.isArray(rawGuard.broker)) {
+      guard.broker = rawGuard.broker as Record<string, unknown>;
+    }
     if (Object.keys(guard).length > 0) out.actionGuard = guard;
   }
 
@@ -1020,6 +1063,55 @@ async function handleTypedBeforeToolCall(
 
 // ==================== PLUGIN EXPORT ====================
 
+/**
+ * Assemble the approval broker (#143) from the main package, or return
+ * undefined.
+ *
+ * Undefined is the normal answer and a safe one: no broker means the guard
+ * behaves exactly as it did before #143 — every dangerous-tier call goes to the
+ * operator. It is returned whenever the broker is not switched on, and whenever
+ * the installed `shieldcortex` build is older than the broker (a version skew
+ * this plugin has to survive, which is why every piece is looked up by name
+ * rather than imported).
+ *
+ * All four pieces are required together. A half-wired broker — a decision core
+ * with no config normaliser, say — would be a policy consuming unvalidated
+ * input, which is the one shape this feature must never take.
+ */
+function resolveBrokerRuntime(
+  defenceMod: any,
+  rawBrokerConfig: Record<string, unknown> | undefined,
+  api: PluginApi,
+): BrokerRuntime | undefined {
+  try {
+    const needed = ['normaliseBrokerConfig', 'brokerDecision', 'runJudge', 'timeoutOutcome'];
+    if (needed.some((fn) => typeof defenceMod?.[fn] !== 'function')) {
+      if (rawBrokerConfig?.enabled === true) {
+        (api.logger as any)?.warn?.('[shieldcortex] approval broker requested but this shieldcortex build does not provide it — every dangerous action still goes to you');
+      }
+      return undefined;
+    }
+    const config = defenceMod.normaliseBrokerConfig(rawBrokerConfig);
+    if (!config?.enabled) return undefined;
+
+    api.logger?.info?.(
+      `[shieldcortex] approval broker ON — judge via the gateway model pool${config.model ? ` (${config.model})` : ''}, pre-clear ${config.allowPreClear ? `at ≥${config.preClearConfidence}` : 'disabled'}`,
+    );
+    return {
+      config,
+      runJudge: defenceMod.runJudge,
+      brokerDecision: defenceMod.brokerDecision,
+      timeoutOutcome: defenceMod.timeoutOutcome,
+      approvalTimeoutMs: typeof defenceMod.approvalTimeoutMs === 'function' ? defenceMod.approvalTimeoutMs : undefined,
+    } as BrokerRuntime;
+  } catch (err) {
+    (api.logger as any)?.warn?.(`[shieldcortex] approval broker unavailable: ${err instanceof Error ? err.message : err} — holding every dangerous action for you`);
+    return undefined;
+  }
+}
+
+export const __testables = { resolveBrokerRuntime };
+
 export default {
   id: PLUGIN_ID,
   name: "ShieldCortex Real-time Scanner",
@@ -1033,6 +1125,7 @@ export default {
     jsonSchema: PLUGIN_CONFIG_JSON_SCHEMA,
   },
 
+
   register(api: PluginApi) {
     if (_registered) return;
     _registered = true;
@@ -1080,6 +1173,7 @@ export default {
           evaluateToolCall: typeof (defenceMod as any).evaluateToolCall === 'function'
             ? ((defenceMod as any).evaluateToolCall as Parameters<typeof createInterceptor>[2] extends { evaluateToolCall?: infer E } ? E : never)
             : undefined,
+          broker: resolveBrokerRuntime(defenceMod, interceptorConfig.actionGuard?.broker, api),
           onAuditEntry: (entry) => syncInterceptEvent(entry, {
             cloudApiKey: (scConfig as any).cloudApiKey ?? '',
             cloudBaseUrl: (scConfig as any).cloudBaseUrl ?? 'https://api.shieldcortex.ai',

package/interceptor.ts

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { mkdirSync, appendFileSync, readFileSync, statSync } from 'node:fs';
 import { join, isAbsolute, resolve as resolvePath } from 'node:path';
 import { homedir } from 'node:os';
+import { createGatewayInvoker, type BrokerInvokerContext, type ModelInvokerLike } from './broker-invoker.js';
 
 export type Severity = 'low' | 'medium' | 'high' | 'critical';
 export type InterceptAction = 'log' | 'warn' | 'require_approval';
@@ -29,6 +30,11 @@ export interface ActionGuardConfig {
   /** Audit recognised (severity 'sensitive'+) allow-decisions. Default true (issue #95).
    *  Benign allows are never audited — on a busy agent every `ls` would drown the stream. */
   auditAllows?: boolean;
+  /** RAW approval-broker config (#143), passed through untouched. It is
+   *  normalised by `normaliseBrokerConfig` in the main package before it reaches
+   *  the broker — this plugin never interprets it, so a hostile value cannot be
+   *  laundered by travelling through here. Absent/disabled = today's behaviour. */
+  broker?: Record<string, unknown>;
 }
 
 /** Structural shape of a Tool Action Guard verdict (kept local to avoid a
@@ -56,6 +62,77 @@ export type ToolGuardEvaluator = (
   options?: ToolGuardEvaluatorOptions,
 ) => ToolGuardVerdictLike;
 
+// ── Approval broker (#143) ──────────────────────────────────────────────────
+// Structurally typed, like ToolGuardVerdictLike above: the real implementations
+// live in `shieldcortex/defence` (approval-broker.ts, approval-judge.ts,
+// broker-config.ts) and are injected at runtime, because this plugin is built
+// across a package boundary and must keep working when the main package is a
+// different version — or absent. No injection = no broker = today's behaviour.
+
+export interface JudgeResultLike {
+  assessment: 'benign' | 'uncertain' | 'malicious';
+  confidence: number;
+  inContext: boolean;
+  injectionSuspected: boolean;
+  rationale?: string;
+}
+
+export interface BrokerAuditLike {
+  outcome: string;
+  tool: string;
+  action: string;
+  severity: string;
+  signals: string[];
+  judgeAssessment: string;
+  judgeConfidence: number | null;
+  injectionSuspected: boolean;
+  inContext: boolean | null;
+  reason: string;
+}
+
+export interface BrokerDecisionLike {
+  outcome: 'not_brokerable' | 'harden' | 'hold' | 'pre_clear';
+  reason: string;
+  canAutoApproveOnTimeout: boolean;
+  audit: BrokerAuditLike;
+}
+
+export interface BrokerConfigLike {
+  enabled: boolean;
+  allowPreClear: boolean;
+  preClearConfidence: number;
+  judgeTimeoutMs: number;
+  approvalTimeoutMs: { sensitive: number; dangerous: number };
+  model?: string;
+}
+
+/** Everything the interceptor needs to run a broker pass, injected as one unit
+ *  so a half-wired broker (a decision core with no judge, say) cannot exist. */
+export interface BrokerRuntime {
+  /** ALREADY normalised by `normaliseBrokerConfig`. The interceptor does not
+   *  sanitise config; it consumes a config that was sanitised at the boundary. */
+  config: BrokerConfigLike;
+  runJudge: (
+    req: {
+      tool: string;
+      toolInput: unknown;
+      verdict: { severity: string; action: string; reason: string; signals: string[] };
+      sessionSummary?: string;
+    },
+    invoke: ModelInvokerLike,
+    opts?: { timeoutMs?: number },
+  ) => Promise<JudgeResultLike | null>;
+  brokerDecision: (input: {
+    tool: string;
+    toolInput: unknown;
+    verdict: ToolGuardVerdictLike;
+    judge: JudgeResultLike | null;
+    policy?: { allowPreClear: boolean; preClearConfidence: number };
+  }) => BrokerDecisionLike;
+  timeoutOutcome: (decision: BrokerDecisionLike) => 'approve' | 'deny';
+  approvalTimeoutMs?: (config: BrokerConfigLike, severity: string) => number;
+}
+
 export interface InterceptorConfig {
   enabled: boolean;
   severityActions: Record<Severity, InterceptAction>;
@@ -68,6 +145,11 @@ export interface ToolCallContext {
   toolName: string;
   arguments: Record<string, unknown>;
   requireApproval?: (message: string) => Promise<boolean>;
+  /** Optional one-shot completion through the gateway's OWN model pool (#143).
+   *  ShieldCortex supplies no credentials of its own; when a gateway build does
+   *  not offer this, the broker has no judge and holds for the operator —
+   *  exactly today's behaviour. See broker-invoker.ts. */
+  invokeModel?: BrokerInvokerContext['invokeModel'];
   /** Working directory the tool call runs in, when the gateway supplies one —
    *  used to resolve a relative script path (issue #4). Falls back to the
    *  call's own `cwd` argument, then `process.cwd()`. */
@@ -89,6 +171,10 @@ export interface InterceptAuditEntry {
   outcome: 'approved' | 'denied' | 'auto_denied' | 'logged' | 'warned' | 'failure_allowed' | 'failure_denied' | 'allowed';
   preview: string;
   ts: string;
+  /** The approval broker's record for this call (#143). Present on exactly the
+   *  calls the broker judged, so "was a model consulted, and what did it say?"
+   *  is answerable from the audit stream alone. Absent = the broker never ran. */
+  broker?: BrokerAuditLike;
 }
 
 const WATCHED_TOOLS = ['remember', 'mcp__memory__remember'] as const;
@@ -323,6 +409,8 @@ const FALLBACK_DANGEROUS_PATTERNS: Array<{ re: RegExp; signal: string }> = [
   { re: /\btruncate\b[^|;&\n]*(?:-s\s*0\b|--size(?:=|\s+)0\b)/i, signal: 'truncate-to-zero' },
   { re: /\bhistory\s+-c\b|\.bash_history|truncate\b[^|\n]*\.log/i, signal: 'wipe-history-or-logs' },
   { 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' },
   { 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' },
@@ -536,6 +624,39 @@ export function createScriptSourceResolver(cwd?: string): (scriptPath: string) =
   };
 }
 
+/** Raised when the operator never answered the approval card (#143). Distinct
+ *  from a transport error, because the two have opposite handling: an error
+ *  routes to failurePolicy, a timeout routes to the broker's asymmetric rule. */
+export class ApprovalTimeout extends Error {
+  constructor(public readonly timeoutMs: number) {
+    super(`no approval answer within ${timeoutMs}ms`);
+    this.name = 'ApprovalTimeout';
+  }
+}
+
+/**
+ * Race an approval against a deadline.
+ *
+ * `timeoutMs <= 0` means no deadline at all — the pre-#143 behaviour, where the
+ * gateway's own card owns the waiting. A deadline is only ever applied when the
+ * broker is in play, and it can only turn an unanswered card into the broker's
+ * timeout rule, which for everything but a pre-cleared call is a denial.
+ */
+export function withApprovalDeadline(approval: Promise<boolean>, timeoutMs: number): Promise<boolean> {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return approval;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  // A card answered after we stopped listening must not surface as an unhandled
+  // rejection in the gateway process.
+  const guarded = approval.catch(err => { throw err; });
+  guarded.catch(() => { /* handled by the race below or deliberately dropped */ });
+  return Promise.race([
+    guarded,
+    new Promise<boolean>((_resolve, reject) => {
+      timer = setTimeout(() => reject(new ApprovalTimeout(timeoutMs)), timeoutMs);
+    }),
+  ]).finally(() => { if (timer) clearTimeout(timer); });
+}
+
 /** The cwd a tool call runs in, if the gateway or the call itself names one. */
 function toolCallCwd(context: ToolCallContext): string | undefined {
   if (typeof context.cwd === 'string' && context.cwd) return context.cwd;
@@ -551,8 +672,24 @@ interface InterceptorOptions {
   onAuditEntry?: (entry: InterceptAuditEntry) => void;
   /** Tool Action Guard evaluator, injected from `shieldcortex/defence` at runtime. */
   evaluateToolCall?: ToolGuardEvaluator;
+  /** 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. */
+  broker?: BrokerRuntime;
+  /** Judge calls allowed per minute. The judge spends the OPERATOR's own rate
+   *  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;
 }
 
+/** How many recent tool NAMES the judge is told about. Names only, never
+ *  arguments — see buildSessionSummary. */
+const SESSION_TOOL_MEMORY = 12;
+/** Tool names are registry-supplied, not free text, but an MCP server can name
+ *  a tool anything at all — so they are reduced to an identifier shape before
+ *  being placed anywhere near a prompt. */
+const TOOL_NAME_SAFE = /[^A-Za-z0-9_.:-]/g;
+
 export function createInterceptor(
   config: InterceptorConfig,
   pipeline: PipelineRunner,
@@ -567,6 +704,13 @@ export function createInterceptor(
   const onAuditEntry = options?.onAuditEntry;
   const actionGuardCfg: ActionGuardConfig = config.actionGuard ?? { enabled: true, enforce: true, autoApprove: [] };
   const evaluateToolCall = options?.evaluateToolCall;
+  const broker = options?.broker;
+  // The judge rides the operator's own model pool, so its calls are their cost
+  // and their rate limit. Bounded per minute, and running out means "no judge",
+  // which the decision core reads as "hold for the human" — never as an allow.
+  const judgeLimiter = new RateLimiter(options?.maxJudgeCallsPerMinute ?? 20);
+  /** Bare tool names seen this session, newest last. See buildSessionSummary. */
+  const recentTools: string[] = [];
 
   function emitAudit(entry: InterceptAuditEntry): void {
     writeAuditEntry(entry);
@@ -584,6 +728,100 @@ export function createInterceptor(
     };
   }
 
+  // ── Approval broker (#143) ────────────────────────────────────────────────
+
+  /**
+   * The ONLY thing the judge is told about the session.
+   *
+   * The design's third open question was "what does the broker see of the
+   * session, and how do we stop *that* being the injection vector?" — a
+   * poisoned transcript arguing its own approval is the obvious attack. The
+   * answer here is the narrowest thing that still means anything: a list of
+   * bare tool NAMES, sanitised to an identifier shape. No arguments, no
+   * content, no memory text, no user or assistant turns.
+   *
+   * That is enough for "does this action fit what the session was doing?" —
+   * an `npm install` in a session of Read/Edit/Bash is in pattern; the same
+   * command as the first act of a session is not — and it carries no attacker
+   * prose, because there is nowhere in it for prose to live.
+   */
+  function buildSessionSummary(): string | undefined {
+    if (recentTools.length === 0) return undefined;
+    const names = [...new Set(recentTools)].join(', ');
+    return `tools used in this session so far (names only, no arguments): ${names}`;
+  }
+
+  function noteToolForSession(toolName: string): void {
+    const safe = String(toolName ?? '').replace(TOOL_NAME_SAFE, '').slice(0, 60);
+    if (!safe) return;
+    recentTools.push(safe);
+    if (recentTools.length > SESSION_TOOL_MEMORY) recentTools.shift();
+  }
+
+  /**
+   * One broker pass over a dangerous-tier verdict.
+   *
+   * Returns null when the broker is not in play at all — no runtime injected,
+   * or disabled by config — and the caller then behaves exactly as it did
+   * before #143. Every *failure* inside a pass (no model seam, pool down, junk
+   * reply, budget spent, core throwing) resolves to a decision of `hold` or to
+   * null, both of which route to the operator. There is no path here that
+   * produces an allow the guard would not otherwise have produced.
+   */
+  async function runBroker(context: ToolCallContext, v: ToolGuardVerdictLike): Promise<BrokerDecisionLike | null> {
+    if (!broker || broker.config?.enabled !== true) return null;
+
+    try {
+      // No seam on this gateway build → no invoker → no judge. Not an error:
+      // it is the honest state of every gateway shipping today.
+      const invoke = createGatewayInvoker(context as BrokerInvokerContext, {
+        model: broker.config.model,
+        timeoutMs: broker.config.judgeTimeoutMs,
+      });
+
+      let judge: JudgeResultLike | null = null;
+      if (invoke && judgeLimiter.shouldAllow()) {
+        judge = await broker.runJudge(
+          {
+            tool: context.toolName,
+            toolInput: context.arguments,
+            verdict: { severity: v.severity, action: v.action, reason: v.reason, signals: v.signals },
+            sessionSummary: buildSessionSummary(),
+          },
+          invoke,
+          { timeoutMs: broker.config.judgeTimeoutMs },
+        );
+      } else if (invoke) {
+        log.warn(`[shieldcortex] approval broker: judge budget spent this minute — holding ${context.toolName} for the operator`);
+      }
+
+      const decision = broker.brokerDecision({
+        tool: context.toolName,
+        toolInput: context.arguments,
+        verdict: v,
+        judge,
+        policy: {
+          allowPreClear: broker.config.allowPreClear,
+          preClearConfidence: broker.config.preClearConfidence,
+        },
+      });
+      // A decision we cannot read is not a decision. Falling back to null puts
+      // the call on the pre-#143 path, which asks the human.
+      if (!decision || typeof decision.outcome !== 'string') return null;
+      return decision;
+    } catch (err) {
+      log.warn(`[shieldcortex] ⚠️ approval broker error: ${err instanceof Error ? err.message : err} — holding for the operator`);
+      return null;
+    }
+  }
+
+  /** How long to wait for a human once the broker is in play. */
+  function brokerApprovalTimeoutMs(severity: string): number {
+    if (!broker) return 0;
+    if (typeof broker.approvalTimeoutMs === 'function') return broker.approvalTimeoutMs(broker.config, severity);
+    return Math.min(broker.config.approvalTimeoutMs.sensitive, broker.config.approvalTimeoutMs.dangerous);
+  }
+
   // WS2 fail-closed path (issue #59): when the real guard was never wired in or
   // throws, run the dependency-free fallback scan. Three tiers, so no dangerous
   // op is ever silently allowed on a scan failure — and every could-not-scan
@@ -713,14 +951,49 @@ export function createInterceptor(
       return;
     }
 
+    // ── AI-assisted approval broker (#143) ──────────────────────────────────
+    // Sits between the guard's verdict and the human, and can only move the
+    // answer toward caution. Off by default; when off, `brokered` is null and
+    // everything below is the pre-#143 code path unchanged.
+    const brokered = await runBroker(context, v);
+    // Every downstream audit row for a brokered call carries the broker's own
+    // record alongside the guard's, so one row answers "was a model consulted,
+    // what did it say, and what did that change?".
+    const auditBase = brokered ? { ...base, broker: brokered.audit } : base;
+
+    if (brokered?.outcome === 'harden') {
+      // The judge found something the rules did not. Deny outright rather than
+      // offer the operator a button to be socially-engineered into tapping.
+      emitAudit({ ...auditBase, action: 'require_approval', outcome: 'auto_denied' });
+      log.warn(`[shieldcortex] approval broker HARDENED ${context.toolName} to a denial: ${brokered.reason}`);
+      throw new Error(`ShieldCortex: tool call blocked — ${brokered.reason}`);
+    }
+
+    if (brokered?.outcome === 'pre_clear') {
+      // Reversible, on-host, in-context, judge-confident: proceed without
+      // waiting. Loud on purpose — a release nobody approved must never be a
+      // silent one, because the audit row is the only thing that will ever tell
+      // the operator it happened.
+      emitAudit({ ...auditBase, action: 'require_approval', outcome: 'approved' });
+      log.warn(`[shieldcortex] approval broker PRE-CLEARED ${context.toolName} without waiting for the operator: ${brokered.reason} [${v.signals.join(', ')}]`);
+      return;
+    }
+
     if (typeof context.requireApproval !== 'function') {
       // Unattended (no approver, e.g. cron/heartbeat): fail closed on the failure
       // policy. High-severity dangerous defaults to deny — surfaced loudly to the
       // gateway log so an operator sees it, because a silent no-op is exactly the
       // failure mode we are eliminating.
+      //
+      // With the broker in play this can only get STRICTER: no approver is the
+      // timeout case by definition, and `timeoutOutcome` answers 'approve' only
+      // for a pre-cleared call, which already returned above. So a brokered call
+      // that reaches here denies even where failurePolicy would have allowed.
       const failAction = config.failurePolicy[severity];
-      emitAudit({ ...base, action: 'require_approval', outcome: failAction === 'deny' ? 'failure_denied' : 'failure_allowed' });
-      if (failAction === 'deny') {
+      const brokerDenies = brokered ? broker!.timeoutOutcome(brokered) === 'deny' : false;
+      const deny = failAction === 'deny' || brokerDenies;
+      emitAudit({ ...auditBase, action: 'require_approval', outcome: deny ? 'failure_denied' : 'failure_allowed' });
+      if (deny) {
         log.warn(`[shieldcortex] action-guard DENIED (unattended, no approver) ${context.toolName}: ${v.reason} [${v.signals.join(", ")}]`);
         throw new Error(`ShieldCortex: tool call blocked — ${v.reason} (no approver, failure policy: deny)`);
       }
@@ -728,17 +1001,34 @@ export function createInterceptor(
     }
 
     if (!rateLimiter.shouldAllow()) {
-      emitAudit({ ...base, action: 'rate_limit', outcome: 'auto_denied' });
+      emitAudit({ ...auditBase, action: 'rate_limit', outcome: 'auto_denied' });
       throw new Error('ShieldCortex: tool call auto-denied (approval rate limit exceeded)');
     }
 
     let approved: boolean;
     try {
-      approved = await context.requireApproval(formatActionGuardPrompt(context.toolName, v));
+      approved = await withApprovalDeadline(
+        context.requireApproval(formatActionGuardPrompt(context.toolName, v)),
+        brokered ? brokerApprovalTimeoutMs(v.severity) : 0,
+      );
     } catch (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
+        // in practice this is always a deny. It reads the broker's own derived
+        // flag rather than re-deriving its own idea of what is safe.
+        const outcome = broker!.timeoutOutcome(brokered);
+        emitAudit({ ...auditBase, action: 'require_approval', outcome: outcome === 'approve' ? 'approved' : 'auto_denied' });
+        if (outcome === 'approve') {
+          log.warn(`[shieldcortex] approval broker: no answer in ${err.timeoutMs}ms — auto-approving pre-cleared ${context.toolName}`);
+          return;
+        }
+        log.warn(`[shieldcortex] approval broker: no answer in ${err.timeoutMs}ms — DENYING ${context.toolName} (fail-closed)`);
+        throw new Error(`ShieldCortex: tool call blocked — no answer from the operator within ${err.timeoutMs}ms (fail-closed)`);
+      }
       const failAction = config.failurePolicy[severity];
       log.warn(`[shieldcortex] ⚠️ requireApproval error: ${err instanceof Error ? err.message : err} — failure policy: ${failAction}`);
-      emitAudit({ ...base, action: 'require_approval', outcome: failAction === 'deny' ? 'failure_denied' : 'failure_allowed' });
+      emitAudit({ ...auditBase, action: 'require_approval', outcome: failAction === 'deny' ? 'failure_denied' : 'failure_allowed' });
       if (failAction === 'deny') {
         throw new Error('ShieldCortex: tool call blocked — approval error, failure policy: deny');
       }
@@ -746,14 +1036,18 @@ export function createInterceptor(
     }
 
     if (approved) {
-      emitAudit({ ...base, action: 'require_approval', outcome: 'approved' });
+      emitAudit({ ...auditBase, action: 'require_approval', outcome: 'approved' });
       return;
     }
-    emitAudit({ ...base, action: 'require_approval', outcome: 'denied' });
+    emitAudit({ ...auditBase, action: 'require_approval', outcome: 'denied' });
     throw new Error('ShieldCortex: tool call denied by user');
   }
 
   async function handleToolCall(context: ToolCallContext): Promise<void> {
+    // 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);
+
     // Non-memory tools go through the Action Guard (what the agent DOES); the
     // memory-write tools continue through the content defence pipeline below.
     if (!(WATCHED_TOOLS as readonly string[]).includes(context.toolName)) {

package/openclaw.plugin.json

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