agentquad 0.4.1 → 0.4.4

package/src/pty.js

@@ -2,7 +2,7 @@ import { EventEmitter } from 'node:events'
 import { createRequire } from 'node:module'
 import { randomUUID } from 'node:crypto'
 import { spawnSync, execFile as execFileCb } from 'node:child_process'
-import { readdirSync, statSync, existsSync, watch as fsWatch, mkdirSync, openSync, readSync, closeSync, readFileSync } from 'node:fs'
+import { readdirSync, statSync, existsSync, unlinkSync, watch as fsWatch, mkdirSync, openSync, readSync, closeSync, readFileSync } from 'node:fs'
 import { delimiter, dirname, isAbsolute, join } from 'node:path'
 import { homedir } from 'node:os'
 import { createCodexPromptDetector } from './codex-prompt-detector.js'
@@ -419,7 +419,7 @@ export class PtyManager extends EventEmitter {
    * 会话建立时调 create()、收到前端真实 cols/rows 后再调 startWithSize()，
    * 这样 PTY 永远不会在默认 80×24 上 spawn 一次再 resize。
    */
-  create({ sessionId, tool, prompt, cwd, resumeNativeId, permissionMode, extraEnv }) {
+  create({ sessionId, tool, prompt, cwd, resumeNativeId, permissionMode, extraEnv, mcpConfigPath = null, codexMcpUrl = null }) {
     const toolCfg = this.tools[tool]
     if (!toolCfg) throw new Error(`unknown tool: ${tool}`)
     const baseArgs = toolCfg.args || []
@@ -433,6 +433,18 @@ export class PtyManager extends EventEmitter {
     // Claude 支持 --session-id <uuid>：新会话时由我们预生成，避免事后靠 FS/输出扫描。
     const presetClaudeId = tool === 'claude' && !resumeNativeId ? randomUUID() : null
     const claudeSessionArgs = presetClaudeId ? ['--session-id', presetClaudeId] : []
+    // AgentQuad runtime MCP config injection
+    const mcpConfigArgs = (tool === 'claude' && mcpConfigPath)
+      ? ['--mcp-config', mcpConfigPath]
+      : []
+    // Codex 用 --config key=value 直接覆写（不需要文件）
+    // 注意 codex 把 value 当 TOML 表达式解析，URL 字符串要带双引号
+    const codexMcpArgs = (tool === 'codex' && codexMcpUrl)
+      ? [
+          '-c', `mcp_servers.agentquad.url="${codexMcpUrl}"`,
+          '-c', 'mcp_servers.agentquad.transport="http"',
+        ]
+      : []
 
     // cursor-agent 没有 --session-id 预置，但有 `cursor-agent create-chat` 异步建会话拿 chatId。
     // 新会话先异步跑 create-chat，拿到 chatId 后在 startWithSize() 里用 --resume 进交互模式。
@@ -445,17 +457,21 @@ export class PtyManager extends EventEmitter {
 
     let args
     if (resumeNativeId) {
-      if (tool === 'codex') args = [...baseArgs, ...permissionArgs, 'resume', resumeNativeId]
+      if (tool === 'codex') args = [...baseArgs, ...permissionArgs, ...codexMcpArgs, 'resume', resumeNativeId]
       else if (tool === 'cursor') args = [...baseArgs, ...permissionArgs, '--resume', resumeNativeId]
-      else args = [...baseArgs, ...permissionArgs, ...disallowedToolsArgs, '--resume', resumeNativeId]
+      else args = [...baseArgs, ...permissionArgs, ...disallowedToolsArgs, ...mcpConfigArgs, '--resume', resumeNativeId]
     } else if (tool === 'cursor' && cursorResumeId) {
       args = useCliPrompt
         ? [...baseArgs, ...permissionArgs, '--resume', cursorResumeId, prompt]
         : [...baseArgs, ...permissionArgs, '--resume', cursorResumeId]
     } else {
+      // 关键：mcpConfigArgs（--mcp-config <FILE>）必须放在某个 --<flag> 之前，
+      // 否则 Claude 的变长 --mcp-config 会贪婪吃后面的 prompt 当成 "另一个配置文件"
+      // （Claude Code GitHub issue #5593 同一类问题）。
+      // 因此把 mcpConfigArgs 放在 claudeSessionArgs (--session-id) 之前。
       args = useCliPrompt
-        ? [...baseArgs, ...permissionArgs, ...disallowedToolsArgs, ...claudeSessionArgs, prompt]
-        : [...baseArgs, ...permissionArgs, ...disallowedToolsArgs, ...claudeSessionArgs]
+        ? [...baseArgs, ...permissionArgs, ...disallowedToolsArgs, ...mcpConfigArgs, ...claudeSessionArgs, ...codexMcpArgs, prompt]
+        : [...baseArgs, ...permissionArgs, ...disallowedToolsArgs, ...mcpConfigArgs, ...claudeSessionArgs, ...codexMcpArgs]
     }
     let effectiveCwd = cwd || process.env.HOME || process.cwd()
 
@@ -510,6 +526,7 @@ export class PtyManager extends EventEmitter {
       detector: null,
       lastTuiAlertAt: 0,
       cursorChatPromise,
+      mcpConfigPath: mcpConfigPath || null,
       spawnSpec: {
         args,
         env,
@@ -572,6 +589,10 @@ export class PtyManager extends EventEmitter {
     } catch (error) {
       // ptyFactory failed → session record is stranded (no proc → no onExit to clean it up).
       // Remove it explicitly so callers can retry / start a new session with the same id.
+      // Task 10: 防止 ptyFactory 失败时孤立 runtime mcp config 文件
+      if (session.mcpConfigPath) {
+        try { if (existsSync(session.mcpConfigPath)) unlinkSync(session.mcpConfigPath) } catch { /* ignore */ }
+      }
       this.sessions.delete(sessionId)
       error.message = `PTY spawn failed for ${tool} (bin=${toolCfg.bin}, cwd=${effectiveCwd}, args=${JSON.stringify(args)}): ${error.message}`
       throw error
@@ -846,6 +867,10 @@ export class PtyManager extends EventEmitter {
       if (this.sidecar && session.tool === 'codex' && session.nativeId) {
         try { this.sidecar.clear(session.nativeId) } catch { /* ignore */ }
       }
+      // Cleanup runtime MCP config file (Task 10)
+      if (session.mcpConfigPath) {
+        try { if (existsSync(session.mcpConfigPath)) unlinkSync(session.mcpConfigPath) } catch { /* ignore */ }
+      }
       const fullLog = session.fullLog.join('')
       this.sessions.delete(sessionId)
       this.emit('done', {
@@ -979,6 +1004,10 @@ export class PtyManager extends EventEmitter {
       if (s.detectTimer) { try { clearInterval(s.detectTimer) } catch { /* ignore */ } s.detectTimer = null }
       if (s.cursorWatchTimer) { try { clearInterval(s.cursorWatchTimer) } catch { /* ignore */ } s.cursorWatchTimer = null }
       if (s.fsWatcher) { try { s.fsWatcher.close() } catch { /* ignore */ } s.fsWatcher = null }
+      // Cleanup runtime MCP config file (Task 10)
+      if (s.mcpConfigPath) {
+        try { if (existsSync(s.mcpConfigPath)) unlinkSync(s.mcpConfigPath) } catch { /* ignore */ }
+      }
       this.sessions.delete(sessionId)
       this.emit('done', {
         sessionId,

package/src/routes/ai-terminal.js

@@ -3,8 +3,12 @@ import { spawnSync } from 'node:child_process'
 import { Router } from 'express'
 import { writeFile, mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
+import { homedir } from 'node:os'
 import pidusage from 'pidusage'
 import { loadConfig, resolveToolsConfig, SUPPORTED_TOOLS, DEFAULT_ROOT_DIR } from '../config.js'
+import { writeRuntimeMcpConfig } from '../agent-installer-shared.js'
+import { CLAUDE_DEFAULT_PERMISSION_OPTIONS, extractPermissionPrompt, formatToolUseAsPrompt } from '../permission-prompt.js'
+import { findLatestPendingToolUse } from '../claude-transcript.js'
 
 const MAX_OUTPUT_BUFFER = 5 * 1024 * 1024
 const CLEANUP_MS = 30 * 60_000
@@ -160,7 +164,10 @@ export function createAiTerminal({ db, pty, logDir, defaultCwd, getDefaultCwd, o
     if (session.status === 'running' && session.awaitingReply === false) return false
     session.status = 'running'
     session.awaitingReply = false
-    if (wasPending) session.recentOutput = ''
+    if (wasPending) {
+      session.recentOutput = ''
+      session.permissionPrompt = null
+    }
     persistLiveSessionState(session, 'running', 'ai_running')
     if (wasPending) broadcastToSession(session, { type: 'pending_cleared' })
     return true
@@ -182,12 +189,73 @@ export function createAiTerminal({ db, pty, logDir, defaultCwd, getDefaultCwd, o
   // 也翻 pending_confirm，会让 session 在 AI 完成回话之后无故卡在"待确认"，前端没有任何
   // 入口能把它清掉（focus 只清 unread；markSessionRunningAfterInput 需要真实输入）。
   // 所以 idle / 其它非 running 状态下，直接拒绝翻转。
-  function markPendingConfirm(sessionId, { source = null } = {}) {
+  // promptText 可由 caller 显式传入（Codex 的 prompt-detector 已经握有一段干净文本）；
+  // 不传则从 session.recentOutput 提取尾部（Claude Notification 路径走这条）。
+  // 状态已经是 pending_confirm 时也允许更新 pendingPrompt —— 同一轮等待中 PTY
+  // 可能继续追加输出（如选项变化、高亮位移），让前端拿到最新文案。
+  function markPendingConfirm(sessionId, { source = null, promptText = null } = {}) {
     const session = sessions.get(sessionId)
     if (!session) return false
     if (!LIVE_AI_STATUSES.has(session.status)) return false
-    if (session.status === 'pending_confirm') return true
-    if (session.status !== 'running') return false
+    const wasPending = session.status === 'pending_confirm'
+    if (!wasPending && session.status !== 'running') return false
+
+    let text = ''
+    let options = []
+
+    // Claude 优先走 jsonl 路径：Notification fire 时 jsonl 末尾通常已经写好了
+    // pending 的 tool_use 块（Bash 命令、Edit 文件 path 等），结构化、无 ANSI 噪声。
+    if (!promptText && session.tool === 'claude' && session.nativeSessionId && pty?.findClaudeSession) {
+      try {
+        const loc = pty.findClaudeSession(session.nativeSessionId)
+        if (loc?.filePath) {
+          const toolUse = findLatestPendingToolUse(loc.filePath)
+          if (toolUse) {
+            text = formatToolUseAsPrompt(toolUse)
+            options = CLAUDE_DEFAULT_PERMISSION_OPTIONS
+          }
+        }
+      } catch { /* ignore — 走 PTY 兜底 */ }
+    }
+
+    // 兜底：从 PTY 提取（Codex 主路径 / Claude jsonl 拿不到时的 backup）。
+    // recentOutput 是 4KB 滑窗，TUI redraw 抖动会冲掉真实 prompt 文本；
+    // 再兜底用 outputHistory（最大 5MB）的尾部 ~64KB，让 extractor 能找到锚点。
+    if (!text) {
+      const extractSource = promptText || session.recentOutput || ''
+      let historicalRaw = null
+      if (!promptText && Array.isArray(session.outputHistory) && session.outputHistory.length > 0) {
+        const joined = session.outputHistory.join('')
+        historicalRaw = joined.length > 65536 ? joined.slice(-65536) : joined
+      }
+      const r = extractPermissionPrompt(extractSource, { historicalRaw })
+      text = r.text
+      options = r.options
+    }
+    const hasContent = !!(text || options.length)
+    const prevPrompt = session.permissionPrompt || null
+
+    if (wasPending) {
+      // 已经是 pending_confirm：只在 prompt 文本/选项真的有变化时才更新并再广播。
+      // 多次 Notification/detector 在同一轮内反复 fire 是常态，不能每次都刷前端。
+      const sameText = (prevPrompt?.text || '') === text
+      const sameOptions = JSON.stringify(prevPrompt?.options || []) === JSON.stringify(options)
+      if (!hasContent || (sameText && sameOptions)) return true
+      session.permissionPrompt = { text, options, source: source || 'hook', createdAt: Date.now() }
+      broadcastToSession(session, {
+        type: 'pending_confirm',
+        snippet: session.recentOutput ? session.recentOutput.slice(-500) : '',
+        promptText: text,
+        options,
+        source: source || 'hook',
+      })
+      return true
+    }
+
+    session.permissionPrompt = hasContent
+      ? { text, options, source: source || 'hook', createdAt: Date.now() }
+      : null
+
     session.status = 'pending_confirm'
     const todo = db.getTodo(session.todoId)
     if (todo) {
@@ -209,6 +277,8 @@ export function createAiTerminal({ db, pty, logDir, defaultCwd, getDefaultCwd, o
     broadcastToSession(session, {
       type: 'pending_confirm',
       snippet: session.recentOutput ? session.recentOutput.slice(-500) : '',
+      promptText: text,
+      options,
       source: source || 'hook',
     })
     return true
@@ -439,7 +509,7 @@ export function createAiTerminal({ db, pty, logDir, defaultCwd, getDefaultCwd, o
   })
 
   // ─── 程序化 session 启动入口（供 orchestrator 等模块直接调用，跳过 HTTP） ───
-  function spawnSession({ todoId, prompt, tool, cwd, resumeNativeId, permissionMode, label, extraEnv, sessionId: externalSessionId, skipTelegram = false, ignoreExistingNativeSessionId = false }) {
+  function spawnSession({ todoId, prompt, tool, cwd, resumeNativeId, permissionMode, label, extraEnv, sessionId: externalSessionId, skipTelegram = false, ignoreExistingNativeSessionId = false, parentTodoId = null }) {
     if (!todoId || typeof prompt !== 'string' || !tool) {
       const err = new Error('missing todoId, prompt, or tool'); err.code = 'bad_request'
       throw err
@@ -522,6 +592,38 @@ export function createAiTerminal({ db, pty, logDir, defaultCwd, getDefaultCwd, o
         QUADTODO_TODO_ID: String(todoId),
         QUADTODO_TODO_TITLE: String(todo.title || ''),
       }
+      // Task 10: 嵌套深度 + 父 todo id 注入
+      const parentDepthRaw = process.env.QUADTODO_DEPTH
+      const parentDepth = parentDepthRaw !== undefined && parentDepthRaw !== '' ? Number(parentDepthRaw) : -1
+      autoEnv.QUADTODO_DEPTH = String(parentDepth + 1)
+      // parentTodoId 优先来自 MCP 工具显式传入；否则 fallback 到 process.env（适合 PTY 嵌套场景，但 AgentQuad 主进程通常没设）
+      autoEnv.QUADTODO_PARENT_TODO_ID = parentTodoId != null
+        ? String(parentTodoId)
+        : String(process.env.QUADTODO_TODO_ID || '')
+      // 添加 QUADTODO_URL 让 hook/child agent 知道访问哪个端口
+      const cfgPort = cfg?.port || 5677
+      autoEnv.QUADTODO_URL = `http://127.0.0.1:${cfgPort}`
+
+      // Task 10: 运行时 MCP 配置注入（C 方案）— claude 走 --mcp-config <file>
+      let runtimeMcpPath = null
+      if (tool === 'claude') {
+        try {
+          const runtimeDir = cfg?.agents?.runtimeDir
+            ? cfg.agents.runtimeDir.replace(/^~/, homedir())
+            : join(homedir(), '.agentquad', 'run')
+          const out = writeRuntimeMcpConfig({ runtimeDir, sessionId, port: cfgPort, tool: 'claude' })
+          runtimeMcpPath = out.path
+        } catch (e) {
+          console.warn(`[ai-terminal] runtime mcp config write failed: ${e.message}`)
+        }
+      }
+
+      // Task 11: Codex 走 --config <key=value>，不需要文件，只需要构造 URL
+      let codexMcpUrl = null
+      if (tool === 'codex') {
+        codexMcpUrl = `http://127.0.0.1:${cfgPort}/mcp`
+      }
+
       // 1. 先 pty.create 让 PtyManager 把 presetClaudeId / resumeNativeId 落进 session 记录。
       pty.create({
         sessionId,
@@ -532,6 +634,8 @@ export function createAiTerminal({ db, pty, logDir, defaultCwd, getDefaultCwd, o
         resumeNativeId: resumeNativeId || undefined,
         permissionMode: permissionMode || null,
         extraEnv: { ...(extraEnv || {}), ...autoEnv },
+        mcpConfigPath: runtimeMcpPath,
+        codexMcpUrl,
       })
       // 2. 读出 preset nativeId（claude 新会话 = randomUUID, resume = resumeNativeId, codex 新 = null）。
       //    这是让"首屏即正确"成立的核心：先于 db.updateTodo 拿到值。
@@ -657,6 +761,7 @@ export function createAiTerminal({ db, pty, logDir, defaultCwd, getDefaultCwd, o
           lastTurnDoneAt: s.lastTurnDoneAt || null,
           outputBytesTotal: s.outputBytesTotal || 0,
           awaitingReply: !!s.awaitingReply,
+          permissionPrompt: s.permissionPrompt || null,
         })
       }
       res.json({ ok: true, sessions: out })
@@ -771,7 +876,7 @@ export function createAiTerminal({ db, pty, logDir, defaultCwd, getDefaultCwd, o
 
   // ─── WebSocket hooks (called from server.js on upgrade) ───
 
-  function addBrowser(sessionId, ws) {
+  function addBrowser(sessionId, ws, { role = 'secondary' } = {}) {
     const session = sessions.get(sessionId)
     if (!session) {
       try {
@@ -780,7 +885,12 @@ export function createAiTerminal({ db, pty, logDir, defaultCwd, getDefaultCwd, o
       } catch { /* ignore */ }
       return
     }
+    const effectiveRole = role === 'primary' ? 'primary' : 'secondary'
+    if (ws) ws.__quadtodoRole = effectiveRole
     session.browsers.add(ws)
+    // 不分 primary / secondary，都回放——否则 reopen SessionFocus 会看到一片空白。
+    // 旧顾虑是"窄 cols 时代 scrollback 在宽 viewer 里重排乱码"；现在交给 init/resize 后
+    // TUI 的 SIGWINCH 自重绘兜底，replay 内容沉到 scrollback 上面、用户可滚回去看。
     if (session.outputHistory.length > 0) {
       ws.send(JSON.stringify({ type: 'replay', chunks: session.outputHistory }))
     }
@@ -802,18 +912,43 @@ export function createAiTerminal({ db, pty, logDir, defaultCwd, getDefaultCwd, o
   // 同一个 session 被多个网页同时打开时（比如你在另一个 tab/window 又开了一遍
   // 同一个 todo），每个 tab 的 xterm fit 出的 cols/rows 都不一样，谁最后发谁
   // 赢就会在两个尺寸之间来回抖，Claude 的 TUI 不停重排、scrollback 全是残影。
-  // 取所有在线浏览器上报尺寸的 **最小值** 发给 PTY：最窄的窗口看得下，更宽的
-  // tab 只是右边留空白，整体输出保持稳定。
+  //
+  // 聚合策略：
+  // - 若有任意 viewer 声明 role='primary'（当前只有 SessionFocus 全屏视图会这么报）
+  //   → 只用 primary viewer 的尺寸，多个 primary 之间仍取 min 兜底
+  //   secondary viewer（Dock 卡片、迷你窗等）一律忽略，靠 xterm 软折行自己处理
+  // - 没有 primary → 退回历史行为：所有 viewer 的 min 聚合
   function applyAggregatedResize(session) {
     if (!canResizeSession(session)) return
 
-    let cols = Infinity
-    let rows = Infinity
+    let primaryCols = Infinity
+    let primaryRows = Infinity
+    let hasPrimary = false
+    let fallbackCols = Infinity
+    let fallbackRows = Infinity
+    let hasFallback = false
     for (const b of session.browsers) {
       const sz = b.__quadtodoSize
       if (!sz || !isValidResizeSize(sz.cols, sz.rows)) continue
-      if (sz.cols < cols) cols = sz.cols
-      if (sz.rows < rows) rows = sz.rows
+      if (b.__quadtodoRole === 'primary') {
+        hasPrimary = true
+        if (sz.cols < primaryCols) primaryCols = sz.cols
+        if (sz.rows < primaryRows) primaryRows = sz.rows
+      } else {
+        hasFallback = true
+        if (sz.cols < fallbackCols) fallbackCols = sz.cols
+        if (sz.rows < fallbackRows) fallbackRows = sz.rows
+      }
+    }
+    let cols, rows
+    if (hasPrimary) {
+      cols = primaryCols
+      rows = primaryRows
+    } else if (hasFallback) {
+      cols = fallbackCols
+      rows = fallbackRows
+    } else {
+      return
     }
     if (!isValidResizeSize(cols, rows)) return
     cols = clampPtyCols(cols)
@@ -823,10 +958,17 @@ export function createAiTerminal({ db, pty, logDir, defaultCwd, getDefaultCwd, o
     pty.resize(session.sessionId, cols, rows)
   }
 
-  // \r=Enter \n=LF \x03=Ctrl+C \x04=Ctrl+D —— 这些才会真正让 Claude/Codex 的 confirm 提示推进
+  // \r=Enter \n=LF \x03=Ctrl+C \x04=Ctrl+D 以及裸 ESC（\x1b 或 \x1b\x1b）——
+  // 这些才会真正让 Claude/Codex 的 confirm 提示推进。前端"拒绝"按钮发的就是裸 ESC，
+  // 不在这里命中的话 markSessionRunningAfterInput 不跑、permissionPrompt 永远不清，
+  // 卡片就一直显示，按钮 disabled，看起来像 UI 卡住。
+  // 注意：箭头键 '\x1b[A' / 焦点序列 '\x1b[I' 等 ANSI 序列不能命中——所以只匹配
+  // "正好等于裸 ESC"，与 isInterruptInput 同样的判定。
   function isPendingClearingInput(data) {
     if (typeof data !== 'string' || !data) return false
-    return /[\r\n\x03\x04]/.test(data)
+    if (/[\r\n\x03\x04]/.test(data)) return true
+    if (data === '\x1b' || data === '\x1b\x1b') return true
+    return false
   }
 
   // 用户希望"打断当前轮"的按键：Ctrl+C（\x03）或 Esc（裸 \x1b / \x1b\x1b）。
@@ -993,6 +1135,11 @@ export function createAiTerminal({ db, pty, logDir, defaultCwd, getDefaultCwd, o
       const session = sessions.get(sessionId)
       if (!session) return
       if (!isValidResizeSize(cols, rows)) return
+      // role 字段可选：addBrowser 时已经按 WS URL ?role= 设过 ws.__quadtodoRole；
+      // 这里只在 init 显式带 role 时才覆盖（保留首次"primary"声明不被无 role 的 init 静默打回）
+      if (ws && (msg.role === 'primary' || msg.role === 'secondary')) {
+        ws.__quadtodoRole = msg.role
+      }
       if (!session.spawned) {
         if (session.spawnFallbackTimer) {
           clearTimeout(session.spawnFallbackTimer)
@@ -1023,6 +1170,11 @@ export function createAiTerminal({ db, pty, logDir, defaultCwd, getDefaultCwd, o
       const rows = Number(msg.rows)
       const session = sessions.get(sessionId)
       if (!canResizeSession(session)) return
+      // role 字段可选：只在显式传入时更新，避免普通 resize 把已声明的 primary
+      // 静默打回 secondary
+      if (ws && (msg.role === 'primary' || msg.role === 'secondary')) {
+        ws.__quadtodoRole = msg.role
+      }
       if (ws && session.browsers.has(ws)) {
         if (!isValidResizeSize(cols, rows)) {
           delete ws.__quadtodoSize

package/src/server.js

@@ -1659,8 +1659,9 @@ export function createServer(opts = {}) {
 		const url = new URL(req.url || "", "http://127.0.0.1");
 		if (url.pathname.startsWith("/ws/terminal/")) {
 			const sessionId = url.pathname.replace("/ws/terminal/", "");
+			const role = url.searchParams.get("role") === "primary" ? "primary" : "secondary";
 			wss.handleUpgrade(req, socket, head, (ws) =>
-				handleBrowserWs(ws, sessionId),
+				handleBrowserWs(ws, sessionId, role),
 			);
 		} else {
 			socket.destroy();
@@ -1669,8 +1670,8 @@ export function createServer(opts = {}) {
 
 	const HEARTBEAT_MS = 15_000;
 
-	function handleBrowserWs(ws, sessionId) {
-		ait.addBrowser(sessionId, ws);
+	function handleBrowserWs(ws, sessionId, role) {
+		ait.addBrowser(sessionId, ws, { role });
 
 		ws.on("message", (raw) => {
 			try {

package/src/templates/agent-skills/agentquad-child.cursor.mdc

@@ -0,0 +1,26 @@
+---
+description: Use when the user mentions quadtodo / agentquad / 四象限 todo or wants to split a task into sub-tasks delegated to AI agents.
+alwaysApply: false
+---
+
+# AgentQuad 子任务委派
+
+## 你身处的环境
+- 你正在通过 Cursor 操作一个 AgentQuad（本地四象限 AI 任务调度器）项目
+- AgentQuad 的 MCP 服务在 `http://127.0.0.1:<port>/mcp`（已通过 mcp 连接）
+- 当前 Cursor 会话本身不是 AgentQuad 启动的，所以没有 `QUADTODO_*` 环境变量
+
+## 何时触发本 rule
+- 用户说"在 AgentQuad 加一条 todo / 拆出去给另一个 agent / 看下我的四象限"
+- 用户提到 quadtodo / agentquad / 四象限 todo
+
+## 操作流程
+1. `list_quadrants` → 决定象限（默认 Q2）
+2. `create_todo(title, quadrant, description, parentId?)` → 拿到 todo id
+3. （可选）`start_ai_session(todoId, tool="claude"|"codex", prompt)` → 把任务交给一个本地 PTY agent
+4. 告诉用户 ticket / id，及它在 AgentQuad web UI（http://127.0.0.1:5677 或 user 配置端口）里可见
+
+## 重要约束
+- 创建前先与用户对齐范围与象限
+- `start_ai_session` 默认 `permissionMode=bypass`，子 agent 有写权限，慎重
+- Cursor 无法被 `start_ai_session` 拉起 —— 拉子 agent 只能选 claude / codex

package/src/templates/agent-skills/agentquad-child.skill.md

@@ -0,0 +1,29 @@
+---
+name: agentquad-child
+description: |
+  Use when the user wants to split the current AgentQuad task into a sub-task and delegate it to another AI agent. Activates inside AgentQuad-launched sessions (env QUADTODO_SESSION_ID present) or when the user explicitly mentions AgentQuad / 四象限 todo.
+---
+
+# AgentQuad 子任务委派
+
+## 你身处的环境
+- 你运行在 AgentQuad（本地四象限 AI 任务调度器）里
+- 父任务的 ID 在环境变量 `QUADTODO_TODO_ID`，标题在 `QUADTODO_TODO_TITLE`
+- AgentQuad 的 MCP 服务地址在 `QUADTODO_URL`（已通过 mcp 连接，无需手动配置）
+- `QUADTODO_DEPTH` 表示嵌套层级（0=顶层，1+=被另一个 agent 启动）
+
+## 何时触发本 skill
+- 用户说"把 X 拆出去 / 另起一个 agent 干 / 开个分支任务"
+- 你判断当前任务过大、应该拆分
+- 用户主动要求创建/查看/管理 AgentQuad todo
+
+## 操作流程
+1. `list_quadrants` → 决定子任务放哪个象限（默认 Q2 重要不紧急）
+2. `create_todo(title, quadrant, parentId=<父 TODO_ID>, description)` → 拿到子 todo id
+3. （可选）`start_ai_session(todoId=<子 id>, parentTodoId=<env QUADTODO_TODO_ID 的值>, tool="claude"|"codex", prompt=<明确任务说明>)`
+4. 把 ticket / 子 id 告诉用户
+
+## 重要约束
+- 拆子任务前先**和用户对齐范围**，不要无脑拆
+- 不要为了拆而拆 —— 子任务必须有清晰的、独立可完成的目标
+- `start_ai_session` 默认 `permissionMode=bypass`，子 agent 默认有写权限，慎重