claude-coder 1.5.1 → 1.5.2

package/docs/ARCHITECTURE.md

@@ -85,7 +85,7 @@ flowchart TB
 
     subgraph SDK["Claude Agent SDK"]
         query["query() 函数"]
-        hook_sys["PreToolUse hook<br/>内联回调"]
+        hook_sys["PreToolUse hook<br/>hooks.js 工厂"]
     end
 
     subgraph Files["文件系统 (.claude-coder/)"]
@@ -154,11 +154,12 @@ flowchart LR
 ## 3. 模块职责
 
 ```
-bin/cli.js          CLI 入口：参数解析、命令路由、SDK peerDep 检查
+bin/cli.js          CLI 入口：参数解析、命令路由
 src/
   config.js         配置管理：.env 加载、模型映射、环境变量构建、全局同步
   runner.js         主循环：scan → session → validate → retry/rollback
-  session.js        SDK 交互：query() 调用、hook 绑定、停顿检测、日志流
+  session.js        SDK 交互：query() 调用、SDK 加载、日志流
+  hooks.js          Hook 工厂：停顿检测 + 编辑死循环防护（可复用于所有 session 类型）
   prompts.js        提示语构建：系统 prompt 组合 + 条件 hint + 任务分解指导
   init.js           环境初始化：读取 profile 执行依赖安装、服务启动、健康检查
   scanner.js        初始化扫描：调用 runScanSession + 重试
@@ -184,7 +185,8 @@ templates/
 | `bin/cli.js` | CLI 入口 |
 | `src/config.js` | .env 加载、模型映射 |
 | `src/runner.js` | Harness 主循环 |
-| `src/session.js` | SDK query() 封装 + hook |
+| `src/session.js` | SDK query() 封装 + 日志流 |
+| `src/hooks.js` | Hook 工厂（停顿检测 + 编辑防护，可复用于所有 session 类型） |
 | `src/prompts.js` | 提示语构建（系统 prompt + 条件 hint + 任务分解指导） |
 | `src/init.js` | 环境初始化（依赖安装、服务启动） |
 | `src/scanner.js` | 项目初始化扫描 |
@@ -250,7 +252,7 @@ flowchart TB
 |---|---|---|---|
 | **编码** | CLAUDE.md | `buildCodingPrompt()` + 11 个条件 hint | 主循环每次迭代 |
 | **扫描** | CLAUDE.md + SCAN_PROTOCOL.md | `buildScanPrompt()` + 任务分解指导 + profile 质量要求 | 首次运行 |
-| **追加** | CLAUDE.md | `buildAddPrompt()` + 任务分解指导 | `claude-coder add` |
+| **追加** | 精简角色提示（不注入 CLAUDE.md） | `buildAddPrompt()` + 任务分解指导 + session_result 格式 | `claude-coder add` |
 
 ### 编码 Session 的 11 个条件 Hint
 
@@ -372,19 +374,19 @@ flowchart TD
     end
 
     subgraph after ["优化后：Harness 注入上下文"]
-        B1["Harness 预读文件"] --> B2["注入 Hint 7: 任务上下文"]
-        B1 --> B3["注入 Hint 8: 会话记忆"]
+        B1["Harness 预读文件"] --> B2["注入 Hint 6: 任务上下文"]
+        B1 --> B3["注入 Hint 7: 会话记忆"]
         B2 --> B4["Agent prompt 就绪"]
         B3 --> B4
         B4 --> B5["Agent 直接开始编码"]
     end
 ```
 
-### Hint 7: 任务上下文注入
+### Hint 6: 任务上下文注入
 
 Harness 在 `buildCodingPrompt()` 中预读 `tasks.json`，将下一个待办任务的 id、description、category、steps 数量和整体进度注入 user prompt。Agent 无需自行读取 `tasks.json`。
 
-### Hint 8: 会话记忆注入
+### Hint 7: 会话记忆注入
 
 Harness 在 `buildCodingPrompt()` 中预读 `session_result.json`，将上次会话的 task_id、结果和 notes 摘要注入 user prompt。Agent 无需自行读取历史 session 数据。
 
@@ -470,13 +472,6 @@ query({
 
 ### P0 — 近期
 
-| 方向 | 说明 |
-|------|------|
-| **文件保护 Deny-list** | PreToolUse hook 拦截对保护文件的写入（比文字规则更硬性） |
-| **成本预算控制** | `.env` 新增 `MAX_COST_USD`，超预算自动停止 |
-
-### P1 — 中期
-
 | 方向 | 说明 |
 |------|------|
 | **TCR 纪律** | Test && Commit \|\| Revert，可配置 strict/smart/off |
@@ -484,7 +479,7 @@ query({
 | **Reminders 注入** | 用户自定义提醒文件，拼接到编码 prompt |
 | **MCP 工具自动检测** | `claude mcp list` 自动启用已安装工具 |
 
-### P2 — 远期
+### P1 — 远期
 
 | 方向 | 说明 |
 |------|------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-coder",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "Claude Coder — Autonomous coding agent harness powered by Claude Code SDK. Scan, plan, code, validate, git-commit in a loop.",
   "bin": {
     "claude-coder": "bin/cli.js"

package/src/hooks.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const { inferPhaseStep } = require('./indicator');
+const { log } = require('./config');
+
+const EDIT_THRESHOLD = 5;
+
+function logToolCall(logStream, input) {
+  if (!logStream) return;
+  const target = input.tool_input?.file_path || input.tool_input?.path || '';
+  const cmd = input.tool_input?.command || '';
+  const pattern = input.tool_input?.pattern || '';
+  const detail = target || cmd.slice(0, 200) || (pattern ? `pattern: ${pattern}` : '');
+  if (detail) {
+    logStream.write(`[${new Date().toISOString()}] ${input.tool_name}: ${detail}\n`);
+  }
+}
+
+/**
+ * Create unified session hooks with configurable stall detection and edit guard.
+ * @param {Indicator} indicator
+ * @param {WriteStream|null} logStream
+ * @param {object} [options]
+ * @param {boolean} [options.enableStallDetection=false]
+ * @param {number}  [options.stallTimeoutMs=1800000]
+ * @param {boolean} [options.enableEditGuard=false]
+ * @returns {{ hooks: object, cleanup: () => void, isStalled: () => boolean }}
+ */
+function createSessionHooks(indicator, logStream, options = {}) {
+  const {
+    enableStallDetection = false,
+    stallTimeoutMs = 1800000,
+    enableEditGuard = false,
+  } = options;
+
+  const editCounts = {};
+  let stallDetected = false;
+  let stallChecker = null;
+
+  if (enableStallDetection) {
+    stallChecker = setInterval(() => {
+      const idleMs = Date.now() - indicator.lastToolTime;
+      if (idleMs > stallTimeoutMs && !stallDetected) {
+        stallDetected = true;
+        const idleMin = Math.floor(idleMs / 60000);
+        log('warn', `无新工具调用超过 ${idleMin} 分钟，自动中断 session`);
+        if (logStream) {
+          logStream.write(`[${new Date().toISOString()}] STALL: 无工具调用 ${idleMin} 分钟，自动中断\n`);
+        }
+      }
+    }, 30000);
+  }
+
+  const hooks = {
+    PreToolUse: [{
+      matcher: '*',
+      hooks: [async (input) => {
+        inferPhaseStep(indicator, input.tool_name, input.tool_input);
+        logToolCall(logStream, input);
+
+        if (enableEditGuard) {
+          const target = input.tool_input?.file_path || input.tool_input?.path || '';
+          if (['Write', 'Edit', 'MultiEdit'].includes(input.tool_name) && target) {
+            editCounts[target] = (editCounts[target] || 0) + 1;
+            if (editCounts[target] > EDIT_THRESHOLD) {
+              return {
+                decision: 'block',
+                message: `已对 ${target} 编辑 ${editCounts[target]} 次，疑似死循环。请重新审视方案后再继续。`,
+              };
+            }
+          }
+        }
+
+        return {};
+      }]
+    }]
+  };
+
+  return {
+    hooks,
+    cleanup() { if (stallChecker) clearInterval(stallChecker); },
+    isStalled() { return stallDetected; },
+  };
+}
+
+module.exports = { createSessionHooks };

package/src/prompts.js

@@ -209,6 +209,15 @@ function buildScanPrompt(projectType, requirement) {
   ].join('\n');
 }
 
+/**
+ * Build lightweight system prompt for add sessions.
+ * Add sessions only decompose requirements — no coding workflow needed.
+ * CLAUDE.md is NOT injected to avoid role conflict and save ~2000 tokens.
+ */
+function buildAddSystemPrompt() {
+  return '你是一个任务分解专家，擅长将模糊需求拆解为结构化、可执行的原子任务。你只分析需求和分解任务，不实现任何代码。';
+}
+
 /**
  * Build user prompt for add sessions.
  * Structure: Role (primacy) → Context → CoT → TaskGuide → Instruction (recency)
@@ -276,7 +285,7 @@ function buildAddPrompt(instruction) {
     '5. 分解任务：每个任务对应一个独立可测试的功能单元，description 简明（40字内），steps 具体可操作',
     '6. 追加到 tasks.json，id 和 priority 从已有最大值递增，status: pending',
     '7. git add -A && git commit -m "chore: add new tasks"',
-    '8. 写入 session_result.json',
+    '8. 写入 session_result.json（格式：{ "session_result": "success", "task_id": "add-tasks", "status_before": "N/A", "status_after": "N/A", "git_commit": "hash", "tests_passed": false, "notes": "追加了 N 个任务：简述" }）',
     '',
 
     // --- Quality constraints ---
@@ -295,5 +304,6 @@ module.exports = {
   buildCodingPrompt,
   buildTaskGuide,
   buildScanPrompt,
+  buildAddSystemPrompt,
   buildAddPrompt,
 };

package/src/runner.js

@@ -5,35 +5,15 @@ const path = require('path');
 const readline = require('readline');
 const { execSync } = require('child_process');
 const { paths, log, COLOR, loadConfig, ensureLoopDir, getProjectRoot } = require('./config');
-const { loadTasks, saveTasks, getFeatures, getStats, findNextTask } = require('./tasks');
+const { loadTasks, getFeatures, getStats, findNextTask, forceStatus } = require('./tasks');
 const { validate } = require('./validator');
 const { scan } = require('./scanner');
-const { runCodingSession, runAddSession } = require('./session');
+const { loadSDK, runCodingSession, runAddSession } = require('./session');
 
 const MAX_RETRY = 3;
 
-async function requireSdk() {
-  const pkgName = '@anthropic-ai/claude-agent-sdk';
-  const attempts = [
-    () => { require.resolve(pkgName); return true; },
-    () => {
-      const { createRequire } = require('module');
-      createRequire(__filename).resolve(pkgName);
-      return true;
-    },
-    () => {
-      const prefix = execSync('npm prefix -g', { encoding: 'utf8' }).trim();
-      const sdkPath = path.join(prefix, 'lib', 'node_modules', pkgName);
-      if (fs.existsSync(sdkPath)) return true;
-      throw new Error('not found');
-    },
-  ];
-  for (const attempt of attempts) {
-    try { if (attempt()) return; } catch { /* try next */ }
-  }
-  console.error(`错误：未找到 ${pkgName}`);
-  console.error(`请先安装：npm install -g ${pkgName}`);
-  process.exit(1);
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
 }
 
 function getHead() {
@@ -77,17 +57,12 @@ function killServicesByProfile() {
   } catch { /* ignore profile read errors */ }
 }
 
-function sleepSync(ms) {
-  const end = Date.now() + ms;
-  while (Date.now() < end) { /* busy wait */ }
-}
-
-function rollback(headBefore, reason) {
+async function rollback(headBefore, reason) {
   if (!headBefore || headBefore === 'none') return;
 
   killServicesByProfile();
 
-  if (process.platform === 'win32') sleepSync(1500);
+  if (process.platform === 'win32') await sleep(1500);
 
   const cwd = getProjectRoot();
   const gitEnv = { ...process.env, GIT_TERMINAL_PROMPT: '0' };
@@ -104,7 +79,7 @@ function rollback(headBefore, reason) {
     } catch (err) {
       if (attempt === 1) {
         log('warn', `回滚首次失败，等待后重试: ${err.message}`);
-        sleepSync(2000);
+        await sleep(2000);
       } else {
         log('error', `回滚失败: ${err.message}`);
       }
@@ -123,14 +98,10 @@ function rollback(headBefore, reason) {
 function markTaskFailed() {
   const data = loadTasks();
   if (!data) return;
-  const features = getFeatures(data);
-  for (const f of features) {
-    if (f.status === 'in_progress') {
-      f.status = 'failed';
-      break;
-    }
+  const result = forceStatus(data, 'failed');
+  if (result) {
+    log('warn', `已将任务 ${result.id} 强制标记为 failed`);
   }
-  saveTasks(data);
 }
 
 function tryPush() {
@@ -192,20 +163,17 @@ async function run(requirement, opts = {}) {
   console.log('============================================');
   console.log('');
 
-  // Load config
   const config = loadConfig();
   if (config.provider !== 'claude' && config.baseUrl) {
     log('ok', `模型配置已加载: ${config.provider}${config.model ? ` (${config.model})` : ''}`);
   }
 
-  // Read requirement from requirements.md or CLI
   const reqFile = path.join(projectRoot, 'requirements.md');
   if (fs.existsSync(reqFile) && !requirement) {
     requirement = fs.readFileSync(reqFile, 'utf8');
     log('ok', '已读取需求文件: requirements.md');
   }
 
-  // Ensure git repo
   try {
     execSync('git rev-parse --is-inside-work-tree', { cwd: projectRoot, stdio: 'ignore' });
   } catch {
@@ -217,7 +185,6 @@ async function run(requirement, opts = {}) {
     });
   }
 
-  // Initialization (scan) if needed
   if (!fs.existsSync(p.profile) || !fs.existsSync(p.tasksFile)) {
     if (!requirement) {
       log('error', '首次运行需要提供需求描述');
@@ -238,7 +205,7 @@ async function run(requirement, opts = {}) {
       return;
     }
 
-    await requireSdk();
+    await loadSDK();
     const scanResult = await scan(requirement, { projectRoot });
     if (!scanResult.success) {
       console.log('');
@@ -253,8 +220,7 @@ async function run(requirement, opts = {}) {
     printStats();
   }
 
-  // Coding loop
-  if (!dryRun) await requireSdk();
+  if (!dryRun) await loadSDK();
   log('info', `开始编码循环 (最多 ${maxSessions} 个会话) ...`);
   console.log('');
 
@@ -292,7 +258,6 @@ async function run(requirement, opts = {}) {
     const nextTask = findNextTask(taskData);
     const taskId = nextTask?.id || 'unknown';
 
-    // Run coding session
     const sessionResult = await runCodingSession(session, {
       projectRoot,
       taskId,
@@ -304,7 +269,7 @@ async function run(requirement, opts = {}) {
     if (sessionResult.stalled) {
       log('warn', `Session ${session} 因停顿超时中断，跳过校验直接重试`);
       consecutiveFailures++;
-      rollback(headBefore, '停顿超时');
+      await rollback(headBefore, '停顿超时');
       if (consecutiveFailures >= MAX_RETRY) {
         log('error', `连续失败 ${MAX_RETRY} 次，跳过当前任务`);
         markTaskFailed();
@@ -320,7 +285,6 @@ async function run(requirement, opts = {}) {
       continue;
     }
 
-    // Validate
     log('info', '开始 harness 校验 ...');
     const validateResult = await validate(headBefore);
 
@@ -338,7 +302,7 @@ async function run(requirement, opts = {}) {
         timestamp: new Date().toISOString(),
         result: 'success',
         cost: sessionResult.cost,
-        taskId: validateResult.sessionData?.task_id || null,
+        taskId: validateResult.sessionData?.task_id || taskId,
         statusAfter: validateResult.sessionData?.status_after || null,
         notes: validateResult.sessionData?.notes || null,
       });
@@ -347,7 +311,16 @@ async function run(requirement, opts = {}) {
       consecutiveFailures++;
       log('error', `Session ${session} 校验失败 (连续失败: ${consecutiveFailures}/${MAX_RETRY})`);
 
-      rollback(headBefore, '校验失败');
+      appendProgress({
+        session,
+        timestamp: new Date().toISOString(),
+        result: 'fatal',
+        cost: sessionResult.cost,
+        taskId,
+        reason: validateResult.sessionData?.reason || '校验失败',
+      });
+
+      await rollback(headBefore, '校验失败');
 
       if (consecutiveFailures >= MAX_RETRY) {
         log('error', `连续失败 ${MAX_RETRY} 次，跳过当前任务`);
@@ -357,7 +330,6 @@ async function run(requirement, opts = {}) {
       }
     }
 
-    // Periodic pause
     if (pauseEvery > 0 && session % pauseEvery === 0) {
       console.log('');
       printStats();
@@ -369,10 +341,8 @@ async function run(requirement, opts = {}) {
     }
   }
 
-  // Cleanup: stop services after loop ends
   killServicesByProfile();
 
-  // Final report
   console.log('');
   console.log('============================================');
   console.log('  运行结束');
@@ -382,7 +352,7 @@ async function run(requirement, opts = {}) {
 }
 
 async function add(instruction, opts = {}) {
-  await requireSdk();
+  await loadSDK();
   const p = paths();
   const projectRoot = getProjectRoot();
   ensureLoopDir();

package/src/session.js

@@ -3,8 +3,11 @@
 const fs = require('fs');
 const path = require('path');
 const { paths, loadConfig, buildEnvVars, getAllowedTools, log } = require('./config');
-const { Indicator, inferPhaseStep } = require('./indicator');
-const { buildSystemPrompt, buildCodingPrompt, buildScanPrompt, buildAddPrompt } = require('./prompts');
+const { Indicator } = require('./indicator');
+const { createSessionHooks } = require('./hooks');
+const { buildSystemPrompt, buildCodingPrompt, buildScanPrompt, buildAddSystemPrompt, buildAddPrompt } = require('./prompts');
+
+// ── SDK loader (cached, shared across sessions) ──
 
 let _sdkModule = null;
 async function loadSDK() {
@@ -38,6 +41,8 @@ async function loadSDK() {
   process.exit(1);
 }
 
+// ── Helpers ──
+
 function applyEnvConfig(config) {
   Object.assign(process.env, buildEnvVars(config));
 }
@@ -63,8 +68,9 @@ function extractResult(messages) {
   return null;
 }
 
-function stripAnsi(str) {
-  return str.replace(/\x1b\[[0-9;]*m/g, '');
+function writeSessionSeparator(logStream, sessionNum, label) {
+  const sep = '='.repeat(60);
+  logStream.write(`\n${sep}\n[Session ${sessionNum}] ${label} ${new Date().toISOString()}\n${sep}\n`);
 }
 
 function logMessage(message, logStream, indicator) {
@@ -75,17 +81,29 @@ function logMessage(message, logStream, indicator) {
           const statusLine = indicator.getStatusLine();
           process.stderr.write('\r\x1b[K');
           if (statusLine) process.stderr.write(statusLine + '\n');
-          if (logStream && statusLine) {
-            logStream.write('\n' + stripAnsi(statusLine) + '\n');
-          }
         }
         process.stdout.write(block.text);
         if (logStream) logStream.write(block.text);
       }
+      if (block.type === 'tool_use' && logStream) {
+        logStream.write(`[TOOL_USE] ${block.name}: ${JSON.stringify(block.input).slice(0, 300)}\n`);
+      }
+    }
+  }
+
+  if (message.type === 'tool_result' && logStream) {
+    const isErr = message.is_error || false;
+    const content = typeof message.content === 'string'
+      ? message.content.slice(0, 500)
+      : JSON.stringify(message.content).slice(0, 500);
+    if (isErr) {
+      logStream.write(`[TOOL_ERROR] ${content}\n`);
     }
   }
 }
 
+// ── Session runners ──
+
 async function runCodingSession(sessionNum, opts = {}) {
   const sdk = await loadSDK();
   const config = loadConfig();
@@ -101,58 +119,27 @@ async function runCodingSession(sessionNum, opts = {}) {
   const logFile = path.join(p.logsDir, `${taskId}_session_${sessionNum}_${dateStr}.log`);
   const logStream = fs.createWriteStream(logFile, { flags: 'a' });
 
-  indicator.start(sessionNum);
+  writeSessionSeparator(logStream, sessionNum, `coding task=${taskId}`);
 
-  const editCounts = {};
-  const EDIT_THRESHOLD = 5;
   const stallTimeoutMs = config.stallTimeout * 1000;
-  let stallDetected = false;
+  const { hooks, cleanup, isStalled } = createSessionHooks(indicator, logStream, {
+    enableStallDetection: true,
+    stallTimeoutMs,
+    enableEditGuard: true,
+  });
 
-  const stallChecker = setInterval(() => {
-    const idleMs = Date.now() - indicator.lastToolTime;
-    if (idleMs > stallTimeoutMs && !stallDetected) {
-      stallDetected = true;
-      log('warn', `无新工具调用超过 ${Math.floor(idleMs / 60000)} 分钟，自动中断 session`);
-    }
-  }, 30000);
+  indicator.start(sessionNum);
 
   try {
     const queryOpts = buildQueryOptions(config, opts);
     queryOpts.systemPrompt = systemPrompt;
-    queryOpts.hooks = {
-      PreToolUse: [{
-        matcher: '*',
-        hooks: [async (input) => {
-          inferPhaseStep(indicator, input.tool_name, input.tool_input);
-
-          const target = input.tool_input?.file_path || input.tool_input?.path || '';
-          const cmd = input.tool_input?.command || '';
-          const pattern = input.tool_input?.pattern || '';
-          const detail = target || cmd.slice(0, 200) || (pattern ? `pattern: ${pattern}` : '');
-          if (detail) {
-            logStream.write(`[${new Date().toISOString()}] ${input.tool_name}: ${detail}\n`);
-          }
-
-          if (['Write', 'Edit', 'MultiEdit'].includes(input.tool_name) && target) {
-            editCounts[target] = (editCounts[target] || 0) + 1;
-            if (editCounts[target] > EDIT_THRESHOLD) {
-              return {
-                decision: 'block',
-                message: `已对 ${target} 编辑 ${editCounts[target]} 次，疑似死循环。请重新审视方案后再继续。`,
-              };
-            }
-          }
-
-          return {};
-        }]
-      }]
-    };
+    queryOpts.hooks = hooks;
 
     const session = sdk.query({ prompt, options: queryOpts });
 
     const collected = [];
     for await (const message of session) {
-      if (stallDetected) {
+      if (isStalled()) {
         log('warn', '停顿超时，中断消息循环');
         break;
       }
@@ -160,20 +147,20 @@ async function runCodingSession(sessionNum, opts = {}) {
       logMessage(message, logStream, indicator);
     }
 
-    clearInterval(stallChecker);
+    cleanup();
     logStream.end();
     indicator.stop();
 
     const result = extractResult(collected);
     return {
-      exitCode: stallDetected ? 2 : 0,
+      exitCode: isStalled() ? 2 : 0,
       cost: result?.total_cost_usd ?? null,
       tokenUsage: result?.usage ?? null,
       logFile,
-      stalled: stallDetected,
+      stalled: isStalled(),
     };
   } catch (err) {
-    clearInterval(stallChecker);
+    cleanup();
     logStream.end();
     indicator.stop();
     log('error', `Claude SDK 错误: ${err.message}`);
@@ -201,40 +188,47 @@ async function runScanSession(requirement, opts = {}) {
   const logFile = path.join(p.logsDir, `scan_${new Date().toISOString().slice(0, 10).replace(/-/g, '')}.log`);
   const logStream = fs.createWriteStream(logFile, { flags: 'a' });
 
+  writeSessionSeparator(logStream, 0, `scan (${projectType})`);
+
+  const stallTimeoutMs = config.stallTimeout * 1000;
+  const { hooks, cleanup, isStalled } = createSessionHooks(indicator, logStream, {
+    enableStallDetection: true,
+    stallTimeoutMs,
+  });
+
   indicator.start(0);
   log('info', `正在调用 Claude Code 执行项目扫描（${projectType}项目）...`);
 
   try {
     const queryOpts = buildQueryOptions(config, opts);
     queryOpts.systemPrompt = systemPrompt;
-    queryOpts.hooks = {
-      PreToolUse: [{
-        matcher: '*',
-        hooks: [async (input) => {
-          inferPhaseStep(indicator, input.tool_name, input.tool_input);
-          return {};
-        }]
-      }]
-    };
+    queryOpts.hooks = hooks;
 
     const session = sdk.query({ prompt, options: queryOpts });
 
     const collected = [];
     for await (const message of session) {
+      if (isStalled()) {
+        log('warn', '扫描停顿超时，中断');
+        break;
+      }
       collected.push(message);
       logMessage(message, logStream, indicator);
     }
 
+    cleanup();
     logStream.end();
     indicator.stop();
 
     const result = extractResult(collected);
     return {
-      exitCode: 0,
+      exitCode: isStalled() ? 2 : 0,
       cost: result?.total_cost_usd ?? null,
       logFile,
+      stalled: isStalled(),
     };
   } catch (err) {
+    cleanup();
     logStream.end();
     indicator.stop();
     log('error', `扫描失败: ${err.message}`);
@@ -248,39 +242,45 @@ async function runAddSession(instruction, opts = {}) {
   applyEnvConfig(config);
   const indicator = new Indicator();
 
-  const systemPrompt = buildSystemPrompt(false);
+  const systemPrompt = buildAddSystemPrompt();
   const prompt = buildAddPrompt(instruction);
 
   const p = paths();
   const logFile = path.join(p.logsDir, `add_tasks_${new Date().toISOString().slice(0, 10).replace(/-/g, '')}.log`);
   const logStream = fs.createWriteStream(logFile, { flags: 'a' });
 
+  writeSessionSeparator(logStream, 0, 'add tasks');
+
+  const stallTimeoutMs = config.stallTimeout * 1000;
+  const { hooks, cleanup, isStalled } = createSessionHooks(indicator, logStream, {
+    enableStallDetection: true,
+    stallTimeoutMs,
+  });
+
   indicator.start(0);
   log('info', '正在追加任务...');
 
   try {
     const queryOpts = buildQueryOptions(config, opts);
     queryOpts.systemPrompt = systemPrompt;
-    queryOpts.hooks = {
-      PreToolUse: [{
-        matcher: '*',
-        hooks: [async (input) => {
-          inferPhaseStep(indicator, input.tool_name, input.tool_input);
-          return {};
-        }]
-      }]
-    };
+    queryOpts.hooks = hooks;
 
     const session = sdk.query({ prompt, options: queryOpts });
 
     for await (const message of session) {
+      if (isStalled()) {
+        log('warn', '追加任务停顿超时，中断');
+        break;
+      }
       logMessage(message, logStream, indicator);
     }
 
+    cleanup();
     logStream.end();
     indicator.stop();
     log('ok', '任务追加完成');
   } catch (err) {
+    cleanup();
     logStream.end();
     indicator.stop();
     log('error', `任务追加失败: ${err.message}`);
@@ -304,6 +304,7 @@ function hasCodeFiles(projectRoot) {
 }
 
 module.exports = {
+  loadSDK,
   runCodingSession,
   runScanSession,
   runAddSession,

package/src/tasks.js

@@ -67,6 +67,22 @@ function setStatus(data, taskId, newStatus) {
   return task;
 }
 
+/**
+ * Harness-level forced status change (bypasses TRANSITIONS validation).
+ * Used when harness needs to mark tasks failed after max retries.
+ */
+function forceStatus(data, status) {
+  const features = getFeatures(data);
+  for (const f of features) {
+    if (f.status === 'in_progress') {
+      f.status = status;
+      saveTasks(data);
+      return f;
+    }
+  }
+  return null;
+}
+
 function addTask(data, task) {
   if (!data) {
     data = { project: '', created_at: new Date().toISOString().slice(0, 10), features: [] };
@@ -145,6 +161,7 @@ module.exports = {
   getFeatures,
   findNextTask,
   setStatus,
+  forceStatus,
   addTask,
   getStats,
   showStatus,

package/templates/CLAUDE.md

@@ -177,8 +177,8 @@ pending ──→ in_progress ──→ testing ──→ done
 ### 第一步：恢复上下文
 
 1. **检查 prompt 注入的上下文**：
-   - 如果 prompt 中包含"任务上下文"（Hint 7），说明 harness 已注入当前任务信息，**跳过读取 tasks.json**，直接确认任务后进入第二步
-   - 如果 prompt 中包含"上次会话"（Hint 8），说明 harness 已注入上次会话摘要，**跳过读取 session_result.json 历史**
+   - 如果 prompt 中包含"任务上下文"（Hint 6），说明 harness 已注入当前任务信息，**跳过读取 tasks.json**，直接确认任务后进入第二步
+   - 如果 prompt 中包含"上次会话"（Hint 7），说明 harness 已注入上次会话摘要，**跳过读取 session_result.json 历史**
 2. 批量读取以下文件（一次工具调用，跳过已注入的）：`.claude-coder/project_profile.json`、`.claude-coder/tasks.json`（仅当无 Hint 6 时）
 3. 如果无 Hint 7 且 `session_result.json` 不存在，运行 `git log --oneline -20` 补充上下文
 4. 如果项目根目录存在 `requirements.md`，读取用户的详细需求和偏好（技术约束、样式要求等），作为本次会话的参考依据