feat: 实现渐进式工具披露、自动验证传感器和内置验证Agent

- 新增 ToolSearch 工具支持按需加载 deferred 工具 schema
- 新增 AutoVerifyStage 在 Edit/Write 后自动运行类型检查并注入错误
- 新增内置验证 Subagent 用于独立代码质量评估
- 新增 PromptHook 支持 LLM 推理型传感器（如代码审查）
- 新增 ConfigTool 和 update-config skill 用于配置管理
- 实现 Ralph Loop 机制在 Spec 未完成时自动继续执行
- 改进上下文压缩后自动恢复最近访问的文件内容
- 增强工具结果预算管理，支持消息级聚合限制

Author: echoVic

.gitignore

@@ -85,3 +85,4 @@ packages/vscode/*.vsix
 # Web 构建缓存
 packages/web/.vite/
 packages/cli/web/.vite/
+.gstack/

packages/cli/src/agent/loop/completionPolicy.ts

@@ -5,6 +5,7 @@
  * 1. checkOutputRecovery — finishReason === 'length' 时的恢复/截断判断
  * 2. checkIncompleteIntent — 检测 LLM "说了要做但没做"的模式
  * 3. checkStopHook — 执行 stop hook 并加超时保护
+ * 4. checkRalphLoop — Spec 未完成任务时自动继续（Ralph Loop 模式）
  *
  * 所有函数返回 action descriptors，不执行副作用。
  */
@@ -181,3 +182,85 @@ export async function checkStopHook(context: {
     return { action: 'stop' };
   }
 }
+
+// ===== Ralph Loop (Spec-Aware Auto-Continue) =====
+
+/** Ralph Loop 安全阈值：当轮次超过最大轮次的 90% 时停止，防止无限循环 */
+const RALPH_LOOP_SAFETY_RATIO = 0.9;
+
+export type RalphLoopAction =
+  | { action: 'continue'; reason: string }
+  | { action: 'none' };
+
+/**
+ * Ralph Loop：当 Spec 处于 implementation 阶段且有未完成任务时，
+ * 自动继续执行而不停止。
+ *
+ * 触发条件（全部满足）：
+ * 1. Spec 模式活跃且处于 implementation 阶段
+ * 2. 存在未完成任务
+ * 3. 轮次未超出安全阈值（防止无限循环）
+ */
+export async function checkRalphLoop(context: {
+  turnsCount: number;
+  maxTurns: number;
+}): Promise<RalphLoopAction> {
+  try {
+    // 延迟导入避免循环依赖
+    const { SpecManager } = await import('../../spec/SpecManager.js');
+    const specManager = SpecManager.getInstance();
+
+    if (!specManager.isActive()) {
+      return { action: 'none' };
+    }
+
+    const spec = specManager.getCurrentSpec();
+    if (!spec || spec.phase !== 'implementation') {
+      return { action: 'none' };
+    }
+
+    // 安全阈值检查
+    if (
+      context.maxTurns > 0 &&
+      context.turnsCount >= context.maxTurns * RALPH_LOOP_SAFETY_RATIO
+    ) {
+      logger.info(
+        `[RalphLoop] 轮次接近上限 (${context.turnsCount}/${context.maxTurns})，停止自动继续`,
+      );
+      return { action: 'none' };
+    }
+
+    const tasks = spec.tasks ?? [];
+    const completed = tasks.filter(
+      (t: { status: string }) =>
+        t.status === 'completed' || t.status === 'skipped',
+    ).length;
+    const total = tasks.length;
+
+    if (completed >= total) {
+      return { action: 'none' };
+    }
+
+    // 找到下一个待执行任务
+    const nextTask = tasks.find(
+      (t: { status: string }) =>
+        t.status === 'pending' || t.status === 'in_progress',
+    );
+
+    const reason =
+      `[Ralph Loop] Spec "${spec.name}" 仍有未完成任务。\n` +
+      `进度: ${completed}/${total} 任务已完成。\n` +
+      (nextTask
+        ? `下一个任务: ${nextTask.title}${nextTask.description ? ` — ${nextTask.description}` : ''}\n`
+        : '') +
+      '请继续执行下一个未完成的任务，不要停止。';
+
+    logger.info(
+      `[RalphLoop] Spec "${spec.name}" 进度 ${completed}/${total}，自动继续`,
+    );
+    return { action: 'continue', reason };
+  } catch {
+    // SpecManager 不可用时（如未初始化），静默跳过
+    return { action: 'none' };
+  }
+}

packages/cli/src/agent/loop/executeLoopGenerator.ts

@@ -12,7 +12,10 @@ import { CompactionService } from '../../context/CompactionService.js';
 import { ReactiveCompaction } from '../../context/ReactiveCompaction.js';
 import { snipCompact } from '../../context/SnipCompaction.js';
 import { createBudgetTracker, recordOutput } from '../../context/TokenBudget.js';
-import { applyToolResultBudget } from '../../context/ToolResultBudget.js';
+import {
+  applyToolResultBudget,
+  MessageBudgetTracker,
+} from '../../context/ToolResultBudget.js';
 import { createLogger, LogCategory } from '../../logging/Logger.js';
 import type {
   ChatResponse,
@@ -34,6 +37,7 @@ import {
   checkOutputRecovery,
   checkIncompleteIntent,
   checkStopHook,
+  checkRalphLoop,
 } from './completionPolicy.js';
 import {
   saveUserMessage,
@@ -415,8 +419,20 @@ export async function* executeLoopGenerator(
     rawTools = injectSkillsMetadata(rawTools);
     const tools = deps.applySkillToolRestrictions(rawTools);
 
+    // 1.5 注入 deferred tools listing 到系统提示
+    let finalSystemPrompt = systemPrompt;
+    if (
+      typeof registry.getDeferredToolsListing === 'function'
+    ) {
+      const deferredListing = registry.getDeferredToolsListing();
+      if (deferredListing && finalSystemPrompt) {
+        finalSystemPrompt =
+          `${finalSystemPrompt}\n\n${deferredListing}`;
+      }
+    }
+
     // 2. 构建消息历史 — 使用 ConversationState 单一消息源
-    const state = new ConversationState(context, systemPrompt);
+    const state = new ConversationState(context, finalSystemPrompt);
     state.appendUser({ role: 'user', content: message });
 
     // 保存用户消息到 JSONL
@@ -511,6 +527,9 @@ export async function* executeLoopGenerator(
               signal: options?.signal,
               confirmationHandler: context.confirmationHandler,
               permissionMode: context.permissionMode,
+              toolRegistry: registry,
+              deferredToolManager:
+                registry.deferredToolManager,
             },
             deps.executionPipeline.getRegistry(),
             deps.executionEngine?.getContextManager(),
@@ -715,6 +734,37 @@ export async function* executeLoopGenerator(
         // 正常完成时归零 incompleteIntentRetryCount
         incompleteIntentRetryCount = 0;
 
+        // Ralph Loop: Spec 未完成任务时自动继续
+        const ralphAction = await checkRalphLoop({
+          turnsCount,
+          maxTurns,
+        });
+        if (ralphAction.action === 'continue') {
+          state.appendAssistant({
+            role: 'assistant',
+            content: turnResult.content || '',
+            reasoningContent: turnResult.reasoningContent,
+          });
+
+          const ralphAssistantUuid = await saveAssistantMessage(
+            deps, context, turnResult.content || '', lastMessageUuid,
+          );
+          if (ralphAssistantUuid) lastMessageUuid = ralphAssistantUuid;
+
+          const ralphMsg: Message = {
+            role: 'user',
+            content: `\n\n<system-reminder>\n${ralphAction.reason}\n</system-reminder>`,
+          };
+          state.appendControl('user', ralphMsg);
+
+          const ralphUserUuid = await saveUserMessage(
+            deps, context, ralphMsg.content as string, lastMessageUuid,
+          );
+          if (ralphUserUuid) lastMessageUuid = ralphUserUuid;
+
+          continue;
+        }
+
         // Stop Hook (via completionPolicy, with timeout)
         const stopAction = await checkStopHook({
           sessionId: context.sessionId,
@@ -874,6 +924,9 @@ export async function* executeLoopGenerator(
                 signal: options?.signal,
                 confirmationHandler: context.confirmationHandler,
                 permissionMode: context.permissionMode,
+                toolRegistry: registry,
+                deferredToolManager:
+                  registry.deferredToolManager,
               }
             );
             return { toolCall, result, toolUseUuid };
@@ -906,6 +959,7 @@ export async function* executeLoopGenerator(
       }
 
       // 8. 处理执行结果
+      const messageBudget = new MessageBudgetTracker();
       for (const { toolCall: rawToolCall, result, toolUseUuid } of executionResults) {
         // 安全断言：所有 toolCall 都是 function 类型
         const toolCall = rawToolCall as {
@@ -991,11 +1045,12 @@ export async function* executeLoopGenerator(
           toolResultContent = JSON.stringify(toolResultContent, null, 2);
         }
 
-        // Apply tool result budget — truncate oversized results
-        if (typeof toolResultContent === 'string' && toolResultContent.length > 100_000) {
+        // Apply tool result budget — per-tool + per-message 截断
+        if (typeof toolResultContent === 'string') {
           toolResultContent = applyToolResultBudget(
             toolResultContent,
-            toolCall.function.name
+            toolCall.function.name,
+            { messageBudget },
           ) as string;
         }
 

packages/cli/src/agent/subagents/builtinAgents.ts

@@ -6,6 +6,7 @@
  */
 
 import type { SubagentConfig } from './types.js';
+import { verificationAgentConfig } from './builtinVerificationAgent.js';
 
 /**
  * 内置 Subagent 列表（4 个核心 agent）
@@ -105,6 +106,7 @@ Be thorough but concise. Focus on actionable steps.`,
       "Use this agent to configure the user's Claude Code status line setting.",
     tools: ['Read', 'Edit'],
   },
+  verificationAgentConfig,
 ];
 
 

packages/cli/src/agent/subagents/builtinVerificationAgent.ts

@@ -0,0 +1,145 @@
+/**
+ * 内置验证 Subagent 配置
+ *
+ * 独立验证 Agent，用于在实现完成后进行质量评估。
+ * 严格只读 — 不能修改代码，只能运行构建、测试、lint 和对抗性检查。
+ */
+
+import type { SubagentConfig } from './types.js';
+
+/**
+ * 验证 Agent 系统提示
+ */
+const VERIFICATION_SYSTEM_PROMPT = `# Verification Agent
+
+You are an **independent verification engineer**. Your sole purpose \
+is to find problems — not to praise or reassure. You are the last \
+line of defense before code ships.
+
+## Constraints
+
+1. **READ-ONLY**: You have NO write tools (no Edit, Write, or \
+NotebookEdit). You cannot modify files. If you discover issues, \
+report them — do not attempt to fix them.
+2. **NO SUB-AGENTS**: You must not delegate to other agents or use \
+the Task tool. Execute all verification steps yourself using your \
+tools directly.
+3. **TOOL-BASED EVIDENCE ONLY**: Every claim must be backed by \
+actual tool output. Never say "looks correct" or "should work" — \
+run the command and prove it.
+4. **NO ASSUMPTIONS**: Do not assume tests pass. Do not assume types \
+are correct. Run the checks.
+
+## Verification Workflow
+
+Execute these phases in order. Do NOT skip any phase.
+
+### Phase 1: Project Setup Detection
+
+1. Use Glob to find project config files: \`package.json\`, \
+\`tsconfig.json\`, \`biome.json\`, \`.eslintrc.*\`, \
+\`vitest.config.*\`, \`jest.config.*\`, \`Makefile\`, \
+\`Cargo.toml\`, \`go.mod\`, etc.
+2. Use Read to examine them and determine:
+   - Package manager (bun/npm/pnpm/yarn)
+   - Available scripts (test, lint, type-check, build)
+   - Project language and framework
+3. Identify which checks are available for this project.
+
+### Phase 2: Automated Checks
+
+Run all applicable checks. Capture full output.
+
+| Check | Typical Command | Priority |
+|-------|----------------|----------|
+| **Type checking** | \`bun run type-check\` or \`npx tsc --noEmit\` | HIGH |
+| **Tests** | \`bun run test:all\` or \`npm test\` | HIGH |
+| **Linting** | \`bun run lint\` or \`npx biome check\` | HIGH |
+| **Build** | \`bun run build\` | MEDIUM |
+
+- If a command fails, record the exact error output.
+- If a command succeeds, record confirmation.
+- Set reasonable timeouts (use Bash timeout parameter).
+
+### Phase 3: Code Review of Changed Files
+
+1. Run \`git diff --name-only HEAD~1\` (or appropriate range) to \
+identify changed files.
+2. Read each changed file and review for:
+   - **Logic errors**: off-by-one, null/undefined handling, race \
+conditions
+   - **Type safety**: any casts, type assertions, missing null checks
+   - **Error handling**: uncaught exceptions, missing error paths
+   - **Edge cases**: empty arrays, empty strings, boundary values
+   - **Security**: injection risks, credential exposure, unsafe eval
+   - **Code style**: naming conventions, dead code, commented-out code
+
+### Phase 4: Adversarial Analysis
+
+Think like an attacker or a hostile user:
+
+1. **Input validation**: Are all inputs validated? What happens with \
+malformed data?
+2. **Boundary conditions**: What happens at limits? (max length, \
+zero, negative)
+3. **Concurrency**: Are there race conditions or shared mutable \
+state issues?
+4. **Dependency risks**: Are new dependencies trustworthy? Pinned \
+versions?
+5. **Regression potential**: Could these changes break existing \
+functionality?
+
+## Output Format
+
+You MUST end your response with a structured verification report:
+
+\`\`\`
+## Verification Result: PASS | FAIL | PARTIAL
+
+### Automated Checks
+- [ ] Type check: PASS/FAIL — [details]
+- [ ] Tests: PASS/FAIL — [details, including test count]
+- [ ] Lint: PASS/FAIL — [details]
+- [ ] Build: PASS/FAIL — [details]
+
+### Code Review Findings
+- [Issue severity: HIGH/MEDIUM/LOW] [file:line] Description
+  Evidence: [exact code or output]
+
+### Adversarial Analysis
+- [Risk level: HIGH/MEDIUM/LOW] Description
+  Impact: [what could go wrong]
+
+### Summary
+[1-3 sentence overall assessment with specific evidence]
+\`\`\`
+
+### Verdict Rules
+
+- **PASS**: All automated checks pass AND no HIGH severity issues \
+found.
+- **FAIL**: Any automated check fails OR any HIGH severity issue \
+found.
+- **PARTIAL**: All automated checks pass BUT MEDIUM severity issues \
+exist.
+
+Be thorough. Be skeptical. Find the bugs.`;
+
+/**
+ * 验证 Agent 配置
+ *
+ * 独立验证 Agent，在实现完成后运行构建、测试、lint 和对抗性分析。
+ * 严格只读 — 明确排除 Edit/Write/NotebookEdit/Task 等写入工具。
+ */
+export const verificationAgentConfig: SubagentConfig = {
+  name: 'verification',
+  description:
+    'Independent verification agent that validates implementation'
+    + ' by running builds, tests, linters, and adversarial'
+    + ' probes. Strictly read-only — cannot modify code. Use'
+    + ' after completing implementation to get an independent'
+    + ' quality assessment.',
+  tools: ['Read', 'Glob', 'Grep', 'Bash'],
+  systemPrompt: VERIFICATION_SYSTEM_PROMPT,
+  source: 'builtin',
+};