@clawling/clawchat-plugin-openclaw 2026.6.30-3 → 2026.7.1

package/dist/src/tools.js

@@ -4,6 +4,7 @@ import { execFile } from "node:child_process";
 import { createOpenclawClawlingApiClient } from "./api-client.js";
 import { resolveLivewarePath } from "./liveware-cli.js";
 import { ClawlingApiError, } from "./api-types.js";
+import { mapGateOutcome } from "./gate-outcome.js";
 import { resolveOpenclawClawlingAccount } from "./config.js";
 import { clawChatDbPathForStateDir, getClawChatStore, } from "./storage.js";
 import { sendOpenclawClawlingMentionMessage } from "./outbound.js";
@@ -272,6 +273,38 @@ export function registerOpenclawClawlingTools(api, options = {}) {
             }
         })();
     }
+    /**
+     * Like withClient, but maps gate codes (21001/21003) to structured outcomes
+     * via mapGateOutcome so the agent sees a clear pending/forbidden status
+     * instead of a generic error. Used for friend and moment mutation tools.
+     */
+    function withGatedClient(fn) {
+        return (async () => {
+            const built = buildClient();
+            if (!built.ok)
+                return built.error;
+            try {
+                const data = await fn(built.client);
+                return jsonResponse(data);
+            }
+            catch (err) {
+                if (err instanceof ClawlingApiError) {
+                    const code = typeof err.meta?.code === "number" ? err.meta.code : null;
+                    if (code !== null) {
+                        const rawData = err.meta?.data;
+                        const gateData = rawData !== null && rawData !== undefined && typeof rawData === "object"
+                            ? rawData
+                            : {};
+                        const outcome = mapGateOutcome(code, gateData);
+                        if (outcome !== null)
+                            return jsonResponse(outcome);
+                    }
+                    return apiError(err);
+                }
+                return genericError(err);
+            }
+        })();
+    }
     function workspaceRoot(ctx) {
         const root = typeof ctx.workspaceDir === "string" ? ctx.workspaceDir.trim() : "";
         return root || null;
@@ -640,7 +673,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
         async execute(_callId, params) {
             return await recordClawchatToolCall("clawchat_send_friend_request", params, async () => {
                 const p = params;
-                return await withClient((c) => c.sendFriendRequest(p));
+                return await withGatedClient((c) => c.sendFriendRequest(p));
             });
         },
     }, { name: "clawchat_send_friend_request" });
@@ -668,7 +701,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
         async execute(_callId, params) {
             return await recordClawchatToolCall("clawchat_accept_friend_request", params, async () => {
                 const p = params;
-                return await withClient((c) => c.acceptFriendRequest(p.requestId));
+                return await withGatedClient((c) => c.acceptFriendRequest(p.requestId));
             });
         },
     }, { name: "clawchat_accept_friend_request" });
@@ -682,7 +715,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
         async execute(_callId, params) {
             return await recordClawchatToolCall("clawchat_reject_friend_request", params, async () => {
                 const p = params;
-                return await withClient((c) => c.rejectFriendRequest(p.requestId));
+                return await withGatedClient((c) => c.rejectFriendRequest(p.requestId));
             });
         },
     }, { name: "clawchat_reject_friend_request" });
@@ -696,7 +729,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
         async execute(_callId, params) {
             return await recordClawchatToolCall("clawchat_remove_friend", params, async () => {
                 const p = params;
-                return await withClient((c) => c.removeFriend(p.friendUserId));
+                return await withGatedClient((c) => c.removeFriend(p.friendUserId));
             });
         },
     }, { name: "clawchat_remove_friend" });
@@ -841,7 +874,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
                 if (!text && (!images || images.length === 0)) {
                     return validationError("clawchat-plugin-openclaw: at least one of text or images is required");
                 }
-                return await withClient((c) => c.createMoment({
+                return await withGatedClient((c) => c.createMoment({
                     ...(text !== undefined ? { text } : {}),
                     ...(images !== undefined ? { images } : {}),
                 }));
@@ -858,7 +891,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
         async execute(_callId, params) {
             return await recordClawchatToolCall("clawchat_delete_moment", params, async () => {
                 const p = params;
-                return await withClient((c) => c.deleteMoment(p.momentId));
+                return await withGatedClient((c) => c.deleteMoment(p.momentId));
             });
         },
     }, { name: "clawchat_delete_moment" });
@@ -875,7 +908,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
                 if (!p.emoji?.trim()) {
                     return validationError("clawchat-plugin-openclaw: emoji is required");
                 }
-                return await withClient((c) => c.toggleMomentReaction({ momentId: p.momentId, emoji: p.emoji }));
+                return await withGatedClient((c) => c.toggleMomentReaction({ momentId: p.momentId, emoji: p.emoji }));
             });
         },
     }, { name: "clawchat_toggle_moment_reaction" });
@@ -892,7 +925,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
                 if (!p.text?.trim()) {
                     return validationError("clawchat-plugin-openclaw: text is required");
                 }
-                return await withClient((c) => c.createMomentComment({ momentId: p.momentId, text: p.text }));
+                return await withGatedClient((c) => c.createMomentComment({ momentId: p.momentId, text: p.text }));
             });
         },
     }, { name: "clawchat_create_moment_comment" });
@@ -909,7 +942,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
                 if (!p.text?.trim()) {
                     return validationError("clawchat-plugin-openclaw: text is required");
                 }
-                return await withClient((c) => c.replyMomentComment({
+                return await withGatedClient((c) => c.replyMomentComment({
                     momentId: p.momentId,
                     replyToCommentId: p.replyToCommentId,
                     text: p.text,
@@ -927,7 +960,7 @@ export function registerOpenclawClawlingTools(api, options = {}) {
         async execute(_callId, params) {
             return await recordClawchatToolCall("clawchat_delete_moment_comment", params, async () => {
                 const p = params;
-                return await withClient((c) => c.deleteMomentComment({ momentId: p.momentId, commentId: p.commentId }));
+                return await withGatedClient((c) => c.deleteMomentComment({ momentId: p.momentId, commentId: p.commentId }));
             });
         },
     }, { name: "clawchat_delete_moment_comment" });

package/dist/src/ws-client.js

@@ -84,6 +84,23 @@ export function createWebSocketTransport(WebSocketCtor = globalThis.WebSocket) {
         },
     };
 }
+/**
+ * Returns the capability set advertised in the connect handshake.
+ * Exported so tests can assert on the exact fields without a full WS setup.
+ *
+ * permission_events: forward-compat: advertises readiness for a future native
+ * `permission.receipt` wire frame; today the permission-decision receipt is
+ * delivered as a system message until msghub emits the native frame.
+ */
+export function buildConnectCapabilities() {
+    return {
+        multi_device: false,
+        device_replay: true,
+        chat_meta_events: true,
+        notify_signals: true,
+        permission_events: true,
+    };
+}
 export class ClawChatClient extends EventEmitter {
     opts;
     currentState = "idle";
@@ -333,12 +350,8 @@ export class ClawChatClient extends EventEmitter {
             // *send* history.transit, which a single-device agent never does, and we
             // do not handle inbound history.transit — advertising it would invite
             // frames we cannot process. This is a deliberate, spec-legal omission.
-            capabilities: {
-                multi_device: false,
-                device_replay: true,
-                chat_meta_events: true,
-                notify_signals: true,
-            },
+            // permission_events: forward-compat; see buildConnectCapabilities().
+            capabilities: buildConnectCapabilities(),
         };
         const traceId = this.nextTraceId();
         this.expectedConnectTraceId = traceId;

package/openclaw.plugin.json

@@ -107,6 +107,7 @@
       "forwardThinking": { "type": "boolean" },
       "forwardToolCalls": { "type": "boolean" },
       "richInteractions": { "type": "boolean" },
+      "awarenessNote": { "type": "boolean" },
       "reconnect": {
         "type": "object",
         "additionalProperties": false,
@@ -180,6 +181,7 @@
           "forwardThinking": { "type": "boolean" },
           "forwardToolCalls": { "type": "boolean" },
           "richInteractions": { "type": "boolean" },
+          "awarenessNote": { "type": "boolean" },
           "reconnect": {
             "type": "object",
             "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.6.30-3",
+  "version": "2026.7.1",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "author": "CLAWLING PTE. LTD.",

package/src/api-client.ts

@@ -17,6 +17,7 @@ import {
   type UserSearchHit,
 } from "./api-types.ts";
 import type { GroupSettings, GroupSettingsFetchResult } from "./group-settings.ts";
+import type { PermissionPolicy, PermState } from "./permissions.ts";
 import { CHANNEL_ID } from "./config.ts";
 
 export interface PluginReportInput {
@@ -179,6 +180,17 @@ export interface OpenclawClawlingApiClient {
    * error still throws.
    */
   getMyGroupSettings(): Promise<GroupSettingsFetchResult>;
+  /**
+   * Fetch the agent's permission policy from `GET /v1/agents/me/permissions`.
+   *
+   * The response `data` is a flat object mapping operation name → state
+   * (`"ask"|"allow"|"deny"`), with one special key `"moment.visibility"` whose
+   * value is a string array. Returns a `PermissionPolicy` with `byOperation`
+   * (all non-visibility keys) and `momentVisibility` (the array). Throws on
+   * network errors or non-2xx responses; callers must catch and keep the stale
+   * cache (never throw / never block message handling).
+   */
+  getMyPermissions(): Promise<PermissionPolicy>;
   registerApp(params: { name: string; appId: string; url: string }): Promise<{ app: AgentAppView }>;
   listApps(): Promise<{ apps: AgentAppView[] }>;
   unregisterApp(appId: string): Promise<{ deleted: boolean }>;
@@ -362,6 +374,7 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
           code,
           status: res.status,
           path,
+          ...(env.data !== undefined ? { data: env.data } : {}),
         });
       }
       return env.data as T;
@@ -759,5 +772,15 @@ export function createOpenclawClawlingApiClient(opts: ApiClientOptions): Opencla
       }
       return { authoritative: true, rows };
     },
+    async getMyPermissions(): Promise<PermissionPolicy> {
+      const data = await call<Record<string, unknown>>("GET", "/v1/agents/me/permissions");
+      const byOperation: Record<string, PermState> = {};
+      let momentVisibility: string[] = [];
+      for (const [k, v] of Object.entries(data ?? {})) {
+        if (k === "moment.visibility") momentVisibility = (v as string[]) ?? [];
+        else byOperation[k] = v as PermState;
+      }
+      return { byOperation, momentVisibility };
+    },
   };
 }

package/src/api-types.ts

@@ -157,7 +157,7 @@ export class ClawlingApiError extends Error {
   constructor(
     public readonly kind: ClawlingApiErrorKind,
     message: string,
-    public readonly meta?: { code?: number; status?: number; path?: string },
+    public readonly meta?: { code?: number; status?: number; path?: string; data?: unknown },
   ) {
     super(message);
     this.name = "ClawlingApiError";

package/src/config.ts

@@ -106,6 +106,8 @@ export type OpenclawClawlingConfig = {
   forwardToolCalls?: boolean;
   /** Emit approval/action rich fragments instead of plain fallback text. */
   richInteractions?: boolean;
+  /** Emit ONE consolidated awareness note to the agent when friend/conversation signals arrive. */
+  awarenessNote?: boolean;
   reconnect?: OpenclawClawlingReconnectConfig;
   heartbeat?: OpenclawClawlingHeartbeatConfig;
   ack?: OpenclawClawlingAckConfig;
@@ -152,6 +154,7 @@ export const openclawClawlingConfigSchema = {
     forwardThinking: { type: "boolean" },
     forwardToolCalls: { type: "boolean" },
     richInteractions: { type: "boolean" },
+    awarenessNote: { type: "boolean" },
     reconnect: {
       type: "object",
       additionalProperties: false,
@@ -274,6 +277,7 @@ export type ResolvedOpenclawClawlingAccount = {
   forwardThinking: boolean;
   forwardToolCalls: boolean;
   richInteractions: boolean;
+  awarenessNote: boolean;
   allowFrom: string[];
   reconnect: Required<OpenclawClawlingReconnectConfig>;
   heartbeat: Required<OpenclawClawlingHeartbeatConfig>;
@@ -482,6 +486,8 @@ export function resolveOpenclawClawlingAccount(
     typeof channel.forwardToolCalls === "boolean" ? channel.forwardToolCalls : false;
   const richInteractions =
     typeof channel.richInteractions === "boolean" ? channel.richInteractions : false;
+  const awarenessNote =
+    typeof channel.awarenessNote === "boolean" ? channel.awarenessNote : false;
 
   return {
     accountId: DEFAULT_ACCOUNT_ID,
@@ -508,6 +514,7 @@ export function resolveOpenclawClawlingAccount(
     forwardThinking,
     forwardToolCalls,
     richInteractions,
+    awarenessNote,
     allowFrom: [],
     reconnect: readReconnect(channel.reconnect),
     heartbeat: readHeartbeat(channel.heartbeat),

package/src/friend-request-turn.ts

@@ -0,0 +1,87 @@
+/**
+ * Synthetic reasoning-turn builder for `friend.request` notify.signal events.
+ *
+ * When the server fires a `friend.request` signal the runtime dispatches one
+ * deduped synthetic `message.send` envelope so the agent can reason about the
+ * pending request. The prompt text varies by the current "friend.add" permission
+ * policy state: a deny policy yields a decline/inform prompt; ask or allow
+ * yields a prompt that instructs the agent to review the request via the
+ * `clawchat_list_friend_requests` tool.
+ */
+import { EVENT, type Envelope } from "./protocol-types.ts";
+import type { PermState } from "./permissions.ts";
+import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+
+/**
+ * Returns canned prompt text for a friend-request reasoning turn based on the
+ * current "friend.add" permission policy state.
+ *
+ * - `deny`  → inform the agent it should decline; no accept instruction.
+ * - `ask` / `allow` → instruct the agent to review the pending request.
+ */
+export function friendRequestPromptFor(state: PermState): string {
+  if (state === "deny") {
+    return [
+      "A new friend request has arrived.",
+      "Your current friend-add policy is set to deny.",
+      "Do not add this contact.",
+      "You may inform the requester that you cannot add them at this time.",
+    ].join(" ");
+  }
+  return [
+    "A new friend request has arrived.",
+    "Please review the pending request by calling `clawchat_list_friend_requests`",
+    "and decide whether to accept it.",
+  ].join(" ");
+}
+
+export interface BuildFriendRequestEnvelopeParams {
+  account: ResolvedOpenclawClawlingAccount;
+  /** Current "friend.add" permission policy state. */
+  state: PermState;
+  /** entity_id from the notify.signal payload (the requesting user). */
+  entityId: string;
+}
+
+/**
+ * Builds a synthetic `message.send` envelope that triggers one agent reasoning
+ * turn for a pending friend request. The envelope shape mirrors the
+ * activation-bootstrap envelope; it targets the owner's direct conversation so
+ * the agent has context about who it is reasoning for.
+ */
+export function buildFriendRequestEnvelope(
+  params: BuildFriendRequestEnvelopeParams,
+): Envelope {
+  const { account, state, entityId } = params;
+  const text = friendRequestPromptFor(state);
+  const now = Date.now();
+  return {
+    version: "2",
+    event: EVENT.MESSAGE_SEND,
+    trace_id: `clawchat-plugin-openclaw-friend-request-${entityId}-${now}`,
+    emitted_at: now,
+    chat_id: account.ownerUserId,
+    chat_type: "direct",
+    to: { id: account.userId, type: "direct" },
+    sender: {
+      id: "clawchat-friend-request",
+      type: "direct",
+      nick_name: "ClawChat",
+    },
+    payload: {
+      message_id: `clawchat-plugin-openclaw-friend-request-${entityId}-${now}`,
+      message_mode: "normal",
+      message: {
+        body: { fragments: [{ kind: "text", text }] },
+        context: { mentions: [], reply: null },
+        streaming: {
+          status: "static",
+          sequence: 0,
+          mutation_policy: "sealed",
+          started_at: null,
+          completed_at: null,
+        },
+      },
+    },
+  };
+}

package/src/gate-outcome.ts

@@ -0,0 +1,44 @@
+/**
+ * Maps backend owner-approval gate codes to structured tool outcomes.
+ *
+ * Backend gate codes (confirmed live contract):
+ *   21001 — pending owner approval (payload: { request_id, operation, expires_at })
+ *   21003 — policy forbidden       (payload: { operation })
+ *
+ * Returns null for any other code so callers can fall through to normal handling.
+ */
+
+export type PendingApprovalOutcome = {
+  status: "pending_owner_approval";
+  request_id: string;
+  operation: string;
+  expires_at: number;
+};
+
+export type ForbiddenOutcome = {
+  status: "forbidden_by_owner";
+  operation: string;
+};
+
+export type GateOutcome = PendingApprovalOutcome | ForbiddenOutcome;
+
+export function mapGateOutcome(
+  code: number,
+  data: Record<string, unknown>,
+): GateOutcome | null {
+  if (code === 21001) {
+    return {
+      status: "pending_owner_approval",
+      request_id: typeof data.request_id === "string" ? data.request_id : "",
+      operation: typeof data.operation === "string" ? data.operation : "",
+      expires_at: typeof data.expires_at === "number" ? data.expires_at : 0,
+    };
+  }
+  if (code === 21003) {
+    return {
+      status: "forbidden_by_owner",
+      operation: typeof data.operation === "string" ? data.operation : "",
+    };
+  }
+  return null;
+}

package/src/inbound.ts

@@ -8,6 +8,7 @@ import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
 import type { MediaItem } from "./media-runtime.ts";
 import { extractMediaFragments, fragmentsToText, type MentionedUser } from "./message-mapper.ts";
 import { hasRenderableText, isInboundMessagePayload } from "./protocol.ts";
+import type { PermissionResultMetadata } from "./permission-result.ts";
 
 export interface IngestTurnParams {
   channel: "clawchat-plugin-openclaw";
@@ -81,6 +82,20 @@ export interface DispatchInboundParams {
     text: string;
     chatId: string;
   }) => Promise<boolean>;
+  /**
+   * Optional consumer for `permission_result` system-message receipts.
+   *
+   * When `sender.id === "system"` and `payload.metadata.kind ===
+   * "permission_result"`, the guard calls this callback with the metadata
+   * object instead of performing the generic system-message drop. The
+   * callback is responsible for deduplication and synthetic-turn dispatch
+   * (see `src/permission-result.ts`).
+   *
+   * When absent, `permission_result` frames fall through to the existing
+   * system-message drop (safe default — no regression for callers that have
+   * not yet wired the consumer).
+   */
+  consumePermissionResult?: (metadata: PermissionResultMetadata) => Promise<void>;
   log?: { info?: (m: string) => void; error?: (m: string) => void };
 }
 
@@ -241,6 +256,19 @@ export async function dispatchOpenclawClawlingInbound(
     return;
   }
   if (sender.id === "system") {
+    // Intercept `permission_result` receipts before the generic system-message
+    // drop. The discriminator is `payload.metadata.kind === "permission_result"`;
+    // all other system messages (group-join notifications, etc.) still drop.
+    const rawPayload = envelope.payload as Record<string, unknown>;
+    const meta = rawPayload.metadata as Record<string, unknown> | undefined;
+    if (
+      params.consumePermissionResult &&
+      meta != null &&
+      meta.kind === "permission_result"
+    ) {
+      await params.consumePermissionResult(meta as unknown as PermissionResultMetadata);
+      return;
+    }
     log?.info?.(
       `[${account.accountId}] clawchat-plugin-openclaw skip system message msg=${payload.message_id}`,
     );

package/src/permission-result.ts

@@ -0,0 +1,128 @@
+/**
+ * Consumer for `permission_result` system-message receipts.
+ *
+ * When the backend delivers a `permission_result` outcome as a
+ * `message.send` system frame (`sender.id="system"`, `payload.metadata.kind
+ * ="permission_result"`), this module deduplicates by `request_id` and
+ * produces a synthetic context-note turn so the agent can close the loop
+ * on the original permission request.
+ *
+ * Wire shape (authoritative):
+ * ```
+ * payload.metadata = {
+ *   kind: "permission_result",
+ *   operation: "friend.add",
+ *   outcome: "approved" | "denied" | "expired" | "failed",
+ *   reason: "owner_allowed" | …,
+ *   request_id: "prq_…",
+ * }
+ * ```
+ * The discriminator is `payload.metadata.kind === "permission_result"`.
+ */
+import { EVENT, type Envelope } from "./protocol-types.ts";
+import type { ResolvedOpenclawClawlingAccount } from "./config.ts";
+
+export interface PermissionResultMetadata {
+  kind: "permission_result";
+  operation: string;
+  outcome: "approved" | "denied" | "expired" | "failed";
+  reason: string;
+  request_id: string;
+}
+
+// Module-level dedup set — `request_id` values are stable backend identifiers.
+// A duplicate receipt (e.g. from WS replay on reconnect) must not re-trigger
+// an agent turn.
+const _seenRequestIds = new Set<string>();
+
+/**
+ * @internal Test helper — reset the dedup set between isolated test runs.
+ * Never call this in production code.
+ */
+export function _resetPermissionResultDedup(): void {
+  _seenRequestIds.clear();
+}
+
+function buildOutcomeNote(metadata: PermissionResultMetadata): string {
+  const { operation, outcome, reason } = metadata;
+  const outcomeLabel =
+    outcome === "approved"
+      ? "approved"
+      : outcome === "denied"
+        ? "denied"
+        : outcome === "expired"
+          ? "expired"
+          : "failed";
+  const resolution =
+    outcome === "approved"
+      ? "The requested action has been completed."
+      : "No further action was taken.";
+  return [
+    `Permission request for operation "${operation}" has been ${outcomeLabel}.`,
+    `Reason: ${reason}.`,
+    resolution,
+  ].join(" ");
+}
+
+/**
+ * Builds a synthetic `message.send` envelope that delivers a
+ * `permission_result` context note to the agent.
+ *
+ * Mirrors the `buildFriendRequestEnvelope` pattern: a synthetic inbound
+ * `message.send` targeting the owner's direct conversation, routed through
+ * `handleInboundEnvelope` so the agent can reason about the outcome.
+ */
+export function buildPermissionResultEnvelope(params: {
+  account: Pick<ResolvedOpenclawClawlingAccount, "userId" | "ownerUserId">;
+  metadata: PermissionResultMetadata;
+}): Envelope {
+  const { account, metadata } = params;
+  const text = buildOutcomeNote(metadata);
+  const now = Date.now();
+  return {
+    version: "2",
+    event: EVENT.MESSAGE_SEND,
+    trace_id: `clawchat-plugin-openclaw-permission-result-${metadata.request_id}-${now}`,
+    emitted_at: now,
+    chat_id: account.ownerUserId,
+    chat_type: "direct",
+    to: { id: account.userId, type: "direct" },
+    sender: {
+      id: "clawchat-permission-result",
+      type: "direct",
+      nick_name: "ClawChat",
+    },
+    payload: {
+      message_id: `clawchat-plugin-openclaw-permission-result-${metadata.request_id}-${now}`,
+      message_mode: "normal",
+      message: {
+        body: { fragments: [{ kind: "text", text }] },
+        context: { mentions: [], reply: null },
+        streaming: {
+          status: "static",
+          sequence: 0,
+          mutation_policy: "sealed",
+          started_at: null,
+          completed_at: null,
+        },
+      },
+    },
+  };
+}
+
+/**
+ * Handles a `permission_result` receipt. Deduplicates by `request_id`
+ * (idempotent — WS replay on reconnect may deliver the same receipt again).
+ *
+ * Returns a synthetic context-note {@link Envelope} on a fresh receipt so
+ * the caller can feed it to `handleInboundEnvelope`; returns `null` when
+ * the `request_id` has already been processed.
+ */
+export function handlePermissionResult(
+  metadata: PermissionResultMetadata,
+  account: Pick<ResolvedOpenclawClawlingAccount, "userId" | "ownerUserId">,
+): Envelope | null {
+  if (_seenRequestIds.has(metadata.request_id)) return null;
+  _seenRequestIds.add(metadata.request_id);
+  return buildPermissionResultEnvelope({ account, metadata });
+}

package/src/permissions.ts

@@ -0,0 +1,13 @@
+export type PermState = "ask" | "allow" | "deny";
+
+export interface PermissionPolicy {
+  byOperation: Record<string, PermState>;
+  momentVisibility: string[];
+}
+
+export class PermissionCache {
+  private p: PermissionPolicy = { byOperation: {}, momentVisibility: [] };
+  get(): PermissionPolicy { return this.p; }
+  set(p: PermissionPolicy): void { this.p = p; }
+  stateOf(op: string): PermState { return this.p.byOperation[op] ?? "ask"; }
+}

package/src/reply-dispatcher.ts

@@ -375,6 +375,8 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
   dispatcher: TypedReplyDispatcherResult["dispatcher"];
   replyOptions: ClawChatReplyOptions;
   markDispatchIdle: TypedReplyDispatcherResult["markDispatchIdle"];
+  /** Number of outbound messages actually delivered to the target so far. */
+  getOutboundDeliveredCount: () => number;
 } {
   const {
     cfg,
@@ -430,6 +432,12 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
   let typingActive = false;
   let terminalReplySuppressed = false;
   let finalDeliverySeen = false;
+  // Count of outbound messages that were actually delivered to the target
+  // (a real, successful send — not a suppressed/duplicate/failed one). This is
+  // the reliable "did anything actually reach the user?" signal; host-side
+  // `counts.block`/`counts.final` only reflect what the agent emitted, not
+  // whether the send succeeded (a cancelled send still counts as a block).
+  let outboundDeliveredCount = 0;
 
   const outboundEventType = () => (replyCtx ? "message.reply" : "message.send");
   const outboundRaw = () => ({ target, replyCtx: replyCtx ?? null });
@@ -646,6 +654,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
       log,
     });
     recordOutboundAck("message", messageId, result);
+    if (result) outboundDeliveredCount += 1;
     log?.info?.(
       `[${account.accountId}] clawchat-plugin-openclaw send complete to=${target.chatId}`,
     );
@@ -835,6 +844,7 @@ export function createOpenclawClawlingReplyDispatcher(options: ReplyDispatcherOp
 
   return {
     dispatcher: base.dispatcher,
+    getOutboundDeliveredCount: () => outboundDeliveredCount,
     replyOptions: {
       ...base.replyOptions,
       sourceReplyDeliveryMode: "automatic",