deskbuddy 0.1.0 → 0.2.0-beta.0

package/hook/hook.cjs

@@ -22,6 +22,8 @@ const { execFileSync } = require('node:child_process')
 const DEFAULT_API_BASE = process.env.DESKBUDDY_API_BASE || 'https://api.shifengintelli.com'
 const KEEPALIVE_MS = 2 * 60 * 1000
 const MAX_SESSIONS = 20
+/** 状态文件里保留的最近事件条数，与 src/core/state.ts 的 RECENT_MAX 一致 */
+const RECENT_MAX = 8
 const REPORT_TIMEOUT_MS = 2000
 /** ServiceApi 版本，不是包路径里的 v2 */
 const GATEWAY_VERSION = '1.0'
@@ -63,7 +65,16 @@ const FALLBACK_REGISTRY = {
       format: 'cc-hook',
       processNames: ['claude'],
       titleSources: ['cc-ai-title', 'git-branch', 'project'],
-      events: { UserPromptSubmit: 'watch', PreToolUse: 'watch', PostToolUse: 'watch', Stop: 'done' },
+      events: {
+        UserPromptSubmit: 'watch',
+        PreToolUse: 'watch',
+        PostToolUse: 'watch',
+        // 工具跑失败时 Claude Code 发这个而不是 PostToolUse；窗口待批准撤卡也要认它
+        PostToolUseFailure: 'watch',
+        Stop: 'done',
+        // 窗口里弹授权框的那一刻就是待确认（S10），不等之后那条权限通知
+        PermissionRequest: 'ask_approval',
+      },
       lifecycle: { SessionStart: 'ignore', SessionEnd: 'remove' },
     },
     codex: {
@@ -81,6 +92,46 @@ const FALLBACK_REGISTRY = {
       },
       lifecycle: { SessionStart: 'ignore', SessionEnd: 'remove' },
     },
+    workbuddy: {
+      format: 'cc-hook',
+      processNames: ['WorkBuddy'],
+      titleSources: ['git-branch', 'project'],
+      events: {
+        UserPromptSubmit: 'watch',
+        PreToolUse: 'watch',
+        PostToolUse: 'watch',
+        Stop: 'done',
+        PermissionRequest: 'ask_approval',
+      },
+      lifecycle: { SessionStart: 'ignore', SessionEnd: 'remove' },
+    },
+    qoder: {
+      format: 'cc-hook',
+      processNames: ['Qoder CN'],
+      titleSources: ['git-branch', 'project'],
+      events: {
+        UserPromptSubmit: 'watch',
+        PreToolUse: 'watch',
+        PostToolUse: 'watch',
+        Stop: 'done',
+        PermissionRequest: 'ask_approval',
+      },
+      lifecycle: { SessionStart: 'ignore', SessionEnd: 'remove' },
+    },
+    opencode: {
+      format: 'oc-plugin',
+      processNames: ['opencode'],
+      // opencode 自带的会话标题是模型对提问的摘要，违反隐私约束（spec §6.4），不用
+      titleSources: ['git-branch', 'project'],
+      events: {
+        UserPromptSubmit: 'watch',
+        PreToolUse: 'watch',
+        PostToolUse: 'watch',
+        Stop: 'done',
+        PermissionRequest: 'ask_approval',
+      },
+      lifecycle: { SessionEnd: 'remove' },
+    },
   },
 }
 
@@ -429,6 +480,7 @@ function buildSnapshot(states, tool, cfg, nowMs) {
       state: s.state,
       startedAt: s.startedAt,
       updatedAt: s.updatedAt,
+      interactive: s.interactive === true,
     }))
   return { clientId: cfg.clientId, hostName: cfg.hostName, tool: tool, snapshotAt: nowMs, sessions: sessions }
 }
@@ -554,6 +606,172 @@ async function reportIfAuthorized(tool, nowMs) {
   await postReport(cfg, buildSnapshot(readAliveStates(tool), tool, cfg, nowMs))
 }
 
+/**
+ * 工具调用指纹前 16 位，与 src/daemon/gate/approvals.ts 的 fingerprint 同算法。
+ * daemon 靠它认出"跑完的正是设备上等着的那一步"，并行的同名工具不会误撤卡（S10 评审 #2）
+ */
+function toolFingerprint(toolName, toolInput) {
+  let input = ''
+  try {
+    input = JSON.stringify(toolInput === undefined ? null : toolInput)
+  } catch (e) {
+    input = String(toolInput)
+  }
+  return crypto.createHash('sha256').update(toolName).update('\0').update(input).digest('hex').slice(0, 16)
+}
+
+/**
+ * 这个智能体进程是不是【交互窗口】（二期 P1）。参数里有 -p / --print / stream-json / exec 的是
+ * 脚本、SDK 或 daemon 起的远程任务；桌面 App 与终端里的 TUI 是窗口。与 gate.cjs 的 isInteractiveClaude 同一判据。
+ * 🔴 判不出来按 false：false 只意味着"不挡远程指令"，与改动前的行为一致
+ */
+function isInteractiveArgs(args) {
+  const all = String(args || '').trim().split(/\s+/)
+  const tokens = all.slice(1)
+  if (tokens.length === 0) return true
+  // exec 只认 Codex 的子命令位置：`claude "exec the tests"` 这种带提示词启动的窗口不能误判（评审）
+  if (tokens[0] === 'exec' && /codex/i.test(path.basename(all[0]))) return false
+  // opencode 的非交互是 `opencode run …`（二期 P9）；TUI 是 `opencode [目录]`
+  if (tokens[0] === 'run' && /opencode/i.test(path.basename(all[0]))) return false
+  return !tokens.some(
+    (t) =>
+      t === '--print' ||
+      t === 'stream-json' ||
+      t.startsWith('--output-format=stream') ||
+      /^-[a-zA-Z]*p[a-zA-Z]*$/.test(t)
+  )
+}
+
+/** 只看进程在不在（kill 0），不查进程名：每次事件都要调，ps 太贵 */
+function pidExists(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e) {
+    return false
+  }
+}
+
+function detectInteractive(pid) {
+  if (!pid) return false
+  try {
+    const args = execFileSync('ps', ['-ww', '-o', 'args=', '-p', String(pid)], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    return args.trim() !== '' && isInteractiveArgs(args)
+  } catch (e) {
+    return false
+  }
+}
+
+// ---------- /clear 改绑（二期 P2） ----------
+
+/** 与 src/core/state.ts 的 ALIAS_TTL_MS 一致 */
+const ALIAS_TTL_MS = 7 * 24 * 60 * 60 * 1000
+/** SessionEnd(clear) 到 SessionStart(clear) 之间允许的间隔 */
+const CLEAR_PAIR_MS = 60 * 1000
+
+function clearMarkPath(pid) {
+  return path.join(deskbuddyHome(), 'clear', String(pid) + '.json')
+}
+
+/** SessionEnd(reason=clear)：按智能体进程号记下旧会话，等同一进程的 SessionStart(source=clear) 来配对 */
+function markClear(pid, oldSessionId) {
+  try {
+    fs.mkdirSync(path.join(deskbuddyHome(), 'clear'), { recursive: true })
+    fs.writeFileSync(clearMarkPath(pid), JSON.stringify({ old: oldSessionId, at: Date.now() }), 'utf8')
+  } catch (e) {
+    /* 改绑是锦上添花，失败就退回"旧会话失效" */
+  }
+}
+
+/** SessionStart(source=clear)：配对成功就写别名 旧 → 新 */
+function pairClear(pid, newSessionId) {
+  let mark
+  try {
+    mark = JSON.parse(fs.readFileSync(clearMarkPath(pid), 'utf8'))
+    fs.unlinkSync(clearMarkPath(pid))
+  } catch (e) {
+    return
+  }
+  if (!mark || typeof mark.old !== 'string' || !mark.old || mark.old === newSessionId) return
+  if (!(Date.now() - mark.at < CLEAR_PAIR_MS)) return
+  const file = path.join(deskbuddyHome(), 'alias.json')
+  let map = {}
+  try {
+    map = JSON.parse(fs.readFileSync(file, 'utf8')) || {}
+  } catch (e) {
+    map = {}
+  }
+  const now = Date.now()
+  for (const k of Object.keys(map)) {
+    if (!(map[k] && now - map[k].at < ALIAS_TTL_MS)) delete map[k]
+  }
+  map[mark.old] = { to: newSessionId, at: now }
+  try {
+    fs.writeFileSync(file + '.tmp', JSON.stringify(map), 'utf8')
+    fs.renameSync(file + '.tmp', file)
+  } catch (e) {
+    /* 同上 */
+  }
+}
+
+/** 最近目录最多记多少条（二期 P6，与 src/core/dirs.ts 同构；上报只取前 10） */
+const DIRS_KEEP = 30
+
+/** UserPromptSubmit 时记下工作目录：{全路径: 最近使用毫秒}。🔴 全路径只留本机 */
+function recordDir(cwd, now) {
+  if (!cwd) return
+  const file = path.join(deskbuddyHome(), 'dirs.json')
+  let map = {}
+  try {
+    map = JSON.parse(fs.readFileSync(file, 'utf8')) || {}
+  } catch (e) {
+    map = {}
+  }
+  map[cwd] = now
+  const kept = Object.entries(map)
+    .filter((e) => typeof e[1] === 'number')
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, DIRS_KEEP)
+  try {
+    fs.mkdirSync(deskbuddyHome(), { recursive: true })
+    fs.writeFileSync(file + '.tmp', JSON.stringify(Object.fromEntries(kept)), 'utf8')
+    fs.renameSync(file + '.tmp', file)
+  } catch (e) {
+    /* 记不下只影响设备上的目录列表 */
+  }
+}
+
+/** 与 src/core/state.ts 的 NOTICE_TTL_MS 一致 */
+const NOTICE_TTL_MS = 60 * 60 * 1000
+const NOTICE_EVENTS = { PostToolUse: 1, PostToolUseFailure: 1, Stop: 1 }
+
+/**
+ * 窗口回显（S10，见 src/core/state.ts 的 writeNotice）：有就取出并删掉，返回要显示的文字。
+ * 先删再用：并发的两个 hook 最多一个拿到，不会重复显示
+ */
+function takeNotice(sessionId) {
+  const safe = String(sessionId).replace(/[^A-Za-z0-9_-]/g, '')
+  if (!safe) return ''
+  const file = path.join(deskbuddyHome(), 'notice', safe + '.json')
+  let raw
+  try {
+    raw = fs.readFileSync(file, 'utf8')
+    fs.unlinkSync(file)
+  } catch (e) {
+    return ''
+  }
+  try {
+    const n = JSON.parse(raw)
+    if (typeof n.text !== 'string' || !n.text || !(Date.now() - n.at < NOTICE_TTL_MS)) return ''
+    return n.text.slice(0, 300)
+  } catch (e) {
+    return ''
+  }
+}
+
 async function main(argv) {
   // 同一份 hook 被 Claude Code 与 Codex 复用，靠命令行参数区分是哪个工具
   const tool = (argv && argv[2]) || 'claude_code'
@@ -562,10 +780,33 @@ async function main(argv) {
   const sessionId = payload.session_id || ''
   if (!sessionId) return
 
+  if (NOTICE_EVENTS[event]) {
+    const notice = takeNotice(sessionId)
+    // 🔴 writeSync：macOS 上 stdout 是管道时 process.stdout.write 是异步的，进程先退就丢了
+    if (notice) {
+      try {
+        fs.writeSync(1, JSON.stringify({ systemMessage: notice }))
+      } catch (e) {
+        /* 显示不了就算了 */
+      }
+    }
+  }
+
   const registry = loadRegistry()
+
+  // /clear 改绑（二期 P2）：SessionStart 在映射表里是 ignore，要在那之前处理
+  if (event === 'SessionStart' && payload.source === 'clear') {
+    const pid = resolveAgentPid(process.pid, agentNames(registry, tool))
+    if (pid) pairClear(pid, sessionId)
+  }
+
   const action = mapEvent(registry, tool, event, payload)
   if (action === 'ignore') return
   if (action === 'remove') {
+    if (event === 'SessionEnd' && payload.reason === 'clear') {
+      const old = readState(sessionId)
+      if (old && old.pid) markClear(old.pid, sessionId)
+    }
     removeState(sessionId)
     // 删完补发一次剩余会话，否则这条会一直挂在屏上等服务端失联 TTL。
     // 关掉最后一个窗口时发的是空列表——服务端放行空快照，该机器该工具随即从屏上消失
@@ -575,19 +816,41 @@ async function main(argv) {
 
   const prev = readState(sessionId)
   const now = Date.now()
-  const pid = (prev && prev.pid) || resolveAgentPid(process.pid, agentNames(registry, tool)) || undefined
+  if (event === 'UserPromptSubmit') recordDir(payload.cwd, now)
+  // 状态里记的进程还活着才沿用（评审）：先远程 -p 跑过、后又在窗口 resume 同一会话时，
+  // 不能拿死掉的 -p 进程的 interactive=false 挡不住窗口
+  const prevAlive = !!(prev && prev.pid && pidExists(prev.pid))
+  const pid = (prevAlive && prev.pid) || resolveAgentPid(process.pid, agentNames(registry, tool)) || undefined
   const next = {
     sessionId: sessionId,
     tool: tool,
     // 标题要读文件，只在真正上报时才取（见下面）；这里先沿用上一次的
     title: (prev && prev.title) || '',
     project: payload.cwd || (prev && prev.project) || '',
+    // 🔴 和 project 装的是同一个值，不是冗余：project 这个名字读起来就像「只该存目录名」
+    //    （上报侧确实只发 basename，见 snapshot.ts），早晚有人去「修」它。而远程指令靠
+    //    工作目录定位在哪执行 —— 实测 claude --resume 从任何目录都找得到会话，但 agent 的
+    //    工作目录跟着【启动目录】走：目录错了不报任何错，它会拿着对的对话去改错目录里的文件。
+    //    所以单独立一个名字说得清的字段，把这条契约钉死。
+    //    ⚠️ 只落本机，绝不上报：快照里发出去的仍然只有 basename。
+    cwd: payload.cwd || (prev && prev.cwd) || '',
     state: action,
     startedAt: (prev && prev.startedAt) || now,
     updatedAt: now,
     pid: pid,
-    pidName: pid ? (prev && prev.pidName) || processName(pid) || undefined : undefined,
+    pidName: pid ? (prevAlive && prev.pidName) || processName(pid) || undefined : undefined,
+    // 二期 P1：窗口开着的会话，设备不能再往里下指令（两个进程会互相吞掉对话）。每个会话只判一次
+    interactive: prevAlive && typeof prev.interactive === 'boolean' ? prev.interactive : detectInteractive(pid),
     lastReportAt: prev ? prev.lastReportAt : undefined,
+    // daemon 靠它给窗口待批准撤卡（S10），与 src/core/state.ts 的 recent 同构
+    recent: ((prev && Array.isArray(prev.recent) ? prev.recent : []).concat([
+      {
+        e: event,
+        tool: typeof payload.tool_name === 'string' ? payload.tool_name : undefined,
+        fp: typeof payload.tool_name === 'string' ? toolFingerprint(payload.tool_name, payload.tool_input) : undefined,
+        at: now,
+      },
+    ])).slice(-RECENT_MAX),
   }
 
   if (!shouldReport(prev, next, now)) {
@@ -647,6 +910,11 @@ module.exports = {
   removeState,
   resolveAgentPid,
   resolveTitle,
+  takeNotice,
+  isInteractiveArgs,
+  recordDir,
+  markClear,
+  pairClear,
   shouldReport,
   sign,
   titleSources,

package/hook/opencode.d.mts

@@ -0,0 +1,7 @@
+// hook/opencode.mjs 的类型声明（只给测试用；插件本体是零依赖 JS，跑在 opencode 自带的 bun 里）
+export function isHeadless(argv?: string[]): boolean
+export function toCcTool(tool: string, args: unknown): { tool_name: string; tool_input: Record<string, unknown> }
+export function askToCc(props: unknown): { tool_name: string; tool_input: Record<string, unknown> }
+export function openPermissions(cfg: unknown): void
+export const OC_GATED_KEYS: string[]
+export function make(opts?: { node?: string }): (ctx: unknown) => Promise<Record<string, unknown>>

package/hook/opencode.mjs

@@ -0,0 +1,329 @@
+// DeskBuddy 的 opencode 插件本体（二期 P9）。
+// `deskbuddy enable opencode` 在 opencode 的插件目录放一个入口文件 import 本文件；
+// 本文件随 hook.cjs / gate.cjs 一起同步到 ~/.deskbuddy/，CLI 升级即生效。
+//
+// 做的事只有翻译：把 opencode 的事件翻成 cc-hook 同构的输入，喂给同目录的 hook.cjs（状态上报）
+// 和 gate.cjs（授权关卡）。状态机、关卡、和设备打交道全在它们和 daemon 里，这里不重复。
+//
+// 实测依据（opencode 1.18.32；1.4.3 远程关卡与窗口确认同样实测通过，spec 2026-09-27-DeskBuddy二期 §P9 O1–O8）：
+// - 插件的 `permission.ask` 钩子不会被调用；授权只能从事件流的 permission.asked / permission.replied 拿
+// - `tool.execute.before` 在权限判断之前触发、可以 await 任意久、抛错 = 这次调用失败
+// - `opencode run` 遇到 ask 立即自动拒绝
+// - `config` 钩子原地改 permission 能生效（整对象替换不行）
+//
+// 🔴 远程任务（环境变量 DESKBUDDY_GATE_RUN）的安全模型，三层：
+//    ① daemon 起进程前确认插件装在 opencode 会读的位置（daemon/index.ts）；
+//    ② OPENCODE_CONFIG_CONTENT 把 OC_GATED_KEYS 逐项压成 deny（全局 + build agent 两级）。
+//       opencode 按"最后一条匹配的规则"生效且配置是深合并：只写 `*: deny` 挡不住用户配置里排在后面的
+//       `bash: allow`（评审 2026-09-28 实测），逐项写才会把同名键的值覆盖掉；
+//    ③ 本插件加载后才在 config 里放开、并在 tool.execute.before 里等设备。
+//    残余：用户给清单外的权限名写了 allow，且插件恰好加载失败 —— 那一项会放行。远程模式下本文件任何失败都必须走"拒绝"。
+// 🔴 窗口模式反过来：任何失败都不表态，授权框照常由人处理。
+
+import { spawn } from 'node:child_process'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const HOOK = join(HERE, 'hook.cjs')
+const GATE = join(HERE, 'gate.cjs')
+const TOOL = 'opencode'
+
+/** 设备允许过的工具调用，后续同一调用的第二个授权框直接代答（O6：rm /tmp/x 会连问 external_directory 和 bash） */
+const APPROVED_CALL_TTL_MS = 60 * 1000
+/** 工具调用参数的缓存时长：tool.execute.before 记下，随后的授权框靠它显示真实命令 */
+const CALL_TTL_MS = 10 * 60 * 1000
+/** hook.cjs 自己有 2 秒上报超时，这里再兜一层：一次卡死不能堵住后面所有状态 */
+const HOOK_KILL_MS = 10 * 1000
+
+/**
+ * 远程模式要压成 deny、插件加载后再放开的权限名。与 src/daemon/executor.ts 的 OPENCODE_GATED_KEYS 必须一致（有测试）。
+ * 新版本 opencode 多出来的权限名不在这里时，只剩 `*` 兜，见顶部"残余"
+ */
+export const OC_GATED_KEYS = [
+  '*', 'bash', 'edit', 'write', 'read', 'glob', 'grep', 'list', 'task', 'webfetch', 'websearch', 'codesearch',
+  'external_directory', 'todowrite', 'todoread', 'lsp', 'skill', 'doom_loop', 'patch', 'apply_patch',
+]
+
+function runIdFromEnv() {
+  const v = process.env.DESKBUDDY_GATE_RUN || ''
+  return /^[0-9a-zA-Z_-]{1,64}$/.test(v) ? v : ''
+}
+
+/**
+ * `opencode run` 是非交互（O2），其余（TUI、`opencode <目录>`）当窗口。编译版 argv = [bun, 入口, 子命令…]。
+ * 子命令前可能有全局参数（`--print-logs run`），所以看 `--` 之前有没有 `run`；误判成非交互只是少一个确认渠道
+ */
+export function isHeadless(argv = process.argv) {
+  const args = argv.slice(2)
+  const end = args.indexOf('--')
+  return (end >= 0 ? args.slice(0, end) : args).includes('run')
+}
+
+/** opencode 工具 → cc-hook 同构的 tool_name / tool_input（daemon 的 classify 按 Claude Code 的工具名判断） */
+export function toCcTool(tool, args) {
+  const a = args && typeof args === 'object' ? args : {}
+  const s = (v) => (typeof v === 'string' ? v : '')
+  switch (tool) {
+    case 'bash':
+      return { tool_name: 'Bash', tool_input: { command: s(a.command) } }
+    case 'read':
+      return { tool_name: 'Read', tool_input: { file_path: s(a.filePath) } }
+    case 'edit':
+      return { tool_name: 'Edit', tool_input: { file_path: s(a.filePath) } }
+    case 'write':
+      return { tool_name: 'Write', tool_input: { file_path: s(a.filePath) } }
+    case 'glob':
+      return { tool_name: 'Glob', tool_input: { pattern: s(a.pattern), path: s(a.path) } }
+    case 'grep':
+      return { tool_name: 'Grep', tool_input: { pattern: s(a.pattern), path: s(a.path) } }
+    case 'list':
+      return { tool_name: 'LS', tool_input: { path: s(a.path) } }
+    case 'webfetch':
+      return { tool_name: 'WebFetch', tool_input: { url: s(a.url) } }
+    case 'task':
+      return { tool_name: 'Task', tool_input: {} }
+    case 'todowrite':
+    case 'todoread':
+      return { tool_name: 'TodoWrite', tool_input: {} }
+    case 'patch':
+    case 'apply_patch':
+      return { tool_name: 'apply_patch', tool_input: { patch: s(a.patchText) || s(a.patch) || s(a.input) } }
+    default:
+      // 不认识的工具（MCP 等）原名原参数交出去：classify 对不认识的一律推设备
+      return { tool_name: String(tool || ''), tool_input: a }
+  }
+}
+
+/** permission.asked → PermissionRequest 的 tool_name / tool_input，给设备卡片生成摘要 */
+export function askToCc(props) {
+  const md = (props && props.metadata) || {}
+  if (typeof md.command === 'string' && md.command) return { tool_name: 'Bash', tool_input: { command: md.command } }
+  const file = md.filepath || md.filePath
+  if (typeof file === 'string' && file) return { tool_name: 'Edit', tool_input: { file_path: file } }
+  const patterns = Array.isArray(props && props.patterns) ? props.patterns.join(' ') : ''
+  return { tool_name: String((props && props.permission) || 'permission'), tool_input: { path: patterns } }
+}
+
+/**
+ * 远程模式：关卡改由 tool.execute.before 把，放开权限。🔴 必须原地改（整对象替换不生效，O8）。
+ * - OC_GATED_KEYS 是 daemon 压成 deny 的，放成 allow（用户原来在这些键上写的值已被覆盖，找不回来 —— 每一步都要过设备）
+ * - 其余键上的 ask 放成 allow（run 下 ask = 立即拒），用户显式的 deny 保留
+ * 全局与 build agent 两级都放（daemon 两级都压了）
+ */
+export function openPermissions(cfg) {
+  if (!cfg || typeof cfg !== 'object') return
+  const open = (perm) => {
+    const walk = (obj) => {
+      for (const k of Object.keys(obj)) {
+        const v = obj[k]
+        if (v === 'ask') obj[k] = 'allow'
+        else if (v && typeof v === 'object') walk(v)
+      }
+    }
+    walk(perm)
+    for (const k of OC_GATED_KEYS) perm[k] = 'allow'
+  }
+  if (!cfg.permission || typeof cfg.permission !== 'object') cfg.permission = {}
+  open(cfg.permission)
+  const build = cfg.agent && cfg.agent.build
+  if (build && build.permission && typeof build.permission === 'object') open(build.permission)
+}
+
+/** 活着的子进程；opencode 退出时一并结束，不留孤儿 gate 挂着设备卡片（评审） */
+const LIVE = new Set()
+process.on('exit', () => {
+  for (const c of LIVE) {
+    try {
+      c.kill('SIGTERM')
+    } catch (_) {
+      /* 已经退了 */
+    }
+  }
+})
+
+/** 起 node 子进程跑 hook.cjs / gate.cjs，stdin 喂 JSON。返回子进程句柄与结束结果（起不来 = code -1）。killMs > 0 时到点结束 */
+function startChild(node, script, args, input, killMs = 0) {
+  let child = null
+  const done = new Promise((resolve) => {
+    let out = ''
+    let err = ''
+    try {
+      child = spawn(node, [script, ...args], { stdio: ['pipe', 'pipe', 'pipe'] })
+    } catch (e) {
+      resolve({ code: -1, out, err: String(e) })
+      return
+    }
+    LIVE.add(child)
+    const timer = killMs > 0 ? setTimeout(() => child.kill('SIGKILL'), killMs) : null
+    const finish = (r) => {
+      LIVE.delete(child)
+      if (timer) clearTimeout(timer)
+      resolve(r)
+    }
+    child.stdout.on('data', (c) => (out += c))
+    child.stderr.on('data', (c) => (err += c))
+    child.on('error', (e) => finish({ code: -1, out, err: String(e) }))
+    child.on('close', (code) => finish({ code, out, err }))
+    child.stdin.on('error', () => {})
+    child.stdin.end(JSON.stringify(input))
+  })
+  return { child, done }
+}
+
+const runChild = (node, script, args, input, killMs) => startChild(node, script, args, input, killMs).done
+
+export function make(opts = {}) {
+  return async function DeskBuddy(ctx) {
+    const node = process.env.DESKBUDDY_NODE || opts.node || 'node'
+    const client = ctx && ctx.client
+    const cwd = (ctx && (ctx.directory || ctx.worktree)) || process.cwd()
+    const runId = runIdFromEnv()
+    const headless = isHeadless()
+
+    // ---- 状态上报：串行喂 hook.cjs，保证 PreToolUse / PostToolUse / Stop 的先后 ----
+    let queue = Promise.resolve()
+    const report = (event, sessionID, extra) => {
+      if (!sessionID) return
+      const input = { hook_event_name: event, session_id: sessionID, cwd, ...extra }
+      queue = queue.then(() => runChild(node, HOOK, [TOOL], input, HOOK_KILL_MS)).catch(() => {})
+    }
+
+    // ---- 窗口确认 ----
+    const pending = new Map() // requestID → gate 子进程
+    const approvedCalls = new Map() // callID → 允许时间
+    const calls = new Map() // callID → { cc, at }：这次工具调用的真实参数
+    const prune = () => {
+      const now = Date.now()
+      for (const [k, v] of calls) if (now - v.at > CALL_TTL_MS) calls.delete(k)
+      for (const [k, at] of approvedCalls) if (now - at > APPROVED_CALL_TTL_MS) approvedCalls.delete(k)
+    }
+
+    const reply = async (sessionID, id, response) => {
+      try {
+        await client.postSessionIdPermissionsPermissionId({ path: { id: sessionID, permissionID: id }, body: { response } })
+      } catch (_) {
+        /* 已被人答复过等，无所谓 */
+      }
+    }
+
+    const toast = async (message) => {
+      try {
+        await client.tui.showToast({ body: { message, variant: 'info' } })
+      } catch (_) {
+        /* 没有 TUI（web / acp）就不提示 */
+      }
+    }
+
+    const onAsked = async (p) => {
+      const { id, sessionID } = p || {}
+      if (!id || !sessionID) return
+      prune()
+      const callID = p.tool && p.tool.callID
+      // 🔴 卡片用这次工具调用的真实参数（tool.execute.before 先于授权触发，O3）。
+      //    external_directory 的 ask 自己不带命令，按它出卡片设备只看到"访问 /tmp/*"（评审）
+      const call = callID ? calls.get(callID) : null
+      const cc = call ? call.cc : askToCc(p)
+      report('PermissionRequest', sessionID, cc)
+      if (runId || headless || !client) return
+      // 同一调用的后续授权框直接代答：只在设备那张卡显示的就是真实参数时（approvedCalls 只在那时写入）
+      const at = callID && approvedCalls.get(callID)
+      if (at && Date.now() - at < APPROVED_CALL_TTL_MS) {
+        await reply(sessionID, id, 'once')
+        return
+      }
+      const input = { hook_event_name: 'PermissionRequest', session_id: sessionID, cwd, ...cc }
+      const { child, done } = startChild(node, GATE, ['--window', '--tool', TOOL], input)
+      if (child) pending.set(id, child)
+      const r = await done
+      pending.delete(id)
+      if (r.code !== 0 || !r.out) return
+      let out
+      try {
+        out = JSON.parse(r.out)
+      } catch (_) {
+        return
+      }
+      const d = out && out.hookSpecificOutput && out.hookSpecificOutput.decision
+      if (!d) return
+      if (d.behavior === 'allow') {
+        if (callID && call) approvedCalls.set(callID, Date.now())
+        await reply(sessionID, id, 'once')
+      } else if (d.behavior === 'deny') {
+        await reply(sessionID, id, 'reject')
+      } else return
+      if (typeof out.systemMessage === 'string' && out.systemMessage) await toast(out.systemMessage)
+    }
+
+    const onReplied = (p) => {
+      // 人先在窗口里答了：结束 gate 子进程，daemon 随之撤掉设备上的卡片
+      const child = p && pending.get(p.requestID)
+      if (child) {
+        pending.delete(p.requestID)
+        try {
+          child.kill('SIGTERM')
+        } catch (_) {
+          /* 已经退了 */
+        }
+      }
+    }
+
+    return {
+      config: async (cfg) => {
+        if (runId) openPermissions(cfg)
+      },
+
+      'chat.message': async (input) => {
+        report('UserPromptSubmit', input && input.sessionID)
+      },
+
+      'tool.execute.before': async (input, output) => {
+        const cc = toCcTool(input && input.tool, output && output.args)
+        if (input && input.callID) calls.set(input.callID, { cc, at: Date.now() })
+        report('PreToolUse', input && input.sessionID, cc)
+        if (!runId) return
+        // 远程关卡：等设备。任何失败都拒（见顶部）
+        const r = await runChild(node, GATE, ['--run', runId], {
+          hook_event_name: 'PreToolUse',
+          session_id: (input && input.sessionID) || '',
+          cwd,
+          ...cc,
+        })
+        let decision = ''
+        try {
+          decision = JSON.parse(r.out).hookSpecificOutput.permissionDecision
+        } catch (_) {
+          decision = ''
+        }
+        if (r.code === 0 && decision === 'allow') return
+        throw new Error((r.err || '').trim() || '用户在设备上拒绝了这一步')
+      },
+
+      'tool.execute.after': async (input) => {
+        if (input && input.callID) calls.delete(input.callID)
+        approvedCalls.delete(input && input.callID)
+        const cc = toCcTool(input && input.tool, input && input.args)
+        report('PostToolUse', input && input.sessionID, cc)
+      },
+
+      event: async ({ event }) => {
+        const p = (event && event.properties) || {}
+        switch (event && event.type) {
+          case 'permission.asked':
+            onAsked(p).catch(() => {})
+            break
+          case 'permission.replied':
+            onReplied(p)
+            break
+          case 'session.idle':
+            report('Stop', p.sessionID)
+            break
+          case 'session.deleted':
+            report('SessionEnd', (p.info && p.info.id) || p.sessionID)
+            break
+          default:
+        }
+      },
+    }
+  }
+}