agentquad 0.3.2 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentquad",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "AgentQuad — local four-quadrant AI task scheduler with embedded Claude Code / Codex terminals",
   "license": "MIT",
   "author": "LIUZHENHUA521",

package/src/cli.js

@@ -290,25 +290,35 @@ export async function doctorReport({ rootDir = DEFAULT_ROOT_DIR } = {}) {
       })
     }
 
-    // 4. Claude Code hook 安装状态（主动推送）
+    // 4. （历史保留位）claude-code hook 现在挪到 oc.enabled 外面统一检查
+  }
+
+  // ─── AI CLI hooks 安装状态（claude / codex / cursor）——所有用户都看 ──
+  // 不再绑定 openclaw 启用与否，因为 hook 还服务 Telegram / Lark 推送
+  const HOOK_DOCTOR_TOOLS = [
+    { name: 'claude-code', mod: './openclaw-hook-installer.js', flag: 'claude' },
+    { name: 'codex',       mod: './codex-hook-installer.js',    flag: 'codex'  },
+    { name: 'cursor',      mod: './cursor-hook-installer.js',   flag: 'cursor' },
+  ]
+  for (const { name, mod, flag } of HOOK_DOCTOR_TOOLS) {
     try {
-      const { inspectHooks } = await import('./openclaw-hook-installer.js')
-      const hk = inspectHooks()
+      const m = await import(mod)
+      const hk = m.inspectHooks()
       checks.push({
-        name: 'claude-code hook script',
+        name: `${name} hook script`,
         ok: hk.scriptExists,
         detail: hk.hookScriptPath + (hk.scriptExists ? '' : ' (missing — should be auto-installed)'),
       })
       checks.push({
-        name: 'claude-code hooks installed',
+        name: `${name} hooks installed`,
         ok: hk.installed,
         detail: hk.installed
           ? `events: ${hk.eventsInstalled.join(', ')}`
-          : '缺失：跑 `agentquad openclaw install-hook` 一次',
+          : `缺失：跑 \`agentquad hook bootstrap --${flag}\` 一次`,
       })
     } catch (e) {
       checks.push({
-        name: 'claude-code hooks',
+        name: `${name} hooks`,
         ok: false,
         detail: `inspect failed: ${e.message}`,
       })
@@ -455,34 +465,44 @@ export async function runStart(cmdOpts = {}) {
   console.log(buildStartupBanner({ port: actualPort, host }))
   console.log(`AI terminal default cwd: ${defaultCwd}`)
 
-  // ─── 自动 bootstrap Claude Code hook（部署 notify.js + 合入 settings.json）───
-  // 设计：缺啥补啥 / 已装则 noop / 用户跑过 uninstall-hook 留下的 marker 会被尊重
+  // ─── 自动 bootstrap 3 个 AI CLI 的 hook（claude / codex / cursor）───
+  // 设计：每个工具独立 try/catch；缺啥补啥 / 已装则 noop / uninstall marker 被尊重
   // 任何错误一律 warn-skip，绝不让 hook bootstrap 把 agentquad start 挂掉
-  try {
-    const { bootstrapHooks } = await import('./openclaw-hook-installer.js')
-    const r = bootstrapHooks()
-    if (r.skipped) {
-      if (r.reason === 'uninstall_marker') {
-        console.log(`ℹ claude-code hook: 已被你 uninstall-hook 拒绝；想恢复跑 'agentquad openclaw bootstrap'`)
-      } else if (r.reason === 'malformed_settings') {
-        console.warn(`⚠ claude-code hook: ~/.claude/settings.json JSON 损坏，跳过自动安装；修好后跑 'agentquad openclaw bootstrap'`)
-      } else {
-        console.log(`ℹ claude-code hook bootstrap skipped: ${r.reason}`)
+  const BOOTSTRAP_TOOLS = [
+    { tool: 'claude-code', mod: './openclaw-hook-installer.js', fn: 'bootstrapHooks',       malformedReason: 'malformed_settings'  },
+    { tool: 'codex',       mod: './codex-hook-installer.js',    fn: 'bootstrapCodexHooks',  malformedReason: 'malformed_hooks_json' },
+    { tool: 'cursor',      mod: './cursor-hook-installer.js',   fn: 'bootstrapCursorHooks', malformedReason: 'malformed_hooks_json' },
+  ]
+  for (const { tool, mod, fn, malformedReason } of BOOTSTRAP_TOOLS) {
+    try {
+      const m = await import(mod)
+      const r = m[fn]()
+      if (r.skipped) {
+        if (r.reason === 'uninstall_marker') {
+          console.log(`ℹ ${tool} hook: 已被你 hook uninstall 拒绝；想恢复跑 'agentquad hook bootstrap --${tool === 'claude-code' ? 'claude' : tool}'`)
+        } else if (r.reason === malformedReason) {
+          console.warn(`⚠ ${tool} hook: 配置 JSON 损坏，跳过自动安装；修好后跑 'agentquad hook bootstrap --${tool === 'claude-code' ? 'claude' : tool}'`)
+        } else {
+          console.log(`ℹ ${tool} hook bootstrap skipped: ${r.reason}`)
+        }
+        continue
       }
-    } else {
       if (r.scriptResult.action === 'installed') {
-        console.log(`✓ claude-code hook script installed (v${r.scriptResult.version}) → ${r.scriptResult.scriptPath}`)
+        console.log(`✓ ${tool} hook script installed (v${r.scriptResult.version}) → ${r.scriptResult.scriptPath}`)
       } else if (r.scriptResult.action === 'upgraded') {
-        console.log(`✓ claude-code hook script upgraded v${r.scriptResult.previousVersion ?? 0} → v${r.scriptResult.version} (backup: ${r.scriptResult.backup})`)
+        console.log(`✓ ${tool} hook script upgraded v${r.scriptResult.previousVersion ?? 0} → v${r.scriptResult.version} (backup: ${r.scriptResult.backup})`)
       }
       if (r.alreadyInstalled) {
         // 静默：避免每次 start 都刷屏。doctor 会显示状态
       } else if (r.hookResult) {
-        console.log(`✓ claude-code hooks installed: ${r.hookResult.added.join(', ')}`)
+        console.log(`✓ ${tool} hooks installed: ${r.hookResult.added.join(', ')}`)
+        if (r.hookResult.configResult?.action && r.hookResult.configResult.action !== 'already_present') {
+          console.log(`  feature flag ${r.hookResult.configResult.action} → ${r.hookResult.configResult.configPath}`)
+        }
       }
+    } catch (e) {
+      console.warn(`⚠ ${tool} hook bootstrap failed: ${e?.message || e}`)
     }
-  } catch (e) {
-    console.warn(`⚠ claude-code hook bootstrap failed: ${e?.message || e}`)
   }
 
   // listen 完成后异步发"重启完成 + Resume N 个会话"通知到 telegram。
@@ -892,25 +912,154 @@ async function actHookStatus() {
   if (r.error) console.log(`  ⚠️  ${r.error}`)
 }
 
+// ─── 多工具 hook 操作（claude / codex / cursor）─────────────────────
+export function planHookTools(opts) {
+  const flags = opts || {}
+  const explicit = []
+  if (flags.claude) explicit.push('claude')
+  if (flags.codex)  explicit.push('codex')
+  if (flags.cursor) explicit.push('cursor')
+  if (flags.all || explicit.length === 0) return ['claude', 'codex', 'cursor']
+  return explicit
+}
+
+const HOOK_INSTALLERS = {
+  claude: { mod: () => import('./openclaw-hook-installer.js'), bootstrap: 'bootstrapHooks' },
+  codex:  { mod: () => import('./codex-hook-installer.js'),    bootstrap: 'bootstrapCodexHooks' },
+  cursor: { mod: () => import('./cursor-hook-installer.js'),   bootstrap: 'bootstrapCursorHooks' },
+}
+
+async function actInstallHookMulti(opts) {
+  let allOk = true
+  for (const tool of planHookTools(opts)) {
+    try {
+      const m = await HOOK_INSTALLERS[tool].mod()
+      const out = m.installHooks()
+      const path = out.settingsPath || out.hooksPath
+      console.log(`✓ [${tool}] installed ${out.added.join(', ')} → ${path}`)
+      if (out.backup) console.log(`   backup: ${out.backup}`)
+      if (out.configResult?.action && out.configResult.action !== 'already_present') {
+        console.log(`   feature flag ${out.configResult.action} → ${out.configResult.configPath}`)
+      }
+      if (out.markerCleared) console.log(`   uninstall marker cleared`)
+    } catch (e) {
+      console.error(`✗ [${tool}] ${e.message}`)
+      if (e.code === 'hook_script_missing') {
+        console.error(`   跑 'agentquad hook bootstrap --${tool}' 一键部署 + 安装`)
+      }
+      allOk = false
+    }
+  }
+  if (!allOk) process.exit(1)
+}
+
+async function actUninstallHookMulti(opts) {
+  let allOk = true
+  for (const tool of planHookTools(opts)) {
+    try {
+      const m = await HOOK_INSTALLERS[tool].mod()
+      const out = m.uninstallHooks({ writeUninstallMarker: opts.marker !== false })
+      const path = out.settingsPath || out.hooksPath
+      if (out.removed.length === 0) {
+        console.log(`= [${tool}] no AgentQuad hooks; nothing to remove`)
+      } else {
+        const total = out.removed.reduce((s, r) => s + r.removedCount, 0)
+        console.log(`✓ [${tool}] removed ${total} entries → ${path}`)
+        for (const r of out.removed) console.log(`     ${r.event}: -${r.removedCount}`)
+        if (out.backup) console.log(`   backup: ${out.backup}`)
+      }
+      if (out.markerWritten) console.log(`   marker written`)
+    } catch (e) {
+      console.error(`✗ [${tool}] ${e.message}`)
+      allOk = false
+    }
+  }
+  if (!allOk) process.exit(1)
+}
+
+async function actHookStatusMulti(opts) {
+  for (const tool of planHookTools(opts)) {
+    try {
+      const m = await HOOK_INSTALLERS[tool].mod()
+      const r = m.inspectHooks()
+      const icon = r.installed ? '✓' : '✗'
+      const path = r.settingsPath || r.hooksPath
+      console.log(`${icon} [${tool}] installed: ${r.installed}`)
+      console.log(`   events: ${r.eventsInstalled.length ? r.eventsInstalled.join(', ') : '(none)'}`)
+      console.log(`   config: ${path}`)
+      console.log(`   script: ${r.hookScriptPath} (${r.scriptExists ? 'exists' : 'MISSING'})`)
+      if (r.featureFlagOk === false) console.log(`   ⚠️  codex_hooks feature flag not set in ~/.codex/config.toml`)
+      if (r.error) console.log(`   ⚠️  ${r.error}`)
+    } catch (e) {
+      console.error(`✗ [${tool}] ${e.message}`)
+    }
+  }
+}
+
+async function actBootstrapHookMulti(opts) {
+  let allOk = true
+  for (const tool of planHookTools(opts)) {
+    const cfg = HOOK_INSTALLERS[tool]
+    try {
+      const m = await cfg.mod()
+      const r = m[cfg.bootstrap]({ respectUninstallMarker: false })
+      if (r.skipped) {
+        const reasonTxt = r.reason === 'malformed_settings' || r.reason === 'malformed_hooks_json'
+          ? `${r.reason} — 请先修复 JSON 再试`
+          : r.reason
+        console.log(`= [${tool}] skipped: ${reasonTxt}`)
+        if (r.reason === 'malformed_settings' || r.reason === 'malformed_hooks_json') allOk = false
+        continue
+      }
+      const sr = r.scriptResult
+      const verb = sr.action === 'unchanged' ? '=' : '✓'
+      console.log(`${verb} [${tool}] script ${sr.action} (v${sr.version})`)
+      if (sr.backup) console.log(`   script backup: ${sr.backup}`)
+      if (r.alreadyInstalled) {
+        console.log(`   hooks already installed`)
+      } else if (r.hookResult) {
+        console.log(`   hooks installed: ${r.hookResult.added.join(', ')}`)
+        if (r.hookResult.backup) console.log(`   config backup: ${r.hookResult.backup}`)
+        if (r.hookResult.configResult?.action && r.hookResult.configResult.action !== 'already_present') {
+          console.log(`   feature flag ${r.hookResult.configResult.action} → ${r.hookResult.configResult.configPath}`)
+        }
+      }
+      if (r.markerCleared) console.log(`   uninstall marker cleared`)
+    } catch (e) {
+      console.error(`✗ [${tool}] ${e.message}`)
+      allOk = false
+    }
+  }
+  if (!allOk) process.exit(1)
+}
+
+function addToolFlags(cmd) {
+  return cmd
+    .option('--claude', 'apply to Claude Code hooks (~/.claude/settings.json)')
+    .option('--codex', 'apply to OpenAI Codex hooks (~/.codex/hooks.json + config.toml)')
+    .option('--cursor', 'apply to Cursor Agent hooks (~/.cursor/hooks.json)')
+    .option('--all', 'apply to all tools (default if no flag given)')
+}
+
 // ─── 顶层 hook 子命令组（首选入口；发现性比埋在 openclaw 下好）──────
-const hookCmd = program.command('hook').description('管理 AgentQuad 在 ~/.claude/settings.json 里安装的 hook（装/删/查/恢复）')
+const hookCmd = program.command('hook').description('管理 AgentQuad 在 Claude Code / Codex / Cursor 里安装的 hook（装/删/查/恢复）')
 
-hookCmd.command('install')
-  .description('把 AgentQuad 的 3 个 hook（Stop/Notification/SessionEnd）合并写入 ~/.claude/settings.json')
-  .action(actInstallHook)
+addToolFlags(hookCmd.command('install'))
+  .description('合并写入 hook 配置；默认 --all（claude + codex + cursor）')
+  .action(actInstallHookMulti)
 
-hookCmd.command('uninstall')
-  .description('从 ~/.claude/settings.json 移除 AgentQuad 加的 hook entry，保留你其他 hook（默认写 .uninstalled marker，下次 start 不再自动装回）')
+addToolFlags(hookCmd.command('uninstall'))
+  .description('移除 AgentQuad 加的 hook entry，保留你其他 hook；默认写 .uninstalled marker，下次 start 不再装回')
   .option('--no-marker', '不写 .uninstalled marker（下次 agentquad start 会自动装回）')
-  .action(actUninstallHook)
+  .action(actUninstallHookMulti)
 
-hookCmd.command('status')
-  .description('查看 AgentQuad hook 是否安装到 ~/.claude/settings.json')
-  .action(actHookStatus)
+addToolFlags(hookCmd.command('status'))
+  .description('查看每个工具的 hook 安装状态')
+  .action(actHookStatusMulti)
 
-hookCmd.command('bootstrap')
+addToolFlags(hookCmd.command('bootstrap'))
   .description('一键部署 hook script + 安装 hooks（强制忽略 .uninstalled marker，用于"删过又想恢复"场景）')
-  .action(actBootstrapHook)
+  .action(actBootstrapHookMulti)
 
 // ─── openclaw 子命令组：保留旧路径以向后兼容；hook 操作建议改用 `agentquad hook *` ───
 const openclawCmd = program.command('openclaw').description('OpenClaw bridge: install/uninstall Claude Code hooks for proactive WeChat push')

package/src/codex-hook-installer.js

@@ -0,0 +1,361 @@
+/**
+ * OpenAI Codex CLI hooks 安装器：
+ *   - 往 `~/.codex/config.toml` 末尾追加 `[features] codex_hooks = true`（若缺）
+ *   - 把 hook entry 合并写入 `~/.codex/hooks.json`，不破坏用户现有 hook
+ *
+ * Codex 没有 SessionEnd 事件，仅装 Stop / UserPromptSubmit 两个。
+ *
+ * 合并策略：
+ *   - 已有 hooks.<event> 数组 → append；不删除已有 entry
+ *   - AgentQuad 加的 entry 用 `_agentquadManaged: true` 字段标记，方便 uninstall
+ *   - 卸载时仅删带这个标记的 entry，其他保留不动
+ *   - hooks.json 不存在 → 创建
+ *   - hooks.json 损坏 → warn-skip 不擅自覆盖
+ *
+ * 启动期 bootstrap（bootstrapCodexHooks）：
+ *   - 部署/升级 ~/.agentquad/codex-hooks/notify.js（带版本号比对）
+ *   - 合并 hook 到 hooks.json + 写 feature flag
+ *   - 用户跑过 hook uninstall → 留 .uninstalled marker，bootstrap 默认尊重
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, unlinkSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { DEFAULT_ROOT_DIR } from './config.js'
+
+const MANAGED_KEY = '_agentquadManaged'
+const HOOK_EVENTS = ['Stop', 'UserPromptSubmit']
+const HOOK_VERSION_RE = /quadtodo-hook-version:\s*(\d+)/
+const FEATURE_FLAG_MARKER = '# agentquad-managed codex_hooks flag'
+
+function defaultHookScriptPath() {
+  return join(DEFAULT_ROOT_DIR, 'codex-hooks', 'notify.js')
+}
+
+function defaultConfigDir() {
+  return join(homedir(), '.codex')
+}
+
+function defaultConfigTomlPath() {
+  return join(defaultConfigDir(), 'config.toml')
+}
+
+function defaultHooksJsonPath() {
+  return join(defaultConfigDir(), 'hooks.json')
+}
+
+function defaultTemplatePath() {
+  return fileURLToPath(new URL('./templates/codex-hooks/notify.js', import.meta.url))
+}
+
+function defaultUninstallMarkerPath() {
+  return join(DEFAULT_ROOT_DIR, 'codex-hooks', '.uninstalled')
+}
+
+function parseHookVersion(content) {
+  if (!content) return null
+  const m = content.match(HOOK_VERSION_RE)
+  return m ? Number(m[1]) : 0
+}
+
+function buildHookEntry(event, hookScriptPath) {
+  const eventLower = event === 'UserPromptSubmit' ? 'notification' : 'stop'
+  return {
+    matcher: '',
+    hooks: [
+      {
+        type: 'command',
+        command: `node ${hookScriptPath} ${eventLower}`,
+        timeout: 30,
+        [MANAGED_KEY]: true,
+      },
+    ],
+    [MANAGED_KEY]: true,
+  }
+}
+
+function loadHooksJson(path) {
+  if (!existsSync(path)) return {}
+  const raw = readFileSync(path, 'utf8')
+  try {
+    return JSON.parse(raw)
+  } catch (e) {
+    const err = new Error(`codex hooks.json malformed: ${e.message}`)
+    err.code = 'malformed_hooks_json'
+    err.path = path
+    throw err
+  }
+}
+
+function saveHooksJson(path, data) {
+  const dir = dirname(path)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n')
+}
+
+function backupFile(path) {
+  if (!existsSync(path)) return null
+  const bak = `${path}.bak.${Date.now()}`
+  copyFileSync(path, bak)
+  return bak
+}
+
+/**
+ * 在 config.toml 中确保 `[features] codex_hooks = true` 存在。
+ * 行级别幂等：如果 file 里已经出现 `codex_hooks` 这个 key（任何位置），就不动；
+ * 否则在末尾追加一个带标记注释的 [features] 段。
+ *
+ * 不解析 TOML、不动其它内容，避免破坏用户配置（如 [projects."..."] 列表）。
+ *
+ * 返回 { configPath, action: 'added' | 'already_present' | 'created', backup }
+ */
+export function ensureFeatureFlag({
+  configPath = defaultConfigTomlPath(),
+} = {}) {
+  const dir = dirname(configPath)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+
+  if (!existsSync(configPath)) {
+    writeFileSync(
+      configPath,
+      `${FEATURE_FLAG_MARKER}\n[features]\ncodex_hooks = true\n`,
+    )
+    return { configPath, action: 'created', backup: null }
+  }
+
+  const raw = readFileSync(configPath, 'utf8')
+  if (/^\s*codex_hooks\s*=\s*true/m.test(raw)) {
+    return { configPath, action: 'already_present', backup: null }
+  }
+
+  const backup = backupFile(configPath)
+  const sep = raw.endsWith('\n') ? '' : '\n'
+  const appended = `${raw}${sep}\n${FEATURE_FLAG_MARKER}\n[features]\ncodex_hooks = true\n`
+  writeFileSync(configPath, appended)
+  return { configPath, action: 'added', backup }
+}
+
+/**
+ * 把 AgentQuad 的 hook entry 合并到 hooks.json。幂等。
+ *
+ * 返回 { hooksPath, backup, added, configResult }
+ */
+export function installHooks({
+  hooksPath = defaultHooksJsonPath(),
+  configPath = defaultConfigTomlPath(),
+  hookScriptPath = defaultHookScriptPath(),
+  events = HOOK_EVENTS,
+  uninstallMarkerPath = defaultUninstallMarkerPath(),
+  clearUninstallMarker = true,
+} = {}) {
+  if (!existsSync(hookScriptPath)) {
+    const err = new Error(`hook script not found: ${hookScriptPath}`)
+    err.code = 'hook_script_missing'
+    throw err
+  }
+
+  const configResult = ensureFeatureFlag({ configPath })
+  const data = loadHooksJson(hooksPath)
+  const backup = backupFile(hooksPath)
+  if (!data.hooks || typeof data.hooks !== 'object') data.hooks = {}
+
+  const added = []
+  for (const event of events) {
+    if (!Array.isArray(data.hooks[event])) data.hooks[event] = []
+    data.hooks[event] = data.hooks[event].filter((entry) => !entry?.[MANAGED_KEY])
+    data.hooks[event].push(buildHookEntry(event, hookScriptPath))
+    added.push(event)
+  }
+
+  saveHooksJson(hooksPath, data)
+  let markerCleared = false
+  if (clearUninstallMarker && existsSync(uninstallMarkerPath)) {
+    try { unlinkSync(uninstallMarkerPath); markerCleared = true } catch { /* ignore */ }
+  }
+  return { hooksPath, backup, added, skipped: [], configResult, markerCleared }
+}
+
+/**
+ * 移除 AgentQuad 加的所有 hook entry（按 _agentquadManaged 标记）。
+ * 不动用户的 feature flag（即便是我们写的也保留 — codex_hooks=true 是无害默认）。
+ */
+export function uninstallHooks({
+  hooksPath = defaultHooksJsonPath(),
+  uninstallMarkerPath = defaultUninstallMarkerPath(),
+  writeUninstallMarker = true,
+} = {}) {
+  let markerWritten = false
+  const writeMarker = () => {
+    if (!writeUninstallMarker) return
+    try {
+      const dir = dirname(uninstallMarkerPath)
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+      writeFileSync(uninstallMarkerPath, `${new Date().toISOString()}\n`)
+      markerWritten = true
+    } catch { /* ignore */ }
+  }
+
+  if (!existsSync(hooksPath)) {
+    writeMarker()
+    return { hooksPath, removed: [], backup: null, markerWritten }
+  }
+
+  const data = loadHooksJson(hooksPath)
+  const backup = backupFile(hooksPath)
+  const removed = []
+
+  if (data.hooks && typeof data.hooks === 'object') {
+    for (const event of Object.keys(data.hooks)) {
+      if (!Array.isArray(data.hooks[event])) continue
+      const before = data.hooks[event].length
+      data.hooks[event] = data.hooks[event].filter((entry) => !entry?.[MANAGED_KEY])
+      if (data.hooks[event].length !== before) {
+        removed.push({ event, removedCount: before - data.hooks[event].length })
+      }
+      if (data.hooks[event].length === 0) delete data.hooks[event]
+    }
+    if (Object.keys(data.hooks).length === 0) delete data.hooks
+  }
+
+  saveHooksJson(hooksPath, data)
+  writeMarker()
+  return { hooksPath, removed, backup, markerWritten }
+}
+
+export function inspectHooks({
+  hooksPath = defaultHooksJsonPath(),
+  configPath = defaultConfigTomlPath(),
+  hookScriptPath = defaultHookScriptPath(),
+} = {}) {
+  const scriptExists = existsSync(hookScriptPath)
+  const featureFlagOk = existsSync(configPath)
+    && /^\s*codex_hooks\s*=\s*true/m.test(readFileSync(configPath, 'utf8'))
+
+  if (!existsSync(hooksPath)) {
+    return { installed: false, eventsInstalled: [], hooksPath, hookScriptPath, scriptExists, featureFlagOk }
+  }
+  let data
+  try {
+    data = loadHooksJson(hooksPath)
+  } catch (e) {
+    return { installed: false, eventsInstalled: [], hooksPath, hookScriptPath, scriptExists, featureFlagOk, error: e.code }
+  }
+  const eventsInstalled = []
+  for (const event of HOOK_EVENTS) {
+    const arr = data?.hooks?.[event]
+    if (!Array.isArray(arr)) continue
+    if (arr.some((entry) => entry?.[MANAGED_KEY])) eventsInstalled.push(event)
+  }
+  return {
+    installed: eventsInstalled.length === HOOK_EVENTS.length && featureFlagOk,
+    eventsInstalled,
+    hooksPath,
+    hookScriptPath,
+    scriptExists,
+    featureFlagOk,
+  }
+}
+
+export function deployHookScript({
+  scriptPath = defaultHookScriptPath(),
+  templatePath = defaultTemplatePath(),
+} = {}) {
+  if (!existsSync(templatePath)) {
+    const err = new Error(`hook template not found: ${templatePath}`)
+    err.code = 'hook_template_missing'
+    throw err
+  }
+  const templateContent = readFileSync(templatePath, 'utf8')
+  const templateVersion = parseHookVersion(templateContent)
+
+  const dir = dirname(scriptPath)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+
+  const previousVersion = existsSync(scriptPath)
+    ? parseHookVersion(readFileSync(scriptPath, 'utf8'))
+    : null
+
+  if (previousVersion !== null && previousVersion === templateVersion) {
+    return { action: 'unchanged', version: templateVersion, previousVersion, scriptPath, backup: null }
+  }
+
+  let backup = null
+  if (previousVersion !== null) {
+    backup = `${scriptPath}.bak.${Date.now()}`
+    copyFileSync(scriptPath, backup)
+  }
+  writeFileSync(scriptPath, templateContent)
+  return {
+    action: previousVersion === null ? 'installed' : 'upgraded',
+    version: templateVersion,
+    previousVersion,
+    scriptPath,
+    backup,
+  }
+}
+
+export function bootstrapCodexHooks({
+  hooksPath = defaultHooksJsonPath(),
+  configPath = defaultConfigTomlPath(),
+  scriptPath = defaultHookScriptPath(),
+  templatePath = defaultTemplatePath(),
+  uninstallMarkerPath = defaultUninstallMarkerPath(),
+  respectUninstallMarker = true,
+} = {}) {
+  if (respectUninstallMarker && existsSync(uninstallMarkerPath)) {
+    return { skipped: true, reason: 'uninstall_marker', uninstallMarkerPath }
+  }
+
+  let markerCleared = false
+  if (!respectUninstallMarker && existsSync(uninstallMarkerPath)) {
+    try { unlinkSync(uninstallMarkerPath); markerCleared = true } catch { /* ignore */ }
+  }
+
+  const scriptResult = deployHookScript({ scriptPath, templatePath })
+
+  const inspect = inspectHooks({ hooksPath, configPath, hookScriptPath: scriptPath })
+  if (inspect.error === 'malformed_hooks_json') {
+    return {
+      skipped: true,
+      reason: 'malformed_hooks_json',
+      hooksPath,
+      scriptResult,
+      markerCleared,
+    }
+  }
+
+  if (inspect.installed) {
+    return {
+      skipped: false,
+      alreadyInstalled: true,
+      scriptResult,
+      hookResult: null,
+      markerCleared,
+    }
+  }
+
+  const hookResult = installHooks({
+    hooksPath,
+    configPath,
+    hookScriptPath: scriptPath,
+    uninstallMarkerPath,
+    clearUninstallMarker: false,
+  })
+  return {
+    skipped: false,
+    alreadyInstalled: false,
+    scriptResult,
+    hookResult,
+    markerCleared,
+  }
+}
+
+export const __test__ = {
+  buildHookEntry,
+  MANAGED_KEY,
+  HOOK_EVENTS,
+  parseHookVersion,
+  defaultTemplatePath,
+  defaultUninstallMarkerPath,
+  FEATURE_FLAG_MARKER,
+}

package/src/cursor-hook-installer.js

@@ -0,0 +1,296 @@
+/**
+ * Cursor Agent CLI hooks 安装器：
+ *   - 把 hook entry 合并写入 `~/.cursor/hooks.json`，不破坏用户现有 hook
+ *   - 写 `"version": 1` 协议头（Cursor 1.7+ 要求）
+ *
+ * Cursor 事件：stop（turn end）/ beforeSubmitPrompt（等用户）/ sessionEnd
+ *
+ * 合并策略：
+ *   - 已有 hooks.<event> 数组 → append；不删除已有 entry
+ *   - AgentQuad 加的 entry 用 `_agentquadManaged: true` 标记
+ *   - hooks.json 不存在 → 创建（带 version:1）
+ *   - hooks.json 损坏 → warn-skip
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, unlinkSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { DEFAULT_ROOT_DIR } from './config.js'
+
+const MANAGED_KEY = '_agentquadManaged'
+const HOOK_EVENTS = ['stop', 'beforeSubmitPrompt', 'sessionEnd']
+const HOOK_VERSION_RE = /quadtodo-hook-version:\s*(\d+)/
+const SCHEMA_VERSION = 1
+
+function defaultHookScriptPath() {
+  return join(DEFAULT_ROOT_DIR, 'cursor-hooks', 'notify.js')
+}
+
+function defaultHooksJsonPath() {
+  return join(homedir(), '.cursor', 'hooks.json')
+}
+
+function defaultTemplatePath() {
+  return fileURLToPath(new URL('./templates/cursor-hooks/notify.js', import.meta.url))
+}
+
+function defaultUninstallMarkerPath() {
+  return join(DEFAULT_ROOT_DIR, 'cursor-hooks', '.uninstalled')
+}
+
+function parseHookVersion(content) {
+  if (!content) return null
+  const m = content.match(HOOK_VERSION_RE)
+  return m ? Number(m[1]) : 0
+}
+
+function eventToArg(event) {
+  if (event === 'beforeSubmitPrompt') return 'notification'
+  if (event === 'sessionEnd') return 'session-end'
+  return 'stop'
+}
+
+function buildHookEntry(event, hookScriptPath) {
+  // Cursor 的 hook entry 是扁平的 object（不像 Claude 的 matcher+hooks 嵌套）
+  return {
+    type: 'command',
+    command: `node ${hookScriptPath} ${eventToArg(event)}`,
+    timeout: 30,
+    [MANAGED_KEY]: true,
+  }
+}
+
+function loadHooksJson(path) {
+  if (!existsSync(path)) return { version: SCHEMA_VERSION }
+  const raw = readFileSync(path, 'utf8')
+  try {
+    return JSON.parse(raw)
+  } catch (e) {
+    const err = new Error(`cursor hooks.json malformed: ${e.message}`)
+    err.code = 'malformed_hooks_json'
+    err.path = path
+    throw err
+  }
+}
+
+function saveHooksJson(path, data) {
+  const dir = dirname(path)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n')
+}
+
+function backupFile(path) {
+  if (!existsSync(path)) return null
+  const bak = `${path}.bak.${Date.now()}`
+  copyFileSync(path, bak)
+  return bak
+}
+
+export function installHooks({
+  hooksPath = defaultHooksJsonPath(),
+  hookScriptPath = defaultHookScriptPath(),
+  events = HOOK_EVENTS,
+  uninstallMarkerPath = defaultUninstallMarkerPath(),
+  clearUninstallMarker = true,
+} = {}) {
+  if (!existsSync(hookScriptPath)) {
+    const err = new Error(`hook script not found: ${hookScriptPath}`)
+    err.code = 'hook_script_missing'
+    throw err
+  }
+
+  const data = loadHooksJson(hooksPath)
+  const backup = backupFile(hooksPath)
+  if (!data.version) data.version = SCHEMA_VERSION
+  if (!data.hooks || typeof data.hooks !== 'object') data.hooks = {}
+
+  const added = []
+  for (const event of events) {
+    if (!Array.isArray(data.hooks[event])) data.hooks[event] = []
+    data.hooks[event] = data.hooks[event].filter((entry) => !entry?.[MANAGED_KEY])
+    data.hooks[event].push(buildHookEntry(event, hookScriptPath))
+    added.push(event)
+  }
+
+  saveHooksJson(hooksPath, data)
+  let markerCleared = false
+  if (clearUninstallMarker && existsSync(uninstallMarkerPath)) {
+    try { unlinkSync(uninstallMarkerPath); markerCleared = true } catch { /* ignore */ }
+  }
+  return { hooksPath, backup, added, skipped: [], markerCleared }
+}
+
+export function uninstallHooks({
+  hooksPath = defaultHooksJsonPath(),
+  uninstallMarkerPath = defaultUninstallMarkerPath(),
+  writeUninstallMarker = true,
+} = {}) {
+  let markerWritten = false
+  const writeMarker = () => {
+    if (!writeUninstallMarker) return
+    try {
+      const dir = dirname(uninstallMarkerPath)
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+      writeFileSync(uninstallMarkerPath, `${new Date().toISOString()}\n`)
+      markerWritten = true
+    } catch { /* ignore */ }
+  }
+
+  if (!existsSync(hooksPath)) {
+    writeMarker()
+    return { hooksPath, removed: [], backup: null, markerWritten }
+  }
+
+  const data = loadHooksJson(hooksPath)
+  const backup = backupFile(hooksPath)
+  const removed = []
+
+  if (data.hooks && typeof data.hooks === 'object') {
+    for (const event of Object.keys(data.hooks)) {
+      if (!Array.isArray(data.hooks[event])) continue
+      const before = data.hooks[event].length
+      data.hooks[event] = data.hooks[event].filter((entry) => !entry?.[MANAGED_KEY])
+      if (data.hooks[event].length !== before) {
+        removed.push({ event, removedCount: before - data.hooks[event].length })
+      }
+      if (data.hooks[event].length === 0) delete data.hooks[event]
+    }
+    if (Object.keys(data.hooks).length === 0) delete data.hooks
+  }
+
+  saveHooksJson(hooksPath, data)
+  writeMarker()
+  return { hooksPath, removed, backup, markerWritten }
+}
+
+export function inspectHooks({
+  hooksPath = defaultHooksJsonPath(),
+  hookScriptPath = defaultHookScriptPath(),
+} = {}) {
+  const scriptExists = existsSync(hookScriptPath)
+  if (!existsSync(hooksPath)) {
+    return { installed: false, eventsInstalled: [], hooksPath, hookScriptPath, scriptExists }
+  }
+  let data
+  try {
+    data = loadHooksJson(hooksPath)
+  } catch (e) {
+    return { installed: false, eventsInstalled: [], hooksPath, hookScriptPath, scriptExists, error: e.code }
+  }
+  const eventsInstalled = []
+  for (const event of HOOK_EVENTS) {
+    const arr = data?.hooks?.[event]
+    if (!Array.isArray(arr)) continue
+    if (arr.some((entry) => entry?.[MANAGED_KEY])) eventsInstalled.push(event)
+  }
+  return {
+    installed: eventsInstalled.length === HOOK_EVENTS.length,
+    eventsInstalled,
+    hooksPath,
+    hookScriptPath,
+    scriptExists,
+  }
+}
+
+export function deployHookScript({
+  scriptPath = defaultHookScriptPath(),
+  templatePath = defaultTemplatePath(),
+} = {}) {
+  if (!existsSync(templatePath)) {
+    const err = new Error(`hook template not found: ${templatePath}`)
+    err.code = 'hook_template_missing'
+    throw err
+  }
+  const templateContent = readFileSync(templatePath, 'utf8')
+  const templateVersion = parseHookVersion(templateContent)
+
+  const dir = dirname(scriptPath)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+
+  const previousVersion = existsSync(scriptPath)
+    ? parseHookVersion(readFileSync(scriptPath, 'utf8'))
+    : null
+
+  if (previousVersion !== null && previousVersion === templateVersion) {
+    return { action: 'unchanged', version: templateVersion, previousVersion, scriptPath, backup: null }
+  }
+
+  let backup = null
+  if (previousVersion !== null) {
+    backup = `${scriptPath}.bak.${Date.now()}`
+    copyFileSync(scriptPath, backup)
+  }
+  writeFileSync(scriptPath, templateContent)
+  return {
+    action: previousVersion === null ? 'installed' : 'upgraded',
+    version: templateVersion,
+    previousVersion,
+    scriptPath,
+    backup,
+  }
+}
+
+export function bootstrapCursorHooks({
+  hooksPath = defaultHooksJsonPath(),
+  scriptPath = defaultHookScriptPath(),
+  templatePath = defaultTemplatePath(),
+  uninstallMarkerPath = defaultUninstallMarkerPath(),
+  respectUninstallMarker = true,
+} = {}) {
+  if (respectUninstallMarker && existsSync(uninstallMarkerPath)) {
+    return { skipped: true, reason: 'uninstall_marker', uninstallMarkerPath }
+  }
+
+  let markerCleared = false
+  if (!respectUninstallMarker && existsSync(uninstallMarkerPath)) {
+    try { unlinkSync(uninstallMarkerPath); markerCleared = true } catch { /* ignore */ }
+  }
+
+  const scriptResult = deployHookScript({ scriptPath, templatePath })
+
+  const inspect = inspectHooks({ hooksPath, hookScriptPath: scriptPath })
+  if (inspect.error === 'malformed_hooks_json') {
+    return {
+      skipped: true,
+      reason: 'malformed_hooks_json',
+      hooksPath,
+      scriptResult,
+      markerCleared,
+    }
+  }
+
+  if (inspect.installed) {
+    return {
+      skipped: false,
+      alreadyInstalled: true,
+      scriptResult,
+      hookResult: null,
+      markerCleared,
+    }
+  }
+
+  const hookResult = installHooks({
+    hooksPath,
+    hookScriptPath: scriptPath,
+    uninstallMarkerPath,
+    clearUninstallMarker: false,
+  })
+  return {
+    skipped: false,
+    alreadyInstalled: false,
+    scriptResult,
+    hookResult,
+    markerCleared,
+  }
+}
+
+export const __test__ = {
+  buildHookEntry,
+  MANAGED_KEY,
+  HOOK_EVENTS,
+  SCHEMA_VERSION,
+  parseHookVersion,
+  eventToArg,
+  defaultTemplatePath,
+  defaultUninstallMarkerPath,
+}

package/src/templates/codex-hooks/notify.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// quadtodo-hook-version: 2
+/**
+ * AgentQuad Claude Code hook —— 把 PTY 内 Claude Code 的状态事件转推到微信。
+ *
+ * 调用约定：
+ *   - argv[2] = 事件名: stop | notification | session-end
+ *   - stdin = Claude Code 注入的 hook payload（JSON 文本，可空）
+ *   - env: QUADTODO_SESSION_ID  (空 = 非 AgentQuad 启动的 Claude Code，立刻 exit 0)
+ *          QUADTODO_TARGET_USER (微信 peer id)
+ *          QUADTODO_TODO_ID
+ *          QUADTODO_TODO_TITLE
+ *
+ * 故障策略：失败一律静默。这个脚本绝不能阻塞 Claude Code。
+ * - 没注 env → 仍然记日志（"no env"），exit 0
+ * - AgentQuad 没起 / 网络失败 → catch 后记日志，exit 0
+ * - JSON 解析失败 → 当作空 payload 继续
+ *
+ * Debug log: 写到 ~/.agentquad/claude-hooks/hook.log，记每次 fire。
+ * 这样能 100% 区分"hook 没 fire" vs "fire 了但 AgentQuad 没收到"。
+ *
+ * 这个文件是模板源；安装器会拷贝到 ~/.agentquad/claude-hooks/notify.js。
+ * 顶部 `quadtodo-hook-version` 行用于版本比对，升级 AgentQuad 时会自动覆盖旧脚本（带备份）。
+ * 注意：脚本独立运行（不能 import config.js）。LOG_PATH 用 import.meta.url 派生，
+ * 跟随脚本所在目录，自动适配 ~/.agentquad / ~/.quadtodo（legacy）。
+ */
+import { appendFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const LOG_PATH = join(dirname(fileURLToPath(import.meta.url)), 'hook.log')
+
+function logLine(obj) {
+  try {
+    appendFileSync(LOG_PATH, JSON.stringify({ ts: new Date().toISOString(), ...obj }) + '\n', 'utf8')
+  } catch { /* ignore — log 失败也不能阻塞 */ }
+}
+
+const event = (process.argv[2] || 'unknown').toLowerCase()
+const SESSION_ID = process.env.QUADTODO_SESSION_ID
+if (!SESSION_ID) {
+  logLine({ event, status: 'skipped_no_env', argv: process.argv.slice(2) })
+  process.exit(0)
+}
+
+const QUADTODO_URL = process.env.QUADTODO_URL || 'http://127.0.0.1:5677'
+const ENDPOINT = `${QUADTODO_URL}/api/openclaw/hook`
+logLine({ event, status: 'fired', sessionId: SESSION_ID, todoTitle: process.env.QUADTODO_TODO_TITLE })
+
+let raw = ''
+process.stdin.setEncoding('utf8')
+process.stdin.on('data', (chunk) => {
+  raw += chunk
+  // 防止超大 payload 把这个进程占内存
+  if (raw.length > 64 * 1024) raw = raw.slice(0, 64 * 1024)
+})
+process.stdin.on('end', send)
+// 没有 stdin 也要发（例如 SessionEnd 可能不带 payload）
+setTimeout(() => { if (!sent) send() }, 1500).unref?.()
+
+let sent = false
+async function send() {
+  if (sent) return
+  sent = true
+
+  let hookPayload = null
+  if (raw.trim()) {
+    try { hookPayload = JSON.parse(raw) } catch { hookPayload = { _raw: raw.slice(0, 240) } }
+  }
+
+  const body = JSON.stringify({
+    event,
+    sessionId: SESSION_ID,
+    targetUserId: process.env.QUADTODO_TARGET_USER || null,
+    todoId: process.env.QUADTODO_TODO_ID || null,
+    todoTitle: process.env.QUADTODO_TODO_TITLE || null,
+    hookPayload,
+  })
+
+  try {
+    // 30s timeout：openclaw CLI shell-out 实测 4-6s，留足余量；
+    // Claude Code 默认等 hook 60s，所以 30s 安全。
+    const ctrl = new AbortController()
+    const timer = setTimeout(() => ctrl.abort(), 30_000)
+    timer.unref?.()
+    const res = await fetch(ENDPOINT, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body,
+      signal: ctrl.signal,
+    })
+    clearTimeout(timer)
+    if (res.ok) {
+      const data = await res.json().catch(() => null)
+      logLine({ event, status: 'sent', sessionId: SESSION_ID, action: data?.action, reason: data?.reason })
+    } else {
+      const text = await res.text().catch(() => '')
+      logLine({ event, status: 'http_error', code: res.status, body: text.slice(0, 200) })
+    }
+  } catch (e) {
+    logLine({ event, status: 'fetch_error', error: e?.message || String(e) })
+  }
+}

package/src/templates/cursor-hooks/notify.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// quadtodo-hook-version: 2
+/**
+ * AgentQuad Claude Code hook —— 把 PTY 内 Claude Code 的状态事件转推到微信。
+ *
+ * 调用约定：
+ *   - argv[2] = 事件名: stop | notification | session-end
+ *   - stdin = Claude Code 注入的 hook payload（JSON 文本，可空）
+ *   - env: QUADTODO_SESSION_ID  (空 = 非 AgentQuad 启动的 Claude Code，立刻 exit 0)
+ *          QUADTODO_TARGET_USER (微信 peer id)
+ *          QUADTODO_TODO_ID
+ *          QUADTODO_TODO_TITLE
+ *
+ * 故障策略：失败一律静默。这个脚本绝不能阻塞 Claude Code。
+ * - 没注 env → 仍然记日志（"no env"），exit 0
+ * - AgentQuad 没起 / 网络失败 → catch 后记日志，exit 0
+ * - JSON 解析失败 → 当作空 payload 继续
+ *
+ * Debug log: 写到 ~/.agentquad/claude-hooks/hook.log，记每次 fire。
+ * 这样能 100% 区分"hook 没 fire" vs "fire 了但 AgentQuad 没收到"。
+ *
+ * 这个文件是模板源；安装器会拷贝到 ~/.agentquad/claude-hooks/notify.js。
+ * 顶部 `quadtodo-hook-version` 行用于版本比对，升级 AgentQuad 时会自动覆盖旧脚本（带备份）。
+ * 注意：脚本独立运行（不能 import config.js）。LOG_PATH 用 import.meta.url 派生，
+ * 跟随脚本所在目录，自动适配 ~/.agentquad / ~/.quadtodo（legacy）。
+ */
+import { appendFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const LOG_PATH = join(dirname(fileURLToPath(import.meta.url)), 'hook.log')
+
+function logLine(obj) {
+  try {
+    appendFileSync(LOG_PATH, JSON.stringify({ ts: new Date().toISOString(), ...obj }) + '\n', 'utf8')
+  } catch { /* ignore — log 失败也不能阻塞 */ }
+}
+
+const event = (process.argv[2] || 'unknown').toLowerCase()
+const SESSION_ID = process.env.QUADTODO_SESSION_ID
+if (!SESSION_ID) {
+  logLine({ event, status: 'skipped_no_env', argv: process.argv.slice(2) })
+  process.exit(0)
+}
+
+const QUADTODO_URL = process.env.QUADTODO_URL || 'http://127.0.0.1:5677'
+const ENDPOINT = `${QUADTODO_URL}/api/openclaw/hook`
+logLine({ event, status: 'fired', sessionId: SESSION_ID, todoTitle: process.env.QUADTODO_TODO_TITLE })
+
+let raw = ''
+process.stdin.setEncoding('utf8')
+process.stdin.on('data', (chunk) => {
+  raw += chunk
+  // 防止超大 payload 把这个进程占内存
+  if (raw.length > 64 * 1024) raw = raw.slice(0, 64 * 1024)
+})
+process.stdin.on('end', send)
+// 没有 stdin 也要发（例如 SessionEnd 可能不带 payload）
+setTimeout(() => { if (!sent) send() }, 1500).unref?.()
+
+let sent = false
+async function send() {
+  if (sent) return
+  sent = true
+
+  let hookPayload = null
+  if (raw.trim()) {
+    try { hookPayload = JSON.parse(raw) } catch { hookPayload = { _raw: raw.slice(0, 240) } }
+  }
+
+  const body = JSON.stringify({
+    event,
+    sessionId: SESSION_ID,
+    targetUserId: process.env.QUADTODO_TARGET_USER || null,
+    todoId: process.env.QUADTODO_TODO_ID || null,
+    todoTitle: process.env.QUADTODO_TODO_TITLE || null,
+    hookPayload,
+  })
+
+  try {
+    // 30s timeout：openclaw CLI shell-out 实测 4-6s，留足余量；
+    // Claude Code 默认等 hook 60s，所以 30s 安全。
+    const ctrl = new AbortController()
+    const timer = setTimeout(() => ctrl.abort(), 30_000)
+    timer.unref?.()
+    const res = await fetch(ENDPOINT, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body,
+      signal: ctrl.signal,
+    })
+    clearTimeout(timer)
+    if (res.ok) {
+      const data = await res.json().catch(() => null)
+      logLine({ event, status: 'sent', sessionId: SESSION_ID, action: data?.action, reason: data?.reason })
+    } else {
+      const text = await res.text().catch(() => '')
+      logLine({ event, status: 'http_error', code: res.status, body: text.slice(0, 200) })
+    }
+  } catch (e) {
+    logLine({ event, status: 'fetch_error', error: e?.message || String(e) })
+  }
+}