openclaw-safeclaw-plugin 1.4.0 → 1.5.0

package/dist/index.js

@@ -97,8 +97,19 @@ async function get(path) {
         return null;
     }
 }
+function approvalSeverityForRisk(riskLevel) {
+    if (riskLevel === 'CriticalRisk' || riskLevel === 'HighRisk')
+        return 'critical';
+    if (riskLevel === 'MediumRisk')
+        return 'warning';
+    return 'info';
+}
+function approvalTimeoutBehaviorForRisk(riskLevel) {
+    return riskLevel === 'CriticalRisk' || riskLevel === 'HighRisk' ? 'deny' : 'allow';
+}
 // --- Plugin Definition ---
 let handshakeCompleted = false;
+let lastHandshakeConfigHash = '';
 async function performHandshake() {
     const cfg = getConfig();
     if (!cfg.apiKey) {
@@ -115,6 +126,7 @@ async function performHandshake() {
     }
     log.info(`[SafeClaw] Handshake OK — org=${r.orgId}, scope=${r.scope}, engine=${r.engineReady ? 'ready' : 'not ready'}`);
     handshakeCompleted = true;
+    lastHandshakeConfigHash = configHash(getConfig());
     return true;
 }
 async function checkConnection() {
@@ -160,9 +172,15 @@ export default {
         // Heartbeat watchdog — send config hash to service every 30s
         const sendHeartbeat = async () => {
             try {
+                const currentHash = configHash(getConfig());
+                if (handshakeCompleted && currentHash !== lastHandshakeConfigHash) {
+                    log.info('[SafeClaw] Config changed — re-authenticating');
+                    handshakeCompleted = false;
+                    performHandshake().catch(() => { });
+                }
                 await post('/heartbeat', {
                     agentId: instanceId,
-                    configHash: configHash(getConfig()),
+                    configHash: currentHash,
                     status: 'alive',
                 });
             }
@@ -237,6 +255,19 @@ export default {
             else if (r === null && cfg.failMode === 'closed' && cfg.enforcement === 'audit-only') {
                 log.warn(`[SafeClaw] Service unavailable at ${cfg.serviceUrl} (fail-closed mode, audit-only)`);
             }
+            // If service says confirmation required, use OpenClaw's native approval flow
+            if (r?.confirmationRequired) {
+                const riskLevel = r.riskLevel || '';
+                return {
+                    requireApproval: {
+                        title: 'SafeClaw Governance Check',
+                        description: r.reason || 'This action requires confirmation',
+                        severity: approvalSeverityForRisk(riskLevel),
+                        timeoutMs: 30_000,
+                        timeoutBehavior: approvalTimeoutBehaviorForRisk(riskLevel),
+                    },
+                };
+            }
             if (r?.block) {
                 const blockReason = r.reason || 'Blocked by SafeClaw (no reason provided)';
                 if (cfg.enforcement === 'enforce') {
@@ -300,7 +331,7 @@ export default {
                 content: event.prompt ?? '',
                 provider: event.provider ?? '',
                 model: event.model ?? '',
-            }).catch(() => { });
+            }).catch((e) => log.warn('[SafeClaw] Failed to log LLM input:', e));
         });
         api.on('llm_output', (event, ctx) => {
             post('/log/llm-output', {
@@ -309,33 +340,35 @@ export default {
                 provider: event.provider ?? '',
                 model: event.model ?? '',
                 usage: event.usage ?? {},
-            }).catch(() => { });
+            }).catch((e) => log.warn('[SafeClaw] Failed to log LLM output:', e));
         });
         // (#195: use event.toolName, !event.error for success, add durationMs and error)
         api.on('after_tool_call', (event, ctx) => {
             post('/record/tool-result', {
                 sessionId: ctx.sessionId ?? event.sessionId ?? '',
+                userId: ctx.agentId ?? '',
                 toolName: event.toolName ?? '',
                 params: event.params ?? {},
                 result: event.result ?? '',
                 success: !event.error,
                 error: event.error ? String(event.error) : '',
                 durationMs: event.durationMs ?? 0,
+                runId: ctx.runId ?? event.runId ?? '',
             }).catch((e) => log.warn('[SafeClaw] Failed to record tool result:', e));
         });
         // Subagent governance — block delegation bypass attempts (#188)
         api.on('subagent_spawning', async (event, ctx) => {
             const cfg = getConfig();
             const r = await post('/evaluate/subagent-spawn', {
-                sessionId: ctx.sessionId ?? event.sessionId,
-                userId: ctx.agentId,
+                sessionId: ctx.sessionId ?? event.sessionId ?? '',
+                userId: ctx.agentId ?? '',
                 parentAgentId: event.parentAgentId,
                 childConfig: event.childConfig ?? {},
                 reason: event.reason ?? '',
             });
             // Fail-closed handling (matches before_tool_call / message_sending pattern)
             if (r === null && cfg.failMode === 'closed' && cfg.enforcement === 'enforce') {
-                throw new Error('SafeClaw service unavailable (fail-closed mode)');
+                return { status: 'error', error: 'SafeClaw service unavailable (fail-closed mode)' };
             }
             else if (r === null && cfg.failMode === 'closed' && cfg.enforcement === 'warn-only') {
                 log.warn('[SafeClaw] Service unavailable (fail-closed mode, warn-only)');
@@ -344,7 +377,7 @@ export default {
                 log.warn('[SafeClaw] Service unavailable (fail-closed mode, audit-only)');
             }
             if (r?.block && cfg.enforcement === 'enforce') {
-                throw new Error(r.reason || 'Blocked by SafeClaw: delegation bypass detected');
+                return { status: 'error', error: r.reason || 'Blocked by SafeClaw: delegation bypass detected' };
             }
             if (r?.block && cfg.enforcement === 'warn-only') {
                 log.warn(`[SafeClaw] Subagent spawn warning: ${r.reason}`);
@@ -353,38 +386,38 @@ export default {
         // Subagent ended — record child agent lifecycle (#188)
         api.on('subagent_ended', (event, ctx) => {
             post('/record/subagent-ended', {
-                sessionId: ctx.sessionId ?? event.sessionId,
+                sessionId: ctx.sessionId ?? event.sessionId ?? '',
                 parentAgentId: event.parentAgentId,
                 childAgentId: event.childAgentId,
-            }).catch(() => { });
+            }).catch((e) => log.warn('[SafeClaw] Failed to record subagent ended:', e));
         });
         // Session lifecycle — notify service of session start (#189)
         api.on('session_start', (event, ctx) => {
             post('/session/start', {
-                sessionId: ctx.sessionId ?? event.sessionId,
-                userId: ctx.agentId,
+                sessionId: ctx.sessionId ?? event.sessionId ?? '',
+                userId: ctx.agentId ?? '',
                 agentId: instanceId,
                 metadata: event.metadata ?? {},
-            }).catch(() => { });
+            }).catch((e) => log.warn('[SafeClaw] Failed to record session start:', e));
         });
         // Session lifecycle — notify service of session end (#189)
         api.on('session_end', (event, ctx) => {
             post('/session/end', {
-                sessionId: ctx.sessionId ?? event.sessionId,
-                userId: ctx.agentId,
+                sessionId: ctx.sessionId ?? event.sessionId ?? '',
+                userId: ctx.agentId ?? '',
                 agentId: instanceId,
-            }).catch(() => { });
+            }).catch((e) => log.warn('[SafeClaw] Failed to record session end:', e));
         });
         // Inbound message governance — evaluate received messages (#190)
         api.on('message_received', (event, ctx) => {
             post('/evaluate/inbound-message', {
-                sessionId: ctx.sessionId ?? event.sessionId,
-                userId: ctx.agentId,
+                sessionId: ctx.sessionId ?? event.sessionId ?? '',
+                userId: ctx.agentId ?? '',
                 channel: event.channel ?? ctx.channelId ?? '',
                 sender: event.sender ?? '',
                 content: event.content ?? '',
                 metadata: event.metadata ?? {},
-            }).catch(() => { });
+            }).catch((e) => log.warn('[SafeClaw] Failed to evaluate inbound message:', e));
         });
         // Agent tools — let agents introspect governance state (#197)
         if (api.registerTool) {

package/dist/tui/config.js

@@ -5,7 +5,7 @@
  * Reads ~/.safeclaw/config.json, applies env-var overrides,
  * and exposes helpers for saving and hashing config state.
  */
-import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
+import { readFileSync, existsSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
 import { join, dirname } from 'path';
 import { homedir } from 'os';
 import crypto from 'crypto';
@@ -167,6 +167,10 @@ export function saveConfig(config) {
     mkdirSync(dirname(CONFIG_PATH), { recursive: true, mode: 0o700 });
     try {
         writeFileSync(CONFIG_PATH, JSON.stringify(existing, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+        try {
+            chmodSync(CONFIG_PATH, 0o600);
+        }
+        catch { /* best-effort */ }
     }
     catch (e) {
         const code = e.code;
@@ -189,6 +193,7 @@ export function configHash(config) {
         enforcement: config.enforcement,
         failMode: config.failMode,
         serviceUrl: config.serviceUrl,
+        apiKeyFingerprint: config.apiKey ? config.apiKey.slice(0, 4) + config.apiKey.slice(-4) : '',
     });
     return crypto.createHash('sha256').update(payload).digest('hex');
 }

package/index.ts

@@ -7,7 +7,7 @@
  * to the SafeClaw service and acts on the responses.
  */
 
-import type { OpenClawPluginApi, OpenClawPluginEvent, OpenClawPluginContext } from 'openclaw/plugin-sdk/core';
+import type { OpenClawPluginApi, OpenClawPluginEvent, OpenClawPluginContext, BeforeToolCallResult } from 'openclaw/plugin-sdk/core';
 import { loadConfig, configHash } from './tui/config.js';
 import crypto from 'crypto';
 import { createRequire } from 'module';
@@ -104,9 +104,20 @@ async function get(path: string): Promise<Record<string, unknown> | null> {
   }
 }
 
+function approvalSeverityForRisk(riskLevel: string): 'info' | 'warning' | 'critical' {
+  if (riskLevel === 'CriticalRisk' || riskLevel === 'HighRisk') return 'critical';
+  if (riskLevel === 'MediumRisk') return 'warning';
+  return 'info';
+}
+
+function approvalTimeoutBehaviorForRisk(riskLevel: string): 'allow' | 'deny' {
+  return riskLevel === 'CriticalRisk' || riskLevel === 'HighRisk' ? 'deny' : 'allow';
+}
+
 // --- Plugin Definition ---
 
 let handshakeCompleted = false;
+let lastHandshakeConfigHash = '';
 
 async function performHandshake(): Promise<boolean> {
   const cfg = getConfig();
@@ -127,6 +138,7 @@ async function performHandshake(): Promise<boolean> {
 
   log.info(`[SafeClaw] Handshake OK — org=${r.orgId}, scope=${r.scope}, engine=${r.engineReady ? 'ready' : 'not ready'}`);
   handshakeCompleted = true;
+  lastHandshakeConfigHash = configHash(getConfig());
   return true;
 }
 
@@ -176,9 +188,15 @@ export default {
     // Heartbeat watchdog — send config hash to service every 30s
     const sendHeartbeat = async () => {
       try {
+        const currentHash = configHash(getConfig());
+        if (handshakeCompleted && currentHash !== lastHandshakeConfigHash) {
+          log.info('[SafeClaw] Config changed — re-authenticating');
+          handshakeCompleted = false;
+          performHandshake().catch(() => {});
+        }
         await post('/heartbeat', {
           agentId: instanceId,
-          configHash: configHash(getConfig()),
+          configHash: currentHash,
           status: 'alive',
         });
       } catch {
@@ -254,6 +272,21 @@ export default {
       } else if (r === null && cfg.failMode === 'closed' && cfg.enforcement === 'audit-only') {
         log.warn(`[SafeClaw] Service unavailable at ${cfg.serviceUrl} (fail-closed mode, audit-only)`);
       }
+
+      // If service says confirmation required, use OpenClaw's native approval flow
+      if (r?.confirmationRequired) {
+        const riskLevel = (r.riskLevel as string) || '';
+        return {
+          requireApproval: {
+            title: 'SafeClaw Governance Check',
+            description: (r.reason as string) || 'This action requires confirmation',
+            severity: approvalSeverityForRisk(riskLevel),
+            timeoutMs: 30_000,
+            timeoutBehavior: approvalTimeoutBehaviorForRisk(riskLevel),
+          },
+        } satisfies BeforeToolCallResult;
+      }
+
       if (r?.block) {
         const blockReason = (r.reason as string) || 'Blocked by SafeClaw (no reason provided)';
         if (cfg.enforcement === 'enforce') {
@@ -320,7 +353,7 @@ export default {
         content: event.prompt ?? '',
         provider: event.provider ?? '',
         model: event.model ?? '',
-      }).catch(() => {});
+      }).catch((e) => log.warn('[SafeClaw] Failed to log LLM input:', e));
     });
 
     api.on('llm_output', (event: OpenClawPluginEvent, ctx: OpenClawPluginContext) => {
@@ -330,19 +363,21 @@ export default {
         provider: event.provider ?? '',
         model: event.model ?? '',
         usage: event.usage ?? {},
-      }).catch(() => {});
+      }).catch((e) => log.warn('[SafeClaw] Failed to log LLM output:', e));
     });
 
     // (#195: use event.toolName, !event.error for success, add durationMs and error)
     api.on('after_tool_call', (event: OpenClawPluginEvent, ctx: OpenClawPluginContext) => {
       post('/record/tool-result', {
         sessionId: ctx.sessionId ?? event.sessionId ?? '',
+        userId: ctx.agentId ?? '',
         toolName: event.toolName ?? '',
         params: event.params ?? {},
         result: event.result ?? '',
         success: !event.error,
         error: event.error ? String(event.error) : '',
         durationMs: event.durationMs ?? 0,
+        runId: ctx.runId ?? event.runId ?? '',
       }).catch((e) => log.warn('[SafeClaw] Failed to record tool result:', e));
     });
 
@@ -350,8 +385,8 @@ export default {
     api.on('subagent_spawning', async (event: OpenClawPluginEvent, ctx: OpenClawPluginContext) => {
       const cfg = getConfig();
       const r = await post('/evaluate/subagent-spawn', {
-        sessionId: ctx.sessionId ?? event.sessionId,
-        userId: ctx.agentId,
+        sessionId: ctx.sessionId ?? event.sessionId ?? '',
+        userId: ctx.agentId ?? '',
         parentAgentId: event.parentAgentId,
         childConfig: event.childConfig ?? {},
         reason: event.reason ?? '',
@@ -359,7 +394,7 @@ export default {
 
       // Fail-closed handling (matches before_tool_call / message_sending pattern)
       if (r === null && cfg.failMode === 'closed' && cfg.enforcement === 'enforce') {
-        throw new Error('SafeClaw service unavailable (fail-closed mode)');
+        return { status: 'error', error: 'SafeClaw service unavailable (fail-closed mode)' };
       } else if (r === null && cfg.failMode === 'closed' && cfg.enforcement === 'warn-only') {
         log.warn('[SafeClaw] Service unavailable (fail-closed mode, warn-only)');
       } else if (r === null && cfg.failMode === 'closed' && cfg.enforcement === 'audit-only') {
@@ -367,7 +402,7 @@ export default {
       }
 
       if (r?.block && cfg.enforcement === 'enforce') {
-        throw new Error((r.reason as string) || 'Blocked by SafeClaw: delegation bypass detected');
+        return { status: 'error', error: (r.reason as string) || 'Blocked by SafeClaw: delegation bypass detected' };
       }
       if (r?.block && cfg.enforcement === 'warn-only') {
         log.warn(`[SafeClaw] Subagent spawn warning: ${r.reason}`);
@@ -377,41 +412,41 @@ export default {
     // Subagent ended — record child agent lifecycle (#188)
     api.on('subagent_ended', (event: OpenClawPluginEvent, ctx: OpenClawPluginContext) => {
       post('/record/subagent-ended', {
-        sessionId: ctx.sessionId ?? event.sessionId,
+        sessionId: ctx.sessionId ?? event.sessionId ?? '',
         parentAgentId: event.parentAgentId,
         childAgentId: event.childAgentId,
-      }).catch(() => {});
+      }).catch((e) => log.warn('[SafeClaw] Failed to record subagent ended:', e));
     });
 
     // Session lifecycle — notify service of session start (#189)
     api.on('session_start', (event: OpenClawPluginEvent, ctx: OpenClawPluginContext) => {
       post('/session/start', {
-        sessionId: ctx.sessionId ?? event.sessionId,
-        userId: ctx.agentId,
+        sessionId: ctx.sessionId ?? event.sessionId ?? '',
+        userId: ctx.agentId ?? '',
         agentId: instanceId,
         metadata: event.metadata ?? {},
-      }).catch(() => {});
+      }).catch((e) => log.warn('[SafeClaw] Failed to record session start:', e));
     });
 
     // Session lifecycle — notify service of session end (#189)
     api.on('session_end', (event: OpenClawPluginEvent, ctx: OpenClawPluginContext) => {
       post('/session/end', {
-        sessionId: ctx.sessionId ?? event.sessionId,
-        userId: ctx.agentId,
+        sessionId: ctx.sessionId ?? event.sessionId ?? '',
+        userId: ctx.agentId ?? '',
         agentId: instanceId,
-      }).catch(() => {});
+      }).catch((e) => log.warn('[SafeClaw] Failed to record session end:', e));
     });
 
     // Inbound message governance — evaluate received messages (#190)
     api.on('message_received', (event: OpenClawPluginEvent, ctx: OpenClawPluginContext) => {
       post('/evaluate/inbound-message', {
-        sessionId: ctx.sessionId ?? event.sessionId,
-        userId: ctx.agentId,
+        sessionId: ctx.sessionId ?? event.sessionId ?? '',
+        userId: ctx.agentId ?? '',
         channel: event.channel ?? (ctx as any).channelId ?? '',
         sender: event.sender ?? '',
         content: event.content ?? '',
         metadata: event.metadata ?? {},
-      }).catch(() => {});
+      }).catch((e) => log.warn('[SafeClaw] Failed to evaluate inbound message:', e));
     });
 
     // Agent tools — let agents introspect governance state (#197)

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "safeclaw",
   "name": "SafeClaw Neurosymbolic Governance",
   "description": "Validates AI agent actions against OWL ontologies and SHACL constraints before execution",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "author": "Tendly EU",
   "license": "MIT",
   "homepage": "https://safeclaw.eu",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-safeclaw-plugin",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "SafeClaw Neurosymbolic Governance plugin for OpenClaw — validates AI agent actions against OWL ontologies and SHACL constraints",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/tui/config.ts

@@ -6,7 +6,7 @@
  * and exposes helpers for saving and hashing config state.
  */
 
-import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
+import { readFileSync, existsSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
 import { join, dirname } from 'path';
 import { homedir } from 'os';
 import crypto from 'crypto';
@@ -181,6 +181,7 @@ export function saveConfig(config: SafeClawConfig): void {
 
   try {
     writeFileSync(CONFIG_PATH, JSON.stringify(existing, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+    try { chmodSync(CONFIG_PATH, 0o600); } catch { /* best-effort */ }
   } catch (e) {
     const code = (e as NodeJS.ErrnoException).code;
     if (code === 'EROFS') {
@@ -203,6 +204,7 @@ export function configHash(config: SafeClawConfig): string {
     enforcement: config.enforcement,
     failMode: config.failMode,
     serviceUrl: config.serviceUrl,
+    apiKeyFingerprint: config.apiKey ? config.apiKey.slice(0, 4) + config.apiKey.slice(-4) : '',
   });
   return crypto.createHash('sha256').update(payload).digest('hex');
 }

package/types/openclaw-sdk.d.ts

@@ -1,11 +1,17 @@
 /**
  * Ambient type declarations for OpenClaw Plugin SDK.
- * These match the types exported by openclaw/plugin-sdk as of v2026.3.
+ * These match the types exported by openclaw/plugin-sdk as of v2026.4.
  * When installed inside OpenClaw, the real SDK types take precedence.
  */
 
 declare module 'openclaw/plugin-sdk/core' {
   export interface OpenClawPluginApi {
+    /**
+     * Register a hook handler for OpenClaw lifecycle events.
+     *
+     * @deprecated The `before_agent_start` hook is deprecated in v2026.4.
+     * Use `before_model_resolve` + `before_prompt_build` instead.
+     */
     on(
       hookName: string,
       handler: (event: OpenClawPluginEvent, ctx: OpenClawPluginContext) => Promise<Record<string, unknown> | void> | void,
@@ -33,6 +39,9 @@ declare module 'openclaw/plugin-sdk/core' {
     model?: string;
     lastAssistant?: string;
     usage?: Record<string, unknown>;
+    runId?: string;
+    toolCallId?: string;
+    childAgentId?: string;
     parentAgentId?: string;
     childConfig?: Record<string, unknown>;
     reason?: string;
@@ -66,6 +75,32 @@ declare module 'openclaw/plugin-sdk/core' {
     execute: (params: Record<string, unknown>, ctx: Record<string, unknown>) => Promise<unknown>;
   }
 
+  export interface PluginApprovalRequest {
+    title: string;
+    description: string;
+    severity?: 'info' | 'warning' | 'critical';
+    timeoutMs?: number;
+    timeoutBehavior?: 'allow' | 'deny';
+    pluginId?: string;
+    onResolution?: (decision: PluginApprovalResolution) => Promise<void> | void;
+  }
+
+  export interface PluginApprovalResolution {
+    approved: boolean;
+    resolvedBy?: string;
+    resolvedAt?: string;
+  }
+
+  /**
+   * Hook result types for before_tool_call.
+   * Return one of: nothing (allow), { block, blockReason }, or { requireApproval }.
+   */
+  export interface BeforeToolCallResult {
+    block?: boolean;
+    blockReason?: string;
+    requireApproval?: PluginApprovalRequest;
+  }
+
   export interface OpenClawPluginLogger {
     info: (...args: unknown[]) => void;
     warn: (...args: unknown[]) => void;