[Enhancement] Loop Gate 改进：参考轨迹动作分析框架减少误报

[Spongeacer]

背景

当前 Loop Gate 机制在检测到重复工具调用时会阻止执行，但存在以下问题：

1. 误报率高：只读操作（如 git status, grep）和验证行为（Edit→Bash）被误判为死循环
2. 用户消息不清晰：缺少工具名称、重复次数、重复类型等上下文
3. 缺乏工具分类：所有工具同等对待，没有区分只读/修改/验证操作

参考资源

参考 backtrack_analyzer.py（Anti-Claude poisoning detection project）中的轨迹动作分析框架：

• 工具分类体系（TOOL_NAME_MAP）：规范化工具名，区分只读/修改/验证工具
• 只读命令白名单（READONLY_BASH_PREFIXES）：git status, ls, grep 等命令的重复执行属于验证行为
• 危险操作标记（DANGER_MARKERS）：rm, mv, git push 等命令需要严格限制
• 动作签名机制（_build_action_signature）：包含 offset/limit/命令摘要，区分有意义的参数差异
• 验证行为识别（_compute_verification_behavior）：Edit→Bash, Edit→Read(同一文件) 是健康的验证驱动开发模式

改进方案

1. 工具分类和白名单

export type ToolCategory = "readonly" | "modify" | "verify" | "internal"

export const TOOL_CLASSIFICATION: Record<string, ToolCategory> = {
  // 只读工具
  "read": "readonly",
  "grep": "readonly",
  "glob": "readonly",
  "webfetch": "readonly",
  
  // 修改工具
  "edit": "modify",
  "write": "modify",
  
  // 需要根据命令内容判断
  "bash": "verify",  // 默认为验证，需要进一步判断
}

// 只读 Bash 命令白名单
export const READONLY_BASH_PREFIXES: string[] = [
  "git status", "git log", "git diff", "git show",
  "ls", "ll", "find ", "cat ", "head ", "tail ", "grep ",
  "which ", "file ", "stat ", "id", "uname", "whoami",
  "npm list", "yarn list", "npm view",
]

// 危险 Bash 子串
export const DANGER_MARKERS: string[] = [
  "rm ", "mv ", "cp ", "> ", ">> ", "| tee", "chmod ", "chown ",
  "git checkout", "git reset", "git restore", "git clean",
  "git commit", "git push", "git pull",
]

2. 改进的动作签名

export function buildActionSignature(tool: string, args: Record<string, unknown>): string {
  switch (tool) {
    case "read": {
      const filePath = extractFilePath(args)
      const offset = args.offset ?? ""
      const limit = args.limit ?? ""
      const extra = offset || limit ? `[o=${offset},l=${limit}]` : ""
      return `Read:${filePath}${extra}`
    }
    case "bash": {
      const command = (args.command as string) ?? ""
      return `Bash:${getBashSignature(command)}`
    }
    // ...
  }
}

3. 验证行为识别

export type VerificationType = 
  | "edit_then_bash"           // Edit → Bash（编辑后验证）
  | "edit_then_read_same"      // Edit → Read(同一文件)（编辑后确认）
  | "none"

export function detectVerification(ctx: VerificationContext): VerificationType {
  // Edit→Bash 和 Edit→Read(同一文件) 是验证行为，应该被容忍
}

4. 改进的用户消息

# 当前消息（无上下文）
"我刚才在重复检查同一处，已停止重复。"

# 改进后（包含工具名、次数、类型）
"我刚才重复查询 git status 4 次（相同输入），已停止重复。"
"我刚才在验证 edit 的修改结果，已停止重复验证。"
"我刚才重复修改 edit 3 次（相同操作），已停止重复。"

预期效果

指标	当前	改进后
只读操作误报	高	降低 50%+
验证行为误报	高	降低 80%+
用户消息清晰度	低	高（包含工具名、次数、类型）
诊断信息	基础	详细（工具分类、验证类型、签名）

实现计划

Phase	内容	工作量
1	工具分类和白名单	1-2 天
2	改进动作签名	1 天
3	验证行为识别	1 天
4	改进门控决策	2 天
5	改进用户消息	1 天
6	测试和验证	2 天
总计		8-9 天

相关文件

• packages/opencode/src/session/diagnostics.ts
• packages/opencode/src/session/loop-renderer.ts
• packages/opencode/src/session/prompt.ts

参考资源

• 完整方案文档：docs/loop-gate-improvement-proposal.md

[Astro-Han]

Closing #726 as superseded by design direction change.

The core problem this issue aimed to solve — false-positive loop gate hits during healthy TDD/verify cycles — was resolved more decisively by PR #770 (merged 2026-05-19), which removed the success-side hard gate entirely rather than refining its classification logic.

Specific status against the proposal's four areas:

1. Tool classification / whitelisting — Moot: the success-side gate no longer exists.
2. Improved action signatures — Partially addressed by fix(session): relax successful same-target loop gate #416/feat(session): gate repeated successful tool calls #406 (output hashes, mutation epochs).
3. Verification behavior detection (Edit→Bash) — Root problem solved by removing the gate.
4. Improved user messages — Addressed by [Bug] Loop gate success-repeat message lacks tool context and may mislead users #725 (closed as completed by fix(session): drop success-side hard gate to stop false-positive loops #770): the success-stop message is no longer emitted on live paths.

The failure-side gate remains and continues to handle genuine death loops. Remaining proposal items that targeted the success path have significantly less value after the gate removal.