@dcrays/dcgchat-test 0.6.8 → 0.6.12

package/src/tools/messageTool.ts

@@ -0,0 +1,334 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { AnyAgentTool } from 'openclaw/plugin-sdk'
+import { jsonResult } from 'openclaw/plugin-sdk/channel-actions'
+import { sendDcgchatMedia } from '..//channel/index.js'
+import { isSessionActiveForTool } from '../tool.js'
+import { dcgLogger } from '../utils/log.js'
+import { getOutboundMsgParams } from '../utils/params.js'
+import { emitOutboundAssistantText } from '../utils/outboundAssistantText.js'
+import { mediaPathDedupeKey } from '../utils/global.js'
+import { expandTildePath } from '../utils/workspaceFilePaths.js'
+import { hasCronSessionKeyMap, normalizeSessionTarget } from '../channel/outboundTarget.js'
+
+/** 与 `registerTool` 工厂入参一致（主包未导出 `OpenClawPluginToolContext` 时仅用所需字段）。 */
+export type DcgchatMessageToolContext = {
+  sessionKey?: string
+  workspaceDir?: string
+  allowedPaths?: string[]
+  /** 通道配置 `allowedAttachmentExtensions`：在插件内置扩展名之外额外允许发送的附件后缀（如 `.py`、`.ipynb`），项可写 `.py` 或 `py`。 */
+  allowedAttachmentExtensions?: string[]
+  deliveryContext?: { to?: string }
+}
+
+/** 统一为 POSIX 风格斜杠，便于跨平台判断（不改变语义，仅用于匹配）。 */
+function toPosixPath(p: string): string {
+  return path.normalize(p.trim()).replace(/\\/g, '/')
+}
+
+/** `filepath` 解析后在 `rootDir` 内或等于 `rootDir`（防 `..` 逃逸）。 */
+function isPathInsideDir(filepath: string, rootDir: string): boolean {
+  const root = path.resolve(rootDir)
+  const resolved = path.resolve(filepath)
+  const rel = path.relative(root, resolved)
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return false
+  return true
+}
+
+/**
+ * 允许发送的路径：
+ * - 当前 Agent 工作区根及其子路径（`workspaceDir`，如 ~/.openclaw/workspace-xxx/output/...）；
+ * - 兼容旧挂载：Unix `/workspace`、`/mobook`；Windows 盘符下 `workspace`、`mobook`。
+ */
+function isSafePath(filepath: string, workspaceDir?: string, allowedPaths?: string[]): boolean {
+  // Check workspaceDir
+  const ws = workspaceDir?.trim()
+  if (ws && isPathInsideDir(filepath, ws)) return true
+
+  // Check allowedPaths from config
+  if (allowedPaths?.length) {
+    for (const allowed of allowedPaths) {
+      if (isPathInsideDir(filepath, allowed)) return true
+    }
+  }
+
+  // Check legacy mounts
+  const p = toPosixPath(filepath)
+  if (p.startsWith('/workspace/') || p === '/workspace') return true
+  if (p.startsWith('/mobook/') || p === '/mobook') return true
+  return p.includes('mobook') || p.includes('workspace')
+}
+
+/** 同一路径在 Windows 上可能大小写不同；媒体 key 与 channel/global 出站去重对齐 */
+function pathKey(filepath: string): string {
+  return mediaPathDedupeKey(filepath.trim())
+}
+
+const fileType1 = ['.webp', '.gif', '.bmp', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx', '.pdf', '.txt', '.rtf', '.odt', '.json']
+const fileType2 = [
+  '.xml',
+  '.csv',
+  '.yaml',
+  '.yml',
+  '.html',
+  '.htm',
+  '.md',
+  '.markdown',
+  '.css',
+  '.js',
+  '.ts',
+  '.py',
+  '.pyi',
+  '.ipynb',
+  '.png',
+  '.jpg',
+  '.jpeg'
+]
+const fileType3 = ['.zip', '.rar', '.7z', '.tar', '.gz', '.bz2', '.xz', '.exe', '.dmg', '.pkg', '.apk', '.ipa', '.log', '.dat', '.bin']
+const fileType4 = ['.svg', '.ico', '.mp3', '.wav', '.ogg', '.aac', '.m4a', '.mp4', '.avi', '.mov', '.wmv', '.flv', '.mkv', '.webm']
+const DEFAULT_SAFE_EXTENSIONS = new Set([...fileType1, ...fileType2, ...fileType3, ...fileType4])
+
+function normalizeAttachmentExt(raw: string): string | null {
+  const t = raw.trim().toLowerCase()
+  if (!t) return null
+  return t.startsWith('.') ? t : `.${t}`
+}
+
+function buildSafeExtensions(extra?: string[]): Set<string> {
+  const set = new Set(DEFAULT_SAFE_EXTENSIONS)
+  for (const e of extra ?? []) {
+    const n = normalizeAttachmentExt(e)
+    if (n && n !== '.') set.add(n)
+  }
+  return set
+}
+
+type DcgchatMessageToolArgs = {
+  target?: string
+  content?: string
+  media?: { file?: string }[]
+}
+
+const messageToolParameters = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    target: {
+      type: 'string',
+      description: '目标会话键（sessionKey），必须与当前会话 SessionKey 一致，禁止填写 userId。'
+    },
+    content: {
+      type: 'string',
+      description: '发送文本内容'
+    },
+    media: {
+      type: 'array',
+      description: '发送附件',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          file: {
+            type: 'string',
+            description:
+              '文件绝对路径：须在「当前 Agent 工作区」目录下（如 /root/.openclaw/workspace-xxx/output/28337/slices_result.json），或为兼容环境的 /workspace/、/mobook/（Windows 盘符下 workspace、mobook）'
+          }
+        },
+        required: ['file']
+      }
+    }
+  },
+  // 须至少提供正文或附件之一；用 anyOf（非 oneOf），否则同时带 content+media 时两个分支都满足会违反「恰好其一」而校验失败
+  anyOf: [{ required: ['content'] }, { required: ['media'] }]
+}
+
+/** 从正文提取可发送的文件路径（固定挂载 + 当前工作区前缀）。 */
+function extractPaths(text: string | undefined, workspaceDir?: string): string[] {
+  if (!text) return []
+  const unix = text.match(/\/workspace\/[^\s]+|\/mobook\/[^\s]+/g) ?? []
+  const win = text.match(/[A-Za-z]:[/\\](?:workspace|mobook)[/\\][^\s]+/g) ?? []
+  const underWs: string[] = []
+  const ws = workspaceDir?.trim()
+  if (ws) {
+    const variants = new Set<string>()
+    variants.add(ws)
+    variants.add(toPosixPath(ws))
+    if (path.sep === '\\') variants.add(ws.replace(/\//g, '\\'))
+    for (const prefix of variants) {
+      if (!prefix) continue
+      let from = 0
+      while (from < text.length) {
+        const i = text.indexOf(prefix, from)
+        if (i === -1) break
+        let end = i + prefix.length
+        while (end < text.length && !/\s/.test(text[end])) end++
+        underWs.push(text.slice(i, end))
+        from = i + 1
+      }
+    }
+  }
+  return [...new Set([...unix, ...win, ...underWs])]
+}
+
+function isSafeFile(filepath: string, extensions: Set<string>) {
+  if (!fs.existsSync(filepath)) return false
+  const stat = fs.statSync(filepath)
+  if (!stat.isFile()) return false
+  if (stat.size === 0) return false
+  const ext = path.extname(filepath).toLowerCase()
+  return extensions.has(ext)
+}
+
+function getSessionKey(pluginCtx: DcgchatMessageToolContext): string {
+  const { sessionKey = '', deliveryContext } = pluginCtx
+  const isCron = sessionKey?.indexOf(':cron:') >= 0
+  if (isCron) {
+    return normalizeSessionTarget(deliveryContext?.to ?? '')
+  }
+  return sessionKey
+}
+
+/**
+ * 书灵墨宝出站消息工具：须符合 OpenClaw `AgentTool`（execute 返回 `AgentToolResult`）。
+ * 工具名使用 `dcgchat_message`，避免与核心内置 `message` 冲突。
+ * 通过注册时的 `OpenClawPluginToolContext.sessionKey` 出站，不再使用非标准的 `execute(args, ctx)`。
+ */
+export function createDcgchatMessageTool(pluginCtx: DcgchatMessageToolContext): AnyAgentTool {
+  const safeExtensions = buildSafeExtensions(pluginCtx.allowedAttachmentExtensions)
+  return {
+    name: 'dcgchat_message',
+    label: 'dcgchat_message',
+    description: `
+      向用户发送消息。
+      若传 target，target 必须是 sessionKey，不能是 userId。
+      如果发送附件：必须使用 media 字段（不依赖 inline buttons，勿要求用户开启 channels.*.capabilities.inlineButtons）。
+      文件路径须在当前 Agent 工作区目录下（随部署变化，如 ~/.openclaw/workspace-xxx/...），或为兼容环境的 /workspace/、/mobook/（Windows 盘符下 workspace、mobook）。
+      禁止在正文中直接输出可访问路径（应通过 media 发送）
+    `,
+    parameters: messageToolParameters,
+    execute: async (_toolCallId, args, signal) => {
+      const toolArgs = args as DcgchatMessageToolArgs
+      if (signal?.aborted) {
+        const err = new Error('Message send aborted')
+        err.name = 'AbortError'
+        throw err
+      }
+
+      const sessionKey = getSessionKey(pluginCtx)
+      if (!sessionKey) {
+        dcgLogger(`dcgchat_message: missing sessionKey, cannot send message`, 'error')
+        // terminate：避免宿主在会话已结束后仍多轮调用模型重试 message，产生无效 token
+        return { ...jsonResult({ error: '缺少 sessionKey，无法向当前会话发送消息' }), terminate: true }
+      }
+      const isCronSessionKey = hasCronSessionKeyMap(sessionKey)
+      // 与 channel.outbound.sendText 一致：无活跃入站轮次则不下发。否则 /stop 或 sendFinal 之后，
+      // 网关里晚结束的 run 仍会调起 message 工具，getOutboundMsgParams 已指向**新**用户 messageId，造成旧回复错挂到后一条上。
+      if (!isCronSessionKey && !isSessionActiveForTool(sessionKey)) {
+        dcgLogger(`dcgchat_message: skipped (session not active, likely stale run after /stop or turn end): ${sessionKey}`)
+        return {
+          ...jsonResult({
+            success: false,
+            error: '当前会话无活跃入站轮次，已忽略发送；会话已结束，请勿再调用本工具。'
+          }),
+          terminate: true
+        }
+      }
+
+      try {
+        const sentFiles = new Set<string>()
+        const sentKeys = new Set<string>()
+        const workspaceDir = pluginCtx.workspaceDir
+        const allowedPaths = pluginCtx.allowedPaths
+        const mediaText = (toolArgs.content ?? '').trim()
+        let contentSentWithMedia = false
+
+        if (toolArgs.media?.length) {
+          const mediaUrls = []
+          for (const media of toolArgs.media) {
+            if (!media.file) continue
+            const filepath = expandTildePath(media.file)
+            if (!isSafePath(filepath, workspaceDir, allowedPaths)) continue
+            if (!isSafeFile(filepath, safeExtensions)) continue
+            const key = pathKey(filepath)
+            if (sentKeys.has(key)) continue
+
+            mediaUrls.push(filepath)
+            sentFiles.add(filepath)
+            sentKeys.add(key)
+          }
+          if (mediaUrls.length > 0) {
+            const text = isCronSessionKey && !contentSentWithMedia ? mediaText : undefined
+            if (text) contentSentWithMedia = true
+
+            await sendDcgchatMedia({ sessionKey, mediaUrls, text })
+          }
+        }
+
+        const fallbackPaths = extractPaths(toolArgs.content, workspaceDir)
+        const mediaUrls = []
+        for (const filepath of fallbackPaths) {
+          const normalizedFilepath = expandTildePath(filepath)
+          if (!isSafePath(normalizedFilepath, workspaceDir, allowedPaths)) {
+            dcgLogger(`非法路径：${normalizedFilepath}`, 'error')
+            continue
+          }
+          if (!isSafeFile(normalizedFilepath, safeExtensions)) {
+            dcgLogger(`非法文件类型：${normalizedFilepath}`, 'error')
+            continue
+          }
+          const key = pathKey(normalizedFilepath)
+          if (sentKeys.has(key)) continue
+
+          mediaUrls.push(normalizedFilepath)
+          sentFiles.add(normalizedFilepath)
+          sentKeys.add(key)
+        }
+        if (mediaUrls.length > 0) {
+          const text = isCronSessionKey && !contentSentWithMedia ? mediaText : undefined
+          if (text) contentSentWithMedia = true
+          await sendDcgchatMedia({ sessionKey, mediaUrls, text })
+        }
+
+        if (toolArgs.media?.length && sentFiles.size === 0) {
+          dcgLogger(`dcgchat_message: no media sent`, 'error')
+          return jsonResult({
+            success: false,
+            error:
+              '未能发送任何附件：路径须位于当前 Agent 工作区，或为 /workspace/、/mobook/ 下的真实文件（非空、扩展名在白名单内）。',
+            sentMediaCount: 0
+          })
+        }
+
+        let content = toolArgs.content ?? ''
+        for (const filepath of sentFiles) {
+          const posix = toPosixPath(filepath)
+          const variants = posix === filepath ? [filepath] : [filepath, posix]
+          const seen = new Set<string>()
+          for (const v of variants) {
+            if (!v || seen.has(v)) continue
+            seen.add(v)
+            content = content.split(v).join('')
+          }
+        }
+        content = content.trim()
+        if (contentSentWithMedia) content = ''
+
+        // 与 bot onPartialReply/deliver 共用 outboundAssistantText 快照增量，避免双发；NO_REPLY 场景由工具兜底正文
+        if (content.length > 0 && content !== 'NO_REPLY') {
+          const msgCtx = getOutboundMsgParams(sessionKey)
+          emitOutboundAssistantText(sessionKey, content, msgCtx)
+        }
+
+        return jsonResult({
+          success: true,
+          sentMediaCount: sentFiles.size
+        })
+      } catch (err) {
+        dcgLogger(`dcgchat_message: failed: ${String(err)}`, 'error')
+        return jsonResult({
+          error: err instanceof Error ? err.message : String(err)
+        })
+      }
+    }
+  }
+}

package/src/tools/toolCallGuard.ts

@@ -0,0 +1,327 @@
+import { mediaPathDedupeKey } from '../utils/global.js'
+import { dcgLogger } from '../utils/log.js'
+import { expandTildePath } from '../utils/workspaceFilePaths.js'
+
+const LOG_TAG = 'tool-call-guard'
+
+/** 与 OpenClaw `PluginHookBeforeToolCallResult` 对齐 */
+export type DcgchatBeforeToolCallHookResult = {
+  params?: Record<string, unknown>
+  block?: boolean
+  blockReason?: string
+}
+
+const MAX_TRACKED_RUNS = 200
+
+/** runId → 已下发的 message 正文 */
+const sentMessageTextByRunId = new Map<string, Set<string>>()
+/** runId → 已下发的 message 附件路径（规范化） */
+const sentMessageFileByRunId = new Map<string, Set<string>>()
+/** runId → 上一笔已成功完成的 FS 操作键（tool + 文件；仅拦截与上一笔相同的连续重复） */
+const lastCompletedFsOpByRunId = new Map<string, string>()
+
+const FS_LOOP_TOOLS = new Set(['read', 'write', 'edit', 'apply_patch'])
+const TERMINATE_BLOCK_REASON = 'Tool round ended for this session (no active inbound turn). Do not retry; reply with NO_REPLY only.'
+
+function pruneRunMap<T>(map: Map<string, T>, runId: string, factory: () => T): T {
+  let entry = map.get(runId)
+  if (!entry) {
+    if (map.size >= MAX_TRACKED_RUNS) {
+      const oldest = map.keys().next().value
+      if (oldest) map.delete(oldest)
+    }
+    entry = factory()
+    map.set(runId, entry)
+  }
+  return entry
+}
+
+function mergeBeforeToolCallResults(
+  ...results: Array<DcgchatBeforeToolCallHookResult | undefined>
+): DcgchatBeforeToolCallHookResult | undefined {
+  let paramsPatch: Record<string, unknown> | undefined
+  for (const r of results) {
+    if (!r) continue
+    if (r.block) return r
+    if (r.params) paramsPatch = r.params
+  }
+  return paramsPatch ? { params: paramsPatch } : undefined
+}
+
+function isBuiltinMessageTool(toolName: string): boolean {
+  return toolName === 'message'
+}
+
+function isDcgchatMessageTool(toolName: string): boolean {
+  return toolName === 'dcgchat_message'
+}
+
+function isOutboundMessagingTool(toolName: string): boolean {
+  return isBuiltinMessageTool(toolName) || isDcgchatMessageTool(toolName)
+}
+
+function isMessageSendAction(params: Record<string, unknown>): boolean {
+  const action = typeof params.action === 'string' ? params.action.trim().toLowerCase() : 'send'
+  return action === 'send'
+}
+
+function extractMessageSendText(params: Record<string, unknown>): string | null {
+  if (!isMessageSendAction(params)) return null
+  const message = typeof params.message === 'string' ? params.message.trim() : ''
+  return message || null
+}
+
+function extractDcgchatMessageSendText(params: Record<string, unknown>): string | null {
+  const content = typeof params.content === 'string' ? params.content.trim() : ''
+  if (!content || content === 'NO_REPLY') return null
+  return content
+}
+
+function extractDcgchatMessageSendFileKeys(params: Record<string, unknown>): string[] {
+  const media = params.media
+  if (!Array.isArray(media)) return []
+  const keys: string[] = []
+  for (const item of media) {
+    if (!item || typeof item !== 'object') continue
+    const file = (item as { file?: string }).file
+    if (typeof file === 'string' && file.trim()) {
+      const k = mediaPathDedupeKey(file.trim())
+      if (k) keys.push(k)
+    }
+  }
+  return [...new Set(keys)]
+}
+
+function extractOutboundMessagingText(toolName: string, params: Record<string, unknown>): string | null {
+  if (isBuiltinMessageTool(toolName)) return extractMessageSendText(params)
+  if (isDcgchatMessageTool(toolName)) return extractDcgchatMessageSendText(params)
+  return null
+}
+
+function extractOutboundMessagingFileKeys(toolName: string, params: Record<string, unknown>): string[] {
+  if (isBuiltinMessageTool(toolName)) return extractMessageSendFileKeys(params)
+  if (isDcgchatMessageTool(toolName)) return extractDcgchatMessageSendFileKeys(params)
+  return []
+}
+
+function isOutboundMessagingSend(toolName: string, params: Record<string, unknown>): boolean {
+  return extractOutboundMessagingText(toolName, params) !== null || extractOutboundMessagingFileKeys(toolName, params).length > 0
+}
+
+/** 内置 message 的 filePath / path / media[].file */
+function extractMessageSendFileKeys(params: Record<string, unknown>): string[] {
+  if (!isMessageSendAction(params)) return []
+  const keys: string[] = []
+  for (const field of ['filePath', 'path'] as const) {
+    const v = params[field]
+    if (typeof v === 'string' && v.trim()) {
+      const k = mediaPathDedupeKey(v.trim())
+      if (k) keys.push(k)
+    }
+  }
+  const media = params.media
+  if (Array.isArray(media)) {
+    for (const item of media) {
+      if (!item || typeof item !== 'object') continue
+      const file = (item as { file?: string }).file
+      if (typeof file === 'string' && file.trim()) {
+        const k = mediaPathDedupeKey(file.trim())
+        if (k) keys.push(k)
+      }
+    }
+  }
+  return [...new Set(keys)]
+}
+
+/**
+ * 会话非 running 时仍须执行 `before_tool_call` + guard（由 tool.ts 外层门控调用）。
+ * 仅出站 `message(send)` 需要拦截；其它 message 动作无需放行。
+ */
+export function shouldRunBeforeToolCallGuardWhenSessionInactive(event: {
+  toolName?: string
+  params?: Record<string, unknown>
+}): boolean {
+  const toolName = event.toolName?.trim()
+  if (!toolName || !isOutboundMessagingTool(toolName)) return false
+  return isOutboundMessagingSend(toolName, event.params ?? {})
+}
+
+function stableJsonKey(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value)
+  if (Array.isArray(value)) return `[${value.map(stableJsonKey).join(',')}]`
+  const obj = value as Record<string, unknown>
+  const keys = Object.keys(obj).sort()
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableJsonKey(obj[k])}`).join(',')}}`
+}
+
+const FS_PATH_FIELDS = ['path', 'filePath', 'file_path', 'file'] as const
+
+function normalizeFsPathParam(params: Record<string, unknown>): string | null {
+  for (const field of FS_PATH_FIELDS) {
+    const v = params[field]
+    if (typeof v === 'string' && v.trim()) {
+      const key = mediaPathDedupeKey(expandTildePath(v.trim()))
+      if (key) return key
+    }
+  }
+  return null
+}
+
+function fsReadRangeKey(params: Record<string, unknown>): string {
+  const offset = params.offset ?? params.startLine ?? ''
+  const limit = params.limit ?? params.endLine ?? ''
+  return `${String(offset)}:${String(limit)}`
+}
+
+/**
+ * 防循环操作键：同一工具 + 同一文件（read 另含 offset/limit）。
+ * 中间插入其它工具调用后会更新 last，允许对同文件再次执行同类操作。
+ */
+function fsLoopOpKey(toolName: string, params: Record<string, unknown>): string | null {
+  if (!FS_LOOP_TOOLS.has(toolName)) return null
+  const pathKey = normalizeFsPathParam(params)
+  if (toolName === 'read') {
+    if (!pathKey) return `read:${stableJsonKey(params)}`
+    return `read:${pathKey}:${fsReadRangeKey(params)}`
+  }
+  if (pathKey) return `${toolName}:${pathKey}`
+  return `${toolName}:${stableJsonKey(params)}`
+}
+
+function setLastCompletedFsOp(runId: string, opKey: string): void {
+  if (lastCompletedFsOpByRunId.size >= MAX_TRACKED_RUNS && !lastCompletedFsOpByRunId.has(runId)) {
+    const oldest = lastCompletedFsOpByRunId.keys().next().value
+    if (oldest) lastCompletedFsOpByRunId.delete(oldest)
+  }
+  lastCompletedFsOpByRunId.set(runId, opKey)
+}
+
+function clearLastCompletedFsOp(runId: string): void {
+  lastCompletedFsOpByRunId.delete(runId)
+}
+
+function blockDuplicate(kind: string, runId: string, toolCallId: string | undefined, detail: string): DcgchatBeforeToolCallHookResult {
+  dcgLogger(`[${LOG_TAG}] block duplicate ${kind} runId=${runId} toolCallId=${toolCallId ?? ''} ${detail}`, 'log')
+  return {
+    block: true,
+    blockReason:
+      `Duplicate ${kind} in the current agent run (${detail}). ` +
+      'Skip this repeated tool call and continue with other steps; do not retry the same call.'
+  }
+}
+
+function blockTerminateLike(runId: string, toolCallId: string | undefined, toolName: string): DcgchatBeforeToolCallHookResult {
+  dcgLogger(
+    `[${LOG_TAG}] block ${toolName} (session inactive, terminate-equivalent) runId=${runId} toolCallId=${toolCallId ?? ''}`,
+    'log'
+  )
+  return { block: true, blockReason: TERMINATE_BLOCK_REASON }
+}
+
+function isCronSessionKey(sessionKey: string): boolean {
+  return sessionKey.includes(':cron:')
+}
+
+export type ToolCallGuardBeforeContext = {
+  sessionKey: string
+  /** 与 dcgchat_message / channel.sendText 一致：无活跃入站轮次则不应再出站 */
+  sessionActive: boolean
+}
+
+/**
+ * before_tool_call：内置 message（正文/附件）去重；FS 工具仅拦截「与上一笔成功调用相同文件+相同操作」的连续重复；
+ * 无活跃会话时对出站 message 做 terminate 等效 block（对齐 dcgchat_message）。
+ */
+export function toolCallGuardBefore(
+  event: {
+    toolName?: string
+    params?: Record<string, unknown>
+    runId?: string
+    toolCallId?: string
+  },
+  ctx: ToolCallGuardBeforeContext
+): DcgchatBeforeToolCallHookResult | undefined {
+  const toolName = event.toolName?.trim()
+  if (!toolName) return undefined
+
+  const runId = event.runId?.trim()
+  if (!runId) return undefined
+
+  const params = event.params ?? {}
+
+  if (isOutboundMessagingTool(toolName)) {
+    if (isOutboundMessagingSend(toolName, params) && !ctx.sessionActive && !isCronSessionKey(ctx.sessionKey)) {
+      return blockTerminateLike(runId, event.toolCallId, toolName)
+    }
+
+    const text = extractOutboundMessagingText(toolName, params)
+    if (text) {
+      const sent = sentMessageTextByRunId.get(runId)
+      if (sent?.has(text)) {
+        return blockDuplicate(`${toolName} text`, runId, event.toolCallId, `len=${text.length}`)
+      }
+    }
+
+    const fileKeys = extractOutboundMessagingFileKeys(toolName, params)
+    if (fileKeys.length) {
+      const sentFiles = sentMessageFileByRunId.get(runId)
+      for (const fk of fileKeys) {
+        if (sentFiles?.has(fk)) {
+          return blockDuplicate(`${toolName} file`, runId, event.toolCallId, `path=${fk}`)
+        }
+      }
+    }
+    return undefined
+  }
+
+  const opKey = fsLoopOpKey(toolName, params)
+  if (!opKey) return undefined
+
+  if (lastCompletedFsOpByRunId.get(runId) === opKey) {
+    return blockDuplicate(toolName, runId, event.toolCallId, 'consecutive same file operation')
+  }
+  return undefined
+}
+
+/** after_tool_call：登记已成功完成的出站 message / 文件类工具，供后续 before 拦截 */
+export function toolCallGuardAfter(event: {
+  toolName?: string
+  params?: Record<string, unknown>
+  runId?: string
+  error?: string
+}): void {
+  if (event.error) return
+
+  const toolName = event.toolName?.trim()
+  if (!toolName) return
+
+  const runId = event.runId?.trim()
+  if (!runId) return
+
+  const params = event.params ?? {}
+
+  if (isOutboundMessagingTool(toolName)) {
+    const text = extractOutboundMessagingText(toolName, params)
+    if (text) {
+      pruneRunMap(sentMessageTextByRunId, runId, () => new Set()).add(text)
+    }
+    for (const fk of extractOutboundMessagingFileKeys(toolName, params)) {
+      pruneRunMap(sentMessageFileByRunId, runId, () => new Set()).add(fk)
+    }
+    clearLastCompletedFsOp(runId)
+    return
+  }
+
+  const opKey = fsLoopOpKey(toolName, params)
+  if (opKey) {
+    setLastCompletedFsOp(runId, opKey)
+    return
+  }
+  clearLastCompletedFsOp(runId)
+}
+
+export function mergeDcgchatBeforeToolCallHookResults(
+  ...results: Array<DcgchatBeforeToolCallHookResult | undefined>
+): DcgchatBeforeToolCallHookResult | undefined {
+  return mergeBeforeToolCallResults(...results)
+}