openclaw-safeclaw-plugin 1.5.0 → 2.0.0

package/README.md

@@ -130,7 +130,7 @@ The plugin registers 11 hooks on OpenClaw events. Each hook communicates with th
 |------|----------|-------------|
 | `before_tool_call` | 100 | The main gate. Evaluates every tool call against SHACL shapes, policies, preferences, and dependencies. Returns `{ block: true }` if the action violates constraints. |
 | `message_sending` | 100 | Checks outbound messages for sensitive data leaks, contact rule violations, and content policy. Returns `{ cancel: true }` to block. |
-| `subagent_spawning` | 100 | Evaluates child agent spawn requests. Detects delegation bypass attempts where a blocked parent tries to spawn an unrestricted child. |
+| `subagent_spawning` | 100 | Forwards child-spawn requests (parent/child session keys, child agent id) to the service. **Note:** under OpenClaw v2026.6.8 this hook exposes only session keys — no parent agent id — so spawn-time delegation-bypass *enforcement* is deferred to the session-keyed hierarchy work (#321); today this hook is observational. Child tool calls are still gated individually by `before_tool_call`. |
 
 ### Context hooks (modify agent behavior)
 
@@ -150,6 +150,16 @@ The plugin registers 11 hooks on OpenClaw events. Each hook communicates with th
 | `session_end` | Notifies the service when a session ends. |
 | `message_received` | Evaluates inbound messages for governance (sender, channel, content). |
 
+> **Required for LLM audit logging.** As of OpenClaw v2026.6.8, raw-conversation
+> hooks (`llm_input`, `llm_output`, and the `before_agent_*` family) only fire for
+> non-bundled plugins when conversation access is explicitly granted. Without it,
+> SafeClaw's LLM I/O audit trail is silently empty. Enable it in your OpenClaw
+> config:
+>
+> ```json
+> { "plugins": { "entries": { "safeclaw": { "hooks": { "allowConversationAccess": true } } } } }
+> ```
+
 ## Agent Tools
 
 The plugin registers two tools that agents can call to introspect governance state.

package/dist/index.js

@@ -107,6 +107,13 @@ function approvalSeverityForRisk(riskLevel) {
 function approvalTimeoutBehaviorForRisk(riskLevel) {
     return riskLevel === 'CriticalRisk' || riskLevel === 'HighRisk' ? 'deny' : 'allow';
 }
+// For high-risk actions, forbid durable "allow-always" trust — the user may only
+// approve this one occurrence or deny (#314). Lower-risk actions keep all options.
+function approvalAllowedDecisionsForRisk(riskLevel) {
+    return riskLevel === 'CriticalRisk' || riskLevel === 'HighRisk'
+        ? ['allow-once', 'deny']
+        : ['allow-once', 'allow-always', 'deny'];
+}
 // --- Plugin Definition ---
 let handshakeCompleted = false;
 let lastHandshakeConfigHash = '';
@@ -240,11 +247,19 @@ export default {
                 return { block: true, blockReason: 'SafeClaw handshake not completed (fail-closed)' };
             }
             const r = await post('/evaluate/tool-call', {
-                sessionId: ctx.sessionId ?? event.sessionId ?? '',
+                sessionId: ctx.sessionKey ?? ctx.sessionId ?? event.sessionId ?? '',
                 userId: ctx.agentId ?? '',
                 toolName: event.toolName ?? '',
                 params: event.params ?? {},
                 runId: ctx.runId ?? '',
+                // v2026.6.8 discriminators so the service can classify code-mode exec,
+                // file-touching envelopes, etc. (#316)
+                toolKind: event.toolKind ?? '',
+                toolInputKind: event.toolInputKind ?? '',
+                derivedPaths: event.derivedPaths ?? [],
+                // Trigger origin (#324): cron-driven runs carry ctx.jobId.
+                triggeredBy: ctx.jobId ? 'cron' : 'interactive',
+                jobId: ctx.jobId ?? '',
             });
             if (r === null && cfg.failMode === 'closed' && cfg.enforcement === 'enforce') {
                 return { block: true, blockReason: `SafeClaw service unavailable at ${cfg.serviceUrl} (fail-closed)` };
@@ -255,18 +270,26 @@ 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 service says confirmation required, use OpenClaw's native approval flow.
+            // Carry any param rewrite (#316) on the same result — OpenClaw applies it as
+            // the approval's overrideParams once the user approves, so the post-approval
+            // execution still runs the governed (sanitized) params.
             if (r?.confirmationRequired) {
                 const riskLevel = r.riskLevel || '';
-                return {
+                const result = {
                     requireApproval: {
                         title: 'SafeClaw Governance Check',
                         description: r.reason || 'This action requires confirmation',
                         severity: approvalSeverityForRisk(riskLevel),
                         timeoutMs: 30_000,
                         timeoutBehavior: approvalTimeoutBehaviorForRisk(riskLevel),
+                        allowedDecisions: approvalAllowedDecisionsForRisk(riskLevel),
                     },
                 };
+                if (r.params && typeof r.params === 'object') {
+                    result.params = r.params;
+                }
+                return result;
             }
             if (r?.block) {
                 const blockReason = r.reason || 'Blocked by SafeClaw (no reason provided)';
@@ -278,24 +301,31 @@ export default {
                 }
                 // audit-only: logged server-side, no action here
             }
+            // Param rewrite (#316): the service only returns `params` for an allowed
+            // call when it sanitized the input (e.g. stripped control characters), so
+            // the tool executes the governed params rather than the raw ones.
+            if (r?.params && typeof r.params === 'object') {
+                return { params: r.params };
+            }
         }, { priority: 100 });
         // Context injection — prepend governance context to agent system prompt
         // (#195: before_agent_start is deprecated; use before_prompt_build + prependSystemContext)
         api.on('before_prompt_build', async (event, ctx) => {
             const r = await post('/context/build', {
-                sessionId: ctx.sessionId ?? event.sessionId ?? '',
+                sessionId: ctx.sessionKey ?? ctx.sessionId ?? event.sessionId ?? '',
                 userId: ctx.agentId ?? '',
             });
             if (r?.prependContext) {
                 return { prependSystemContext: r.prependContext };
             }
         }, { priority: 100 });
-        // Message governance — check outbound messages
-        // (#195: use ctx.conversationId/sessionId, ctx.accountId; return only { cancel: true })
+        // Message governance — check outbound messages.
+        // (v2026.6.8 message context exposes sessionKey/accountId/channelId — there is
+        // no sessionId; the event has no session field. Return only { cancel: true }.)
         api.on('message_sending', async (event, ctx) => {
             const cfg = getConfig();
             const r = await post('/evaluate/message', {
-                sessionId: ctx.conversationId ?? ctx.sessionId ?? event.sessionId ?? '',
+                sessionId: ctx.sessionKey ?? ctx.conversationId ?? '',
                 userId: ctx.accountId ?? '',
                 to: event.to,
                 content: event.content,
@@ -323,29 +353,42 @@ export default {
                 // audit-only: logged server-side, no action here
             }
         }, { priority: 100 });
-        // Async logging — fire-and-forget, no return value needed
-        // (#195: use event.prompt for input, event.lastAssistant for output; add provider/model)
+        // Async logging — fire-and-forget, no return value needed.
+        // (#315: v2026.6.8 raw-conversation hooks require
+        // `plugins.entries.safeclaw.hooks.allowConversationAccess: true` to fire at
+        // all — see README. Output text is `assistantTexts: string[]`, not the
+        // untyped `lastAssistant`. `runId` is forwarded for audit correlation.)
         api.on('llm_input', (event, ctx) => {
             post('/log/llm-input', {
-                sessionId: event.sessionId ?? ctx.sessionId ?? '',
+                sessionId: ctx.sessionKey ?? event.sessionId ?? ctx.sessionId ?? '',
                 content: event.prompt ?? '',
                 provider: event.provider ?? '',
                 model: event.model ?? '',
+                runId: event.runId ?? ctx.runId ?? '',
             }).catch((e) => log.warn('[SafeClaw] Failed to log LLM input:', e));
         });
         api.on('llm_output', (event, ctx) => {
+            // Join assistant segments with a blank line, matching how OpenClaw v2026.6.8
+            // itself joins `assistantTexts`, so message boundaries are preserved in the
+            // audit content (joining with '' would fuse "first"+"second" into one blob).
+            const assistantText = Array.isArray(event.assistantTexts)
+                ? event.assistantTexts.join('\n\n')
+                : typeof event.lastAssistant === 'string'
+                    ? event.lastAssistant
+                    : '';
             post('/log/llm-output', {
-                sessionId: event.sessionId ?? ctx.sessionId ?? '',
-                content: event.lastAssistant ?? '',
+                sessionId: ctx.sessionKey ?? event.sessionId ?? ctx.sessionId ?? '',
+                content: assistantText,
                 provider: event.provider ?? '',
                 model: event.model ?? '',
                 usage: event.usage ?? {},
+                runId: event.runId ?? ctx.runId ?? '',
             }).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 ?? '',
+                sessionId: ctx.sessionKey ?? ctx.sessionId ?? event.sessionId ?? '',
                 userId: ctx.agentId ?? '',
                 toolName: event.toolName ?? '',
                 params: event.params ?? {},
@@ -356,15 +399,27 @@ export default {
                 runId: ctx.runId ?? event.runId ?? '',
             }).catch((e) => log.warn('[SafeClaw] Failed to record tool result:', e));
         });
-        // Subagent governance — block delegation bypass attempts (#188)
+        // Subagent governance — block delegation bypass attempts (#188).
+        // NOTE: `subagent_spawning` is a deprecated OpenClaw compatibility hook
+        // (removal scheduled after 2026-08-16). In v2026.6.8 the context exposes only
+        // session keys (`requesterSessionKey`/`childSessionKey`/`runId`) — there is NO
+        // parent agentId at this hook. The event carries the *child's* `agentId`. So
+        // we forward the parent/child session keys and the child agent id; the service
+        // cannot do the killed-PARENT lookup from a session key alone, so spawn-time
+        // delegation enforcement is reworked onto a session-keyed hierarchy in #321.
+        // `requester` is an object (channel/account/to/threadId), not a string. (#312)
         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 ?? '',
-                parentAgentId: event.parentAgentId,
-                childConfig: event.childConfig ?? {},
-                reason: event.reason ?? '',
+                sessionId: ctx.requesterSessionKey ?? ctx.childSessionKey ?? '',
+                parentSessionKey: ctx.requesterSessionKey ?? '',
+                childSessionKey: ctx.childSessionKey ?? event.childSessionKey ?? '',
+                childAgentId: event.agentId ?? '',
+                mode: event.mode ?? '',
+                threadRequested: event.threadRequested ?? false,
+                requester: event.requester ?? {},
+                runId: ctx.runId ?? '',
+                reason: event.label ?? '',
             });
             // Fail-closed handling (matches before_tool_call / message_sending pattern)
             if (r === null && cfg.failMode === 'closed' && cfg.enforcement === 'enforce') {
@@ -383,18 +438,26 @@ export default {
                 log.warn(`[SafeClaw] Subagent spawn warning: ${r.reason}`);
             }
         }, { priority: 100 });
-        // Subagent ended — record child agent lifecycle (#188)
+        // Subagent ended — record child agent lifecycle (#188).
+        // v2026.6.8 reports `targetSessionKey`/`targetKind`/`outcome`/`error`/`runId`,
+        // not parent/child agent IDs. The ended child is `targetSessionKey`; the
+        // parent is the requester session key from the subagent context. (#312)
         api.on('subagent_ended', (event, ctx) => {
             post('/record/subagent-ended', {
-                sessionId: ctx.sessionId ?? event.sessionId ?? '',
-                parentAgentId: event.parentAgentId,
-                childAgentId: event.childAgentId,
+                sessionId: ctx.requesterSessionKey ?? event.targetSessionKey ?? '',
+                parentSessionKey: ctx.requesterSessionKey ?? '',
+                childSessionKey: event.targetSessionKey ?? '',
+                targetKind: event.targetKind ?? '',
+                outcome: event.outcome ?? '',
+                success: event.outcome ? event.outcome === 'ok' : !event.error,
+                error: event.error ?? '',
+                runId: event.runId ?? ctx.runId ?? '',
             }).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 ?? '',
+                sessionId: ctx.sessionKey ?? ctx.sessionId ?? event.sessionId ?? '',
                 userId: ctx.agentId ?? '',
                 agentId: instanceId,
                 metadata: event.metadata ?? {},
@@ -403,18 +466,23 @@ export default {
         // Session lifecycle — notify service of session end (#189)
         api.on('session_end', (event, ctx) => {
             post('/session/end', {
-                sessionId: ctx.sessionId ?? event.sessionId ?? '',
+                sessionId: ctx.sessionKey ?? ctx.sessionId ?? event.sessionId ?? '',
                 userId: ctx.agentId ?? '',
                 agentId: instanceId,
             }).catch((e) => log.warn('[SafeClaw] Failed to record session end:', e));
         });
-        // Inbound message governance — evaluate received messages (#190)
+        // Inbound message governance — evaluate received messages (#190).
+        // v2026.6.8 message context: sender is `event.from` (+ stable `event.senderId`),
+        // the session is `ctx.sessionKey`, and the channel id is on the context. The
+        // message context has no agentId (use accountId) and no provider field, so the
+        // service maps channel trust from `channelId`/`conversationId` (#313, feeds #320).
         api.on('message_received', (event, ctx) => {
             post('/evaluate/inbound-message', {
-                sessionId: ctx.sessionId ?? event.sessionId ?? '',
-                userId: ctx.agentId ?? '',
-                channel: event.channel ?? ctx.channelId ?? '',
-                sender: event.sender ?? '',
+                sessionId: ctx.sessionKey ?? event.sessionKey ?? '',
+                userId: ctx.accountId ?? '',
+                channel: ctx.channelId ?? '',
+                conversationId: ctx.conversationId ?? '',
+                sender: event.senderId ?? ctx.senderId ?? event.from ?? '',
                 content: event.content ?? '',
                 metadata: event.metadata ?? {},
             }).catch((e) => log.warn('[SafeClaw] Failed to evaluate inbound message:', e));

package/index.ts

@@ -7,7 +7,7 @@
  * to the SafeClaw service and acts on the responses.
  */
 
-import type { OpenClawPluginApi, OpenClawPluginEvent, OpenClawPluginContext, BeforeToolCallResult } from 'openclaw/plugin-sdk/core';
+import type { OpenClawPluginApi, BeforeToolCallResult } from 'openclaw/plugin-sdk/core';
 import { loadConfig, configHash } from './tui/config.js';
 import crypto from 'crypto';
 import { createRequire } from 'module';
@@ -114,6 +114,16 @@ function approvalTimeoutBehaviorForRisk(riskLevel: string): 'allow' | 'deny' {
   return riskLevel === 'CriticalRisk' || riskLevel === 'HighRisk' ? 'deny' : 'allow';
 }
 
+// For high-risk actions, forbid durable "allow-always" trust — the user may only
+// approve this one occurrence or deny (#314). Lower-risk actions keep all options.
+function approvalAllowedDecisionsForRisk(
+  riskLevel: string,
+): Array<'allow-once' | 'allow-always' | 'deny'> {
+  return riskLevel === 'CriticalRisk' || riskLevel === 'HighRisk'
+    ? ['allow-once', 'deny']
+    : ['allow-once', 'allow-always', 'deny'];
+}
+
 // --- Plugin Definition ---
 
 let handshakeCompleted = false;
@@ -251,18 +261,26 @@ export default {
     }
 
     // THE GATE — constraint checking on every tool call (#195: use correct OpenClaw field names)
-    api.on('before_tool_call', async (event: OpenClawPluginEvent, ctx: OpenClawPluginContext) => {
+    api.on('before_tool_call', async (event, ctx) => {
       const cfg = getConfig();
       if (!handshakeCompleted && cfg.failMode === 'closed' && cfg.enforcement === 'enforce') {
         return { block: true, blockReason: 'SafeClaw handshake not completed (fail-closed)' };
       }
 
       const r = await post('/evaluate/tool-call', {
-        sessionId: ctx.sessionId ?? event.sessionId ?? '',
+        sessionId: ctx.sessionKey ?? ctx.sessionId ?? event.sessionId ?? '',
         userId: ctx.agentId ?? '',
         toolName: event.toolName ?? '',
         params: event.params ?? {},
         runId: ctx.runId ?? '',
+        // v2026.6.8 discriminators so the service can classify code-mode exec,
+        // file-touching envelopes, etc. (#316)
+        toolKind: event.toolKind ?? '',
+        toolInputKind: event.toolInputKind ?? '',
+        derivedPaths: event.derivedPaths ?? [],
+        // Trigger origin (#324): cron-driven runs carry ctx.jobId.
+        triggeredBy: ctx.jobId ? 'cron' : 'interactive',
+        jobId: ctx.jobId ?? '',
       });
 
       if (r === null && cfg.failMode === 'closed' && cfg.enforcement === 'enforce') {
@@ -273,18 +291,26 @@ export default {
         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 service says confirmation required, use OpenClaw's native approval flow.
+      // Carry any param rewrite (#316) on the same result — OpenClaw applies it as
+      // the approval's overrideParams once the user approves, so the post-approval
+      // execution still runs the governed (sanitized) params.
       if (r?.confirmationRequired) {
         const riskLevel = (r.riskLevel as string) || '';
-        return {
+        const result: BeforeToolCallResult = {
           requireApproval: {
             title: 'SafeClaw Governance Check',
             description: (r.reason as string) || 'This action requires confirmation',
             severity: approvalSeverityForRisk(riskLevel),
             timeoutMs: 30_000,
             timeoutBehavior: approvalTimeoutBehaviorForRisk(riskLevel),
+            allowedDecisions: approvalAllowedDecisionsForRisk(riskLevel),
           },
-        } satisfies BeforeToolCallResult;
+        };
+        if (r.params && typeof r.params === 'object') {
+          result.params = r.params as Record<string, unknown>;
+        }
+        return result satisfies BeforeToolCallResult;
       }
 
       if (r?.block) {
@@ -297,13 +323,20 @@ export default {
         }
         // audit-only: logged server-side, no action here
       }
+
+      // Param rewrite (#316): the service only returns `params` for an allowed
+      // call when it sanitized the input (e.g. stripped control characters), so
+      // the tool executes the governed params rather than the raw ones.
+      if (r?.params && typeof r.params === 'object') {
+        return { params: r.params as Record<string, unknown> };
+      }
     }, { priority: 100 });
 
     // Context injection — prepend governance context to agent system prompt
     // (#195: before_agent_start is deprecated; use before_prompt_build + prependSystemContext)
-    api.on('before_prompt_build', async (event: OpenClawPluginEvent, ctx: OpenClawPluginContext) => {
+    api.on('before_prompt_build', async (event, ctx) => {
       const r = await post('/context/build', {
-        sessionId: ctx.sessionId ?? event.sessionId ?? '',
+        sessionId: ctx.sessionKey ?? ctx.sessionId ?? event.sessionId ?? '',
         userId: ctx.agentId ?? '',
       });
 
@@ -312,12 +345,13 @@ export default {
       }
     }, { priority: 100 });
 
-    // Message governance — check outbound messages
-    // (#195: use ctx.conversationId/sessionId, ctx.accountId; return only { cancel: true })
-    api.on('message_sending', async (event: OpenClawPluginEvent, ctx: OpenClawPluginContext) => {
+    // Message governance — check outbound messages.
+    // (v2026.6.8 message context exposes sessionKey/accountId/channelId — there is
+    // no sessionId; the event has no session field. Return only { cancel: true }.)
+    api.on('message_sending', async (event, ctx) => {
       const cfg = getConfig();
       const r = await post('/evaluate/message', {
-        sessionId: ctx.conversationId ?? ctx.sessionId ?? event.sessionId ?? '',
+        sessionId: ctx.sessionKey ?? ctx.conversationId ?? '',
         userId: ctx.accountId ?? '',
         to: event.to,
         content: event.content,
@@ -345,31 +379,44 @@ export default {
       }
     }, { priority: 100 });
 
-    // Async logging — fire-and-forget, no return value needed
-    // (#195: use event.prompt for input, event.lastAssistant for output; add provider/model)
-    api.on('llm_input', (event: OpenClawPluginEvent, ctx: OpenClawPluginContext) => {
+    // Async logging — fire-and-forget, no return value needed.
+    // (#315: v2026.6.8 raw-conversation hooks require
+    // `plugins.entries.safeclaw.hooks.allowConversationAccess: true` to fire at
+    // all — see README. Output text is `assistantTexts: string[]`, not the
+    // untyped `lastAssistant`. `runId` is forwarded for audit correlation.)
+    api.on('llm_input', (event, ctx) => {
       post('/log/llm-input', {
-        sessionId: event.sessionId ?? ctx.sessionId ?? '',
+        sessionId: ctx.sessionKey ?? event.sessionId ?? ctx.sessionId ?? '',
         content: event.prompt ?? '',
         provider: event.provider ?? '',
         model: event.model ?? '',
+        runId: event.runId ?? ctx.runId ?? '',
       }).catch((e) => log.warn('[SafeClaw] Failed to log LLM input:', e));
     });
 
-    api.on('llm_output', (event: OpenClawPluginEvent, ctx: OpenClawPluginContext) => {
+    api.on('llm_output', (event, ctx) => {
+      // Join assistant segments with a blank line, matching how OpenClaw v2026.6.8
+      // itself joins `assistantTexts`, so message boundaries are preserved in the
+      // audit content (joining with '' would fuse "first"+"second" into one blob).
+      const assistantText = Array.isArray(event.assistantTexts)
+        ? event.assistantTexts.join('\n\n')
+        : typeof event.lastAssistant === 'string'
+          ? event.lastAssistant
+          : '';
       post('/log/llm-output', {
-        sessionId: event.sessionId ?? ctx.sessionId ?? '',
-        content: event.lastAssistant ?? '',
+        sessionId: ctx.sessionKey ?? event.sessionId ?? ctx.sessionId ?? '',
+        content: assistantText,
         provider: event.provider ?? '',
         model: event.model ?? '',
         usage: event.usage ?? {},
+        runId: event.runId ?? ctx.runId ?? '',
       }).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) => {
+    api.on('after_tool_call', (event, ctx) => {
       post('/record/tool-result', {
-        sessionId: ctx.sessionId ?? event.sessionId ?? '',
+        sessionId: ctx.sessionKey ?? ctx.sessionId ?? event.sessionId ?? '',
         userId: ctx.agentId ?? '',
         toolName: event.toolName ?? '',
         params: event.params ?? {},
@@ -381,15 +428,27 @@ export default {
       }).catch((e) => log.warn('[SafeClaw] Failed to record tool result:', e));
     });
 
-    // Subagent governance — block delegation bypass attempts (#188)
-    api.on('subagent_spawning', async (event: OpenClawPluginEvent, ctx: OpenClawPluginContext) => {
+    // Subagent governance — block delegation bypass attempts (#188).
+    // NOTE: `subagent_spawning` is a deprecated OpenClaw compatibility hook
+    // (removal scheduled after 2026-08-16). In v2026.6.8 the context exposes only
+    // session keys (`requesterSessionKey`/`childSessionKey`/`runId`) — there is NO
+    // parent agentId at this hook. The event carries the *child's* `agentId`. So
+    // we forward the parent/child session keys and the child agent id; the service
+    // cannot do the killed-PARENT lookup from a session key alone, so spawn-time
+    // delegation enforcement is reworked onto a session-keyed hierarchy in #321.
+    // `requester` is an object (channel/account/to/threadId), not a string. (#312)
+    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 ?? '',
-        parentAgentId: event.parentAgentId,
-        childConfig: event.childConfig ?? {},
-        reason: event.reason ?? '',
+        sessionId: ctx.requesterSessionKey ?? ctx.childSessionKey ?? '',
+        parentSessionKey: ctx.requesterSessionKey ?? '',
+        childSessionKey: ctx.childSessionKey ?? event.childSessionKey ?? '',
+        childAgentId: event.agentId ?? '',
+        mode: event.mode ?? '',
+        threadRequested: event.threadRequested ?? false,
+        requester: event.requester ?? {},
+        runId: ctx.runId ?? '',
+        reason: event.label ?? '',
       });
 
       // Fail-closed handling (matches before_tool_call / message_sending pattern)
@@ -409,19 +468,27 @@ export default {
       }
     }, { priority: 100 });
 
-    // Subagent ended — record child agent lifecycle (#188)
-    api.on('subagent_ended', (event: OpenClawPluginEvent, ctx: OpenClawPluginContext) => {
+    // Subagent ended — record child agent lifecycle (#188).
+    // v2026.6.8 reports `targetSessionKey`/`targetKind`/`outcome`/`error`/`runId`,
+    // not parent/child agent IDs. The ended child is `targetSessionKey`; the
+    // parent is the requester session key from the subagent context. (#312)
+    api.on('subagent_ended', (event, ctx) => {
       post('/record/subagent-ended', {
-        sessionId: ctx.sessionId ?? event.sessionId ?? '',
-        parentAgentId: event.parentAgentId,
-        childAgentId: event.childAgentId,
+        sessionId: ctx.requesterSessionKey ?? event.targetSessionKey ?? '',
+        parentSessionKey: ctx.requesterSessionKey ?? '',
+        childSessionKey: event.targetSessionKey ?? '',
+        targetKind: event.targetKind ?? '',
+        outcome: event.outcome ?? '',
+        success: event.outcome ? event.outcome === 'ok' : !event.error,
+        error: event.error ?? '',
+        runId: event.runId ?? ctx.runId ?? '',
       }).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) => {
+    api.on('session_start', (event, ctx) => {
       post('/session/start', {
-        sessionId: ctx.sessionId ?? event.sessionId ?? '',
+        sessionId: ctx.sessionKey ?? ctx.sessionId ?? event.sessionId ?? '',
         userId: ctx.agentId ?? '',
         agentId: instanceId,
         metadata: event.metadata ?? {},
@@ -429,21 +496,26 @@ export default {
     });
 
     // Session lifecycle — notify service of session end (#189)
-    api.on('session_end', (event: OpenClawPluginEvent, ctx: OpenClawPluginContext) => {
+    api.on('session_end', (event, ctx) => {
       post('/session/end', {
-        sessionId: ctx.sessionId ?? event.sessionId ?? '',
+        sessionId: ctx.sessionKey ?? ctx.sessionId ?? event.sessionId ?? '',
         userId: ctx.agentId ?? '',
         agentId: instanceId,
       }).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) => {
+    // Inbound message governance — evaluate received messages (#190).
+    // v2026.6.8 message context: sender is `event.from` (+ stable `event.senderId`),
+    // the session is `ctx.sessionKey`, and the channel id is on the context. The
+    // message context has no agentId (use accountId) and no provider field, so the
+    // service maps channel trust from `channelId`/`conversationId` (#313, feeds #320).
+    api.on('message_received', (event, ctx) => {
       post('/evaluate/inbound-message', {
-        sessionId: ctx.sessionId ?? event.sessionId ?? '',
-        userId: ctx.agentId ?? '',
-        channel: event.channel ?? (ctx as any).channelId ?? '',
-        sender: event.sender ?? '',
+        sessionId: ctx.sessionKey ?? event.sessionKey ?? '',
+        userId: ctx.accountId ?? '',
+        channel: ctx.channelId ?? '',
+        conversationId: ctx.conversationId ?? '',
+        sender: event.senderId ?? ctx.senderId ?? event.from ?? '',
         content: event.content ?? '',
         metadata: event.metadata ?? {},
       }).catch((e) => log.warn('[SafeClaw] Failed to evaluate inbound message:', e));

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.5.0",
+  "version": "2.0.0",
   "author": "Tendly EU",
   "license": "MIT",
   "homepage": "https://safeclaw.eu",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-safeclaw-plugin",
-  "version": "1.5.0",
+  "version": "2.0.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",
@@ -58,7 +58,7 @@
     "typescript": "^5.4.0"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.1.0"
+    "openclaw": ">=2026.6.8"
   },
   "peerDependenciesMeta": {
     "openclaw": {

package/types/openclaw-sdk.d.ts

@@ -1,104 +1,316 @@
 /**
- * Ambient type declarations for OpenClaw Plugin SDK.
- * These match the types exported by openclaw/plugin-sdk as of v2026.4.
- * When installed inside OpenClaw, the real SDK types take precedence.
+ * Ambient type declarations for the OpenClaw Plugin SDK.
+ * Transcribed from the published `openclaw@2026.6.8` source
+ * (`src/plugins/hook-types.ts`, `hook-message.types.ts`,
+ * `hook-before-tool-call-result.ts`). When installed inside OpenClaw the real
+ * SDK types take precedence.
+ *
+ * Design note (#317): each registered hook has BOTH a precise event payload and
+ * a precise *context* type — the contexts genuinely differ (agent runs expose
+ * `agentId`/`sessionId`; message hooks expose neither, only `sessionKey`;
+ * subagent hooks expose only `requesterSessionKey`/`childSessionKey`/`runId`).
+ * `on()` is typed via per-hook overloads keyed off `PluginHookEventMap` /
+ * `PluginHookContextMap`, so reading a field that does not exist on that hook's
+ * real payload/context (e.g. `ctx.agentId` on a subagent hook, `ctx.sessionId`
+ * on a message hook) fails `tsc` instead of silently reading `undefined`.
  */
 
 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,
-      options?: { priority?: number },
-    ): void;
-    registerService?(service: OpenClawPluginService): void;
-    registerCli?(registrar: (ctx: { program: unknown; config: unknown }) => void, opts?: { commands: string[] }): void;
-    registerTool?(tool: OpenClawPluginTool): void;
-    registerCommand?(def: { name: string; description: string; execute: (ctx: unknown) => Promise<string | void> }): void;
-    pluginConfig?: Record<string, unknown>;
-    logger?: OpenClawPluginLogger;
+  // ---- Per-hook contexts (v2026.6.8) ----
+
+  /** PluginHookAgentContext — agent-runtime hooks (tool calls, prompts, llm, session). */
+  export interface PluginHookAgentContext {
+    runId?: string;
+    jobId?: string;
+    agentId?: string;
+    /** Canonical conversation key — present on agent-runtime hooks. */
+    sessionKey?: string;
+    sessionId?: string;
+    workspaceDir?: string;
+    modelProviderId?: string;
+    modelId?: string;
+    messageProvider?: string;
+    /** Channel/plugin id for channel-originated runs, e.g. "discord". */
+    channel?: string;
+    chatId?: string;
+    senderId?: string;
+    trigger?: string;
+    channelId?: string;
   }
 
-  export interface OpenClawPluginEvent {
+  /** PluginHookMessageContext — inbound/outbound message hooks. No agentId / sessionId. */
+  export interface PluginHookMessageContext {
+    channelId: string;
+    accountId?: string;
+    conversationId?: string;
+    /** Canonical conversation key; the message-hook equivalent of sessionId. */
+    sessionKey?: string;
+    runId?: string;
+    messageId?: string;
+    senderId?: string;
+    replyToId?: string;
+  }
+
+  /** PluginHookSubagentContext — subagent_spawning / subagent_ended. Session keys only. */
+  export interface PluginHookSubagentContext {
+    runId?: string;
+    childSessionKey?: string;
+    /** The requesting (parent) session key. There is no parent agentId here. */
+    requesterSessionKey?: string;
+  }
+
+  /** Loose fallback context for hooks SafeClaw does not strongly type. */
+  export interface OpenClawPluginContext {
+    [key: string]: unknown;
+  }
+
+  // ---- Per-hook event payloads (v2026.6.8) ----
+
+  export interface BeforeToolCallEvent {
+    toolName?: string;
+    params?: Record<string, unknown>;
     sessionId?: string;
+    runId?: string;
+    toolCallId?: string;
+    /** e.g. "code_mode_exec" — distinguishes code-mode exec cells from shell exec. */
+    toolKind?: string;
+    /** Code-mode body language, e.g. "javascript" | "typescript". */
+    toolInputKind?: string;
+    /** Host-derived target paths for file-touching envelopes (e.g. apply_patch). */
+    derivedPaths?: readonly string[];
+  }
+
+  export interface AfterToolCallEvent {
     toolName?: string;
     params?: Record<string, unknown>;
-    to?: string;
-    content?: string;
     result?: unknown;
     error?: string;
     durationMs?: number;
+    sessionId?: string;
+    runId?: string;
+  }
+
+  export interface BeforePromptBuildEvent {
+    sessionId?: string;
+  }
+
+  /** v2026.6.8 PluginHookMessageSendingEvent — no sessionId on the event. */
+  export interface MessageSendingEvent {
+    to: string;
+    content: string;
+    replyToId?: string | number;
+    threadId?: string | number;
+    metadata?: Record<string, unknown>;
+  }
+
+  /** v2026.6.8 PluginHookMessageReceivedEvent — sender is `from`; key is `sessionKey`. */
+  export interface MessageReceivedEvent {
+    from: string;
+    content: string;
+    timestamp?: number;
+    threadId?: string | number;
+    messageId?: string;
+    senderId?: string;
+    replyToId?: string;
+    replyToSender?: string;
+    sessionKey?: string;
+    runId?: string;
+    metadata?: Record<string, unknown>;
+  }
+
+  export interface LlmInputEvent {
+    runId?: string;
+    sessionId?: string;
+    provider?: string;
+    model?: string;
+    systemPrompt?: string;
     prompt?: string;
+  }
+
+  /** v2026.6.8: reliable text is `assistantTexts: string[]`; `lastAssistant` is untyped. */
+  export interface LlmOutputEvent {
+    runId?: string;
+    sessionId?: string;
     provider?: string;
     model?: string;
-    lastAssistant?: string;
+    prompt?: string;
+    assistantTexts?: string[];
+    lastAssistant?: unknown;
     usage?: Record<string, unknown>;
+  }
+
+  /**
+   * Deprecated compatibility hook (removal scheduled after 2026-08-16).
+   * v2026.6.8 PluginHookSubagentSpawnBase — `requester` is an object, not a string.
+   */
+  export interface SubagentSpawningEvent {
+    childSessionKey: string;
+    agentId: string;
+    label?: string;
+    mode: 'run' | 'session';
+    requester?: {
+      channel?: string;
+      accountId?: string;
+      to?: string;
+      threadId?: string | number;
+    };
+    threadRequested: boolean;
+  }
+
+  export interface SubagentEndedEvent {
+    targetSessionKey: string;
+    targetKind: 'subagent' | 'acp';
+    reason: string;
+    sendFarewell?: boolean;
+    accountId?: string;
     runId?: string;
-    toolCallId?: string;
-    childAgentId?: string;
-    parentAgentId?: string;
-    childConfig?: Record<string, unknown>;
-    reason?: string;
-    metadata?: Record<string, unknown>;
-    channel?: string;
-    sender?: string;
-    [key: string]: unknown;
+    endedAt?: number;
+    outcome?: 'ok' | 'error' | 'timeout' | 'killed' | 'reset' | 'deleted';
+    error?: string;
   }
 
-  export interface OpenClawPluginContext {
+  export interface SessionLifecycleEvent {
     sessionId?: string;
-    agentId?: string;
-    runId?: string;
-    conversationId?: string;
-    accountId?: string;
-    channelId?: string;
-    workspaceDir?: string;
+    sessionKey?: string;
+    metadata?: Record<string, unknown>;
+  }
+
+  /** Generic fallback payload for hooks SafeClaw does not strongly type. */
+  export interface OpenClawPluginEvent {
     [key: string]: unknown;
   }
 
-  export interface OpenClawPluginService {
-    id: string;
-    start: () => void | Promise<void>;
-    stop?: () => void | Promise<void>;
+  export interface PluginHookEventMap {
+    before_tool_call: BeforeToolCallEvent;
+    after_tool_call: AfterToolCallEvent;
+    before_prompt_build: BeforePromptBuildEvent;
+    message_sending: MessageSendingEvent;
+    message_received: MessageReceivedEvent;
+    llm_input: LlmInputEvent;
+    llm_output: LlmOutputEvent;
+    subagent_spawning: SubagentSpawningEvent;
+    subagent_ended: SubagentEndedEvent;
+    session_start: SessionLifecycleEvent;
+    session_end: SessionLifecycleEvent;
   }
 
-  export interface OpenClawPluginTool {
-    name: string;
-    description: string;
-    parameters: Record<string, unknown>;
-    execute: (params: Record<string, unknown>, ctx: Record<string, unknown>) => Promise<unknown>;
+  export interface PluginHookContextMap {
+    before_tool_call: PluginHookAgentContext;
+    after_tool_call: PluginHookAgentContext;
+    before_prompt_build: PluginHookAgentContext;
+    message_sending: PluginHookMessageContext;
+    message_received: PluginHookMessageContext;
+    llm_input: PluginHookAgentContext;
+    llm_output: PluginHookAgentContext;
+    subagent_spawning: PluginHookSubagentContext;
+    subagent_ended: PluginHookSubagentContext;
+    session_start: PluginHookAgentContext;
+    session_end: PluginHookAgentContext;
   }
 
+  // ---- Hook results ----
+
+  export type PluginApprovalDecision = 'allow-once' | 'allow-always' | 'deny';
+  /** v2026.6.8: typed resolution union (was a free-form string). */
+  export type PluginApprovalResolution = PluginApprovalDecision | 'timeout' | 'cancelled';
+
   export interface PluginApprovalRequest {
     title: string;
     description: string;
     severity?: 'info' | 'warning' | 'critical';
     timeoutMs?: number;
     timeoutBehavior?: 'allow' | 'deny';
+    /** v2026.6.8: restrict the offered decisions (e.g. forbid durable "allow-always"). */
+    allowedDecisions?: PluginApprovalDecision[];
     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;
+    /** v2026.6.8: rewrite tool params before execution. */
+    params?: Record<string, unknown>;
+  }
+
+  export interface BeforePromptBuildResult {
+    prependSystemContext?: string;
+  }
+
+  export interface MessageSendingResult {
+    content?: string;
+    cancel?: boolean;
+    cancelReason?: string;
+  }
+
+  /** v2026.6.8 discriminated union — the error variant requires `error: string`. */
+  export type SubagentSpawningResult =
+    | {
+        status: 'ok';
+        threadBindingReady?: boolean;
+        deliveryOrigin?: {
+          channel?: string;
+          accountId?: string;
+          to?: string;
+          threadId?: string | number;
+        };
+      }
+    | { status: 'error'; error: string };
+
+  export interface PluginHookResultMap {
+    before_tool_call: BeforeToolCallResult;
+    after_tool_call: void;
+    before_prompt_build: BeforePromptBuildResult;
+    message_sending: MessageSendingResult;
+    message_received: void;
+    llm_input: void;
+    llm_output: void;
+    subagent_spawning: SubagentSpawningResult;
+    subagent_ended: void;
+    session_start: void;
+    session_end: void;
+  }
+
+  export interface OpenClawPluginApi {
+    /** Typed overload for the hooks SafeClaw registers (precise event + context). */
+    on<K extends keyof PluginHookEventMap>(
+      hookName: K,
+      handler: (
+        event: PluginHookEventMap[K],
+        ctx: PluginHookContextMap[K],
+      ) => PluginHookResultMap[K] | void | Promise<PluginHookResultMap[K] | void>,
+      options?: { priority?: number; timeoutMs?: number },
+    ): void;
+    /** Generic fallback for any other hook. */
+    on(
+      hookName: string,
+      handler: (
+        event: OpenClawPluginEvent,
+        ctx: OpenClawPluginContext,
+      ) => Promise<Record<string, unknown> | void> | void,
+      options?: { priority?: number; timeoutMs?: number },
+    ): void;
+
+    registerService?(service: OpenClawPluginService): void;
+    registerCli?(registrar: (ctx: { program: unknown; config: unknown }) => void, opts?: { commands: string[] }): void;
+    registerTool?(tool: OpenClawPluginTool): void;
+    registerCommand?(def: { name: string; description: string; execute: (ctx: unknown) => Promise<string | void> }): void;
+    pluginConfig?: Record<string, unknown>;
+    logger?: OpenClawPluginLogger;
+  }
+
+  export interface OpenClawPluginService {
+    id: string;
+    start: () => void | Promise<void>;
+    stop?: () => void | Promise<void>;
+  }
+
+  export interface OpenClawPluginTool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (params: Record<string, unknown>, ctx: Record<string, unknown>) => Promise<unknown>;
   }
 
   export interface OpenClawPluginLogger {