┌─────────────────────────────────────────────────┐
│                                                 │
│   Agent = Model (LLM)                          │
│   Harness = Everything Else                     │
│                                                 │
│   ┌──────────┐     ┌────────────────────────┐  │
│   │  Claude   │ ←── │  Tools, Permissions,   │  │
│   │  Opus/    │ ──→ │  Hooks, Sandbox,       │  │
│   │  Sonnet   │     │  Memory, Settings,     │  │
│   │          │     │  MCP, Skills, Agents   │  │
│   └──────────┘     └────────────────────────┘  │
│      Model              Harness                 │
│                                                 │
└─────────────────────────────────────────────────┘

src/
├── main.tsx                    # 入口点，CLI 引导（803 KB）
├── query.ts                    # 核心 Agent 循环（68 KB）
├── QueryEngine.ts              # LLM 查询引擎（46 KB）
├── Tool.ts                     # Tool 基础接口（29 KB）
├── tools.ts                    # Tool 注册表（25 KB）
├── Task.ts                     # 任务类型定义
├── commands.ts                 # 命令注册
│
├── tools/                      # 43 个工具目录
│   ├── BashTool/              # Shell 命令执行
│   ├── FileReadTool/          # 文件读取
│   ├── FileWriteTool/         # 文件创建
│   ├── FileEditTool/          # 部分文件修改
│   ├── GlobTool/              # 文件模式匹配
│   ├── GrepTool/              # ripgrep 内容搜索
│   ├── AgentTool/             # 子 Agent 生成
│   ├── SkillTool/             # Skill 执行
│   ├── MCPTool/               # MCP 服务器调用
│   ├── WebFetchTool/          # URL 内容抓取
│   ├── WebSearchTool/         # 网页搜索
│   └── https://wanlanglin.github.io/-awesome-cc-harness/.                    # 更多工具
│
├── commands/                   # ~101 个命令目录
│   ├── commit/                # Git 提交
│   ├── review/                # 代码审查
│   ├── mcp/                   # MCP 管理
│   ├── skills/                # Skill 管理
│   └── https://wanlanglin.github.io/-awesome-cc-harness/.
│
├── components/                 # 144+ React/Ink 终端组件
├── hooks/                      # 80+ 自定义 React Hooks
├── services/                   # 22 个服务子目录
│   ├── api/                   # Anthropic API 客户端
│   ├── mcp/                   # MCP 协议连接
│   ├── oauth/                 # OAuth 认证
│   ├── lsp/                   # 语言服务器协议
│   ├── compact/               # 对话压缩
│   ├── plugins/               # 插件加载
│   └── https://wanlanglin.github.io/-awesome-cc-harness/.
│
├── utils/                      # 33+ 子目录，100+ 文件
│   ├── permissions/           # 权限逻辑
│   ├── hooks.ts               # Hook 执行引擎
│   ├── hooks/                 # Hook 配置管理
│   ├── sandbox/               # 沙盒适配器
│   ├── settings/              # 设置管理
│   ├── bash/                  # Shell 工具
│   ├── memdir/                # 持久记忆目录
│   └── https://wanlanglin.github.io/-awesome-cc-harness/.
│
├── state/                      # 应用状态管理
├── entrypoints/                # CLI/MCP/SDK 入口
├── bridge/                     # IDE 双向通信
├── coordinator/                # 多 Agent 编排
├── skills/                     # Skill 系统
├── plugins/                    # 插件系统
├── memdir/                     # 记忆目录系统
├── schemas/                    # Zod 验证 Schema
├── types/                      # 类型定义
└── constants/                  # 应用常量

main.tsx → 并行预取（MDM设置 + Keychain + API预连接）
    ↓
Commander.js CLI 解析器初始化
    ↓
preAction Hook: init() → 遥测 → 插件 → 迁移 → 远程设置
    ↓
React/Ink 渲染器启动
    ↓
交互式 REPL/对话循环

┌─────────────────────────────────────────────────────────────────────┐
│                    Claude Code 数据流全景                             │
│                                                                      │
│  用户输入 ──→ UserPromptSubmit Hook ──→ Slash Command 解析           │
│     │                                                                │
│     v                                                                │
│  QueryEngine.submitMessage()                                         │
│     │                                                                │
│     ├─→ 系统提示构建: base + tools + CLAUDE.md + MCP + memory       │
│     ├─→ 消息规范化: normalizeMessagesForAPI()                        │
│     │   ├─ 重排序 attachment 消息                                    │
│     │   ├─ 合并连续 user/assistant 消息                              │
│     │   ├─ 剥离 PDF/图片错误的重复内容                                │
│     │   ├─ 规范化工具名称（别名→正式名）                              │
│     │   └─ 工具搜索引用块处理                                        │
│     │                                                                │
│     v                                                                │
│  queryLoop() [while(true)]                                           │
│     │                                                                │
│     ├─→ 压缩管道: snip → micro → collapse → auto                    │
│     ├─→ API 调用: deps.sample() [流式]                               │
│     │                                                                │
│     ├─→ 工具执行: StreamingToolExecutor (并发) / runTools (顺序)     │
│     │   │                                                            │
│     │   ├─→ 工具分区: partitionToolCalls()                           │
│     │   │   ├─ isConcurrencySafe=true → 并发执行                     │
│     │   │   └─ isConcurrencySafe=false → 串行执行                    │
│     │   │                                                            │
│     │   └─→ 每个工具:                                                │
│     │       ├─ Zod schema 验证                                       │
│     │       ├─ tool.validateInput()                                  │
│     │       ├─ PreToolUse Hook                                       │
│     │       ├─ 权限检查 (rules → mode → classifier)                 │
│     │       ├─ Sandbox 包装 (BashTool)                               │
│     │       ├─ tool.call() [实际执行]                                │
│     │       └─ PostToolUse Hook                                      │
│     │                                                                │
│     ├─→ 错误恢复: 7 个 continue 站点                                │
│     └─→ Stop Hook → 终止或继续                                      │
│                                                                      │
│  终止 → SessionEnd Hook → 转录保存 → 退出                           │
└─────────────────────────────────────────────────────────────────────┘

// src/types/message.ts — 消息类型层次
type Message =
  | UserMessage           // 人类输入（或工具结果）
  | AssistantMessage      // 模型响应（文本 + 工具调用）
  | AttachmentMessage     // 记忆/资源附件
  | SystemMessage         // 系统消息
  | SystemLocalCommandMessage  // 本地工具结果（bash, read 等）
  | ToolUseSummaryMessage // 压缩后的工具历史
  | TombstoneMessage      // 已删除消息标记
  | ProgressMessage       // 流式进度更新

// src/query.ts — 真实的函数签名
async function* queryLoop(
  params: QueryParams,
  consumedCommandUuids: string[],
): AsyncGenerator<
  | StreamEvent
  | RequestStartEvent
  | Message
  | TombstoneMessage
  | ToolUseSummaryMessage,
  Terminal
> {
  // ===== 不可变参数 — 循环期间永不重新赋值 =====
  const {
    systemPrompt, userContext, systemContext,
    canUseTool, fallbackModel, querySource,
    maxTurns, skipCacheWrite,
  } = params
  const deps = params.deps ?? productionDeps()

  // ===== 可变跨迭代状态 =====
  // 循环体在每次迭代开始时解构此对象以保持裸名读取。
  // Continue 站点写入 `state = { https://wanlanglin.github.io/-awesome-cc-harness/. }` 而不是 9 个独立赋值。
  let state: State = {
    messages: params.messages,
    toolUseContext: params.toolUseContext,
    maxOutputTokensOverride: params.maxOutputTokensOverride,
    autoCompactTracking: undefined,
    stopHookActive: undefined,
    maxOutputTokensRecoveryCount: 0,
    hasAttemptedReactiveCompact: false,
    turnCount: 1,
    pendingToolUseSummary: undefined,
    transition: undefined,  // 为什么上次迭代 continue 了
  }

  // 预算跟踪跨压缩边界（循环局部，不在 State 上）
  let taskBudgetRemaining: number | undefined = undefined

  // 查询配置快照（一次性捕获环境/statsig/会话状态）
  const config = buildQueryConfig()

  // 记忆预取（使用 `using` 确保在生成器退出时清理）
  using pendingMemoryPrefetch = startRelevantMemoryPrefetch(
    state.messages, state.toolUseContext,
  )

  while (true) {
    // https://wanlanglin.github.io/-awesome-cc-harness/. 循环体（下文详解）
  }
}

type State = {
  messages: Message[]
  toolUseContext: ToolUseContext
  autoCompactTracking: AutoCompactTrackingState | undefined
  maxOutputTokensRecoveryCount: number
  hasAttemptedReactiveCompact: boolean
  maxOutputTokensOverride: number | undefined
  pendingToolUseSummary: Promise<ToolUseSummaryMessage | null> | undefined
  stopHookActive: boolean | undefined
  turnCount: number
  transition: Continue | undefined  // 上次迭代为何 continue
}

while (true) {
    // 1. 解构状态
    const { messages, toolUseContext, https://wanlanglin.github.io/-awesome-cc-harness/. } = state;

    // 2. 压缩管道
    // 3. 构建系统提示 + 规范化消息
    // 4. 调用 LLM API（流式）
    // 5. 收集 tool_use 块
    // 6. 错误恢复（7 个 continue 站点）
    // 7. 工具执行
    // 8. Stop Hook → 终止或继续
    // 9. 更新状态 → continue
}

┌─────────────────────────────────────────────────┐
│                 queryLoop()                      │
│                                                  │
│  ┌──────────────────────────────────────────┐   │
│  │ Continue Site 1: Proactive Compaction     │   │
│  │ 触发: token 超过阈值                      │   │
│  │ 动作: autocompact → 新消息 → continue     │   │
│  └──────────────────────────────────────────┘   │
│                                                  │
│  ┌──────────────────────────────────────────┐   │
│  │ Continue Site 2: Prompt Too Long          │   │
│  │ 触发: API 返回 prompt-too-long 错误       │   │
│  │ 动作: context-collapse → reactive compact │   │
│  └──────────────────────────────────────────┘   │
│                                                  │
│  ┌──────────────────────────────────────────┐   │
│  │ Continue Site 3: Max Output Tokens        │   │
│  │ 触发: 模型输出截断                        │   │
│  │ 动作: 升级 8k→64k → 多轮重试（最多3次）   │   │
│  └──────────────────────────────────────────┘   │
│                                                  │
│  ┌──────────────────────────────────────────┐   │
│  │ Continue Site 4: Fallback Model           │   │
│  │ 触发: FallbackTriggeredError             │   │
│  │ 动作: 切换模型 → 重试请求                 │   │
│  └──────────────────────────────────────────┘   │
│                                                  │
│  ┌──────────────────────────────────────────┐   │
│  │ Continue Site 5: Stop Hook Blocking       │   │
│  │ 触发: 用户 Hook 要求额外轮次              │   │
│  │ 动作: 注入 Hook 消息 → continue           │   │
│  └──────────────────────────────────────────┘   │
│                                                  │
│  ┌──────────────────────────────────────────┐   │
│  │ Continue Site 6: Image/Media Errors       │   │
│  │ 触发: ImageSizeError / ImageResizeError   │   │
│  │ 动作: 反应式压缩（移除图片）→ continue    │   │
│  └──────────────────────────────────────────┘   │
│                                                  │
│  ┌──────────────────────────────────────────┐   │
│  │ Continue Site 7: Tool Execution           │   │
│  │ 触发: 正常工具执行完成                    │   │
│  │ 动作: 收集结果 → 更新状态 → continue      │   │
│  └──────────────────────────────────────────┘   │
│                                                  │
│  ┌──────────────────────────────────────────┐   │
│  │ return Terminal — 唯一的退出点             │   │
│  │ 条件: 无工具调用 + Stop Hook 不阻止        │   │
│  └──────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────┐
│                  Compaction Pipeline                     │
│                                                         │
│  Level 1: Snip Compact（每轮）                          │
│  ├─ Feature-gated 历史截断                              │
│  ├─ 追踪释放的 token 数                                  │
│  └─ 最轻量，几乎无延迟                                   │
│                                                         │
│  Level 2: Microcompact（每轮）                           │
│  ├─ 将 3 轮前的工具结果替换为 "[Previous: used {tool}]"  │
│  ├─ 缓存压缩结果                                        │
│  └─ 延迟边界消息直到 API 响应（知道 cache_deleted_input） │
│                                                         │
│  Level 3: Context-Collapse（读时投射）                   │
│  ├─ 不修改消息数组，而是在读取时投射                      │
│  ├─ 按粒度排空可折叠上下文                               │
│  └─ 低成本，渐进式                                      │
│                                                         │
│  Level 4: Autocompact（>50k tokens 时触发）              │
│  ├─ 保存完整转录到磁盘                                   │
│  ├─ LLM 总结所有消息                                     │
│  ├─ 用摘要替换所有消息                                   │
│  └─ 最重量级，但释放最多空间                              │
│                                                         │
│  执行顺序: snip → micro → context-collapse → auto        │
│  各级互不排斥，可组合运行                                 │
└────────────────────────────────────────────────────────┘

// src/services/tools/toolOrchestration.ts — 真实代码
export class StreamingToolExecutor {
  private tools: TrackedTool[] = []
  private toolUseContext: ToolUseContext
  private hasErrored = false
  // 子 AbortController：当一个 Bash 工具出错时，
  // 兄弟子进程立即死亡，但不中止父级查询
  private siblingAbortController: AbortController
  private discarded = false

  addTool(block: ToolUseBlock, assistantMessage: AssistantMessage): void {
    const toolDefinition = findToolByName(this.toolDefinitions, block.name)
    if (!toolDefinition) {
      // 工具不存在 → 立即创建错误结果
      this.tools.push({
        id: block.id, block, assistantMessage,
        status: 'completed',
        isConcurrencySafe: true,
        pendingProgress: [],
        results: [createUserMessage({
          content: [{
            type: 'tool_result',
            content: `<tool_use_error>Error: No such tool: ${block.name}</tool_use_error>`,
            is_error: true,
            tool_use_id: block.id,
          }],
        })],
      })
      return
    }

    // 解析输入并判断是否可并发
    const parsedInput = toolDefinition.inputSchema.safeParse(block.input)
    const isConcurrencySafe = parsedInput?.success
      ? Boolean(toolDefinition.isConcurrencySafe(parsedInput.data))
      : false

    this.tools.push({
      id: block.id, block, assistantMessage,
      status: 'queued', isConcurrencySafe,
      pendingProgress: [],
    })

    void this.processQueue()  // 立即开始处理
  }

  // 当流式回退发生时，丢弃所有待处理和进行中的工具
  discard(): void { this.discarded = true }
}

// src/services/tools/toolOrchestration.ts — 真实代码
export async function* runTools(
  toolUseMessages: ToolUseBlock[],
  assistantMessages: AssistantMessage[],
  canUseTool: CanUseToolFn,
  toolUseContext: ToolUseContext,
): AsyncGenerator<MessageUpdate, void> {
  let currentContext = toolUseContext

  // 核心设计：工具分区
  for (const { isConcurrencySafe, blocks } of partitionToolCalls(
    toolUseMessages, currentContext,
  )) {
    if (isConcurrencySafe) {
      // ===== 只读批次：并发执行 =====
      const queuedContextModifiers: Record<string, ((ctx) => ctx)[]> = {}
      for await (const update of runToolsConcurrently(blocks, https://wanlanglin.github.io/-awesome-cc-harness/.)) {
        if (update.contextModifier) {
          // 收集上下文修改器，延迟应用
          queuedContextModifiers[update.contextModifier.toolUseID]
            ?.push(update.contextModifier.modifyContext)
        }
        yield { message: update.message, newContext: currentContext }
      }
      // 批次完成后，按顺序应用所有上下文修改
      for (const block of blocks) {
        for (const modifier of queuedContextModifiers[block.id] ?? []) {
          currentContext = modifier(currentContext)
        }
      }
    } else {
      // ===== 写入批次：串行执行 =====
      for await (const update of runToolsSerially(blocks, https://wanlanglin.github.io/-awesome-cc-harness/.)) {
        if (update.newContext) currentContext = update.newContext
        yield { message: update.message, newContext: currentContext }
      }
    }
  }
}

输入: [Read("a.ts"), Read("b.ts"), Write("c.ts"), Read("d.ts")]

分区结果:
  批次 1: { isConcurrencySafe: true,  blocks: [Read("a.ts"), Read("b.ts")] }
  批次 2: { isConcurrencySafe: false, blocks: [Write("c.ts")] }
  批次 3: { isConcurrencySafe: true,  blocks: [Read("d.ts")] }

执行顺序: 批次 1 并发 → 批次 2 串行 → 批次 3 并发

// src/query.ts — 真实的 413 恢复代码
if (isWithheld413) {
  // 第 1 步: 排空 context-collapse 队列
  // 只有在上次 transition 不是 collapse_drain_retry 时才尝试
  // （如果已经排空过但仍然 413，跳过直接进入 reactive compact）
  if (feature('CONTEXT_COLLAPSE') && contextCollapse
      && state.transition?.reason !== 'collapse_drain_retry') {
    const drained = contextCollapse.recoverFromOverflow(messagesForQuery, querySource)
    if (drained.committed > 0) {
      state = { https://wanlanglin.github.io/-awesome-cc-harness/.state,
        messages: drained.messages,
        transition: { reason: 'collapse_drain_retry', committed: drained.committed },
      }
      continue  // ← Continue Site 1
    }
  }
}

// 第 2 步: Reactive Compact（完整摘要）
if ((isWithheld413 || isWithheldMedia) && reactiveCompact) {
  const compacted = await reactiveCompact.tryReactiveCompact({
    hasAttempted: hasAttemptedReactiveCompact,  // 防止无限循环
    querySource,
    aborted: toolUseContext.abortController.signal.aborted,
    messages: messagesForQuery,
    cacheSafeParams: { systemPrompt, userContext, systemContext, https://wanlanglin.github.io/-awesome-cc-harness/. },
  })

  if (compacted) {
    // 预算跟踪：捕获压缩前的最终上下文窗口
    if (params.taskBudget) {
      const preCompactContext = finalContextTokensFromLastResponse(messagesForQuery)
      taskBudgetRemaining = Math.max(0,
        (taskBudgetRemaining ?? params.taskBudget.total) - preCompactContext)
    }

    const postCompactMessages = buildPostCompactMessages(compacted)
    for (const msg of postCompactMessages) { yield msg }

    state = { https://wanlanglin.github.io/-awesome-cc-harness/.state,
      messages: postCompactMessages,
      hasAttemptedReactiveCompact: true,
      transition: { reason: 'reactive_compact_retry' },
    }
    continue  // ← Continue Site 2
  }

  // 第 3 步: 所有恢复失败 → 向用户报告
  // 关键：不要进入 Stop Hooks！模型从未产生有效响应，
  // Stop Hooks 无法有意义地评估。运行 Stop Hooks 会造成死亡螺旋：
  // error → hook blocking → retry → error → https://wanlanglin.github.io/-awesome-cc-harness/.
  yield lastMessage
  void executeStopFailureHooks(lastMessage, toolUseContext)
  return { reason: 'prompt_too_long' }
}

// src/query.ts — 真实的 max_output_tokens 恢复代码
if (isWithheldMaxOutputTokens(lastMessage)) {

  // 升级重试：如果使用了默认的 8k 上限，升级到 64k 重试 **同一请求**
  // 无 meta 消息，无多轮交互
  const capEnabled = getFeatureValue_CACHED_MAY_BE_STALE('tengu_otk_slot_v1', false)
  if (capEnabled && maxOutputTokensOverride === undefined
      && !process.env.CLAUDE_CODE_MAX_OUTPUT_TOKENS) {
    logEvent('tengu_max_tokens_escalate', { escalatedTo: ESCALATED_MAX_TOKENS })
    state = { https://wanlanglin.github.io/-awesome-cc-harness/.state,
      maxOutputTokensOverride: ESCALATED_MAX_TOKENS,  // 64k
      transition: { reason: 'max_output_tokens_escalate' },
    }
    continue  // ← Continue Site 3
  }

  // 多轮恢复：注入恢复消息，要求模型从断点继续
  if (maxOutputTokensRecoveryCount < MAX_OUTPUT_TOKENS_RECOVERY_LIMIT) {  // 限制 3 次
    const recoveryMessage = createUserMessage({
      content: `Output token limit hit. Resume directly — no apology, no recap. ` +
        `Pick up mid-thought if that is where the cut happened. ` +
        `Break remaining work into smaller pieces.`,
      isMeta: true,
    })

    state = { https://wanlanglin.github.io/-awesome-cc-harness/.state,
      messages: [https://wanlanglin.gihttps://wanlanglin.github.io/-awesome-cc-harness/ub.io/-awesome-cc-harness/.messagesForQuery, ...assistantMessages, recoveryMessage],
      maxOutputTokensRecoveryCount: maxOutputTokensRecoveryCount + 1,
      transition: {
        reason: 'max_output_tokens_recovery',
        attempt: maxOutputTokensRecoveryCount + 1,
      },
    }
    continue  // ← Continue Site 4
  }

  // 恢复耗尽 → 展示被截断的错误
  yield lastMessage
}

// src/query.ts — Stop Hook 阻止后的恢复
const stopHookResult = yield* handleStopHooks(
  messagesForQuery, assistantMessages, systemPrompt,
  userContext, systemContext, toolUseContext, querySource, stopHookActive,
)

if (stopHookResult.preventContinuation) {
  return { reason: 'stop_hook_prevented' }
}

if (stopHookResult.blockingErrors.length > 0) {
  state = { https://wanlanglin.github.io/-awesome-cc-harness/.state,
    messages: [https://wanlanglin.gihttps://wanlanglin.githttps://wanlanglin.github.io/-awesome-cc-harness/b.io/-awesome-cc-harness/ub.io/-awesome-cc-harness/.messagesForQuery, ...assistantMessages, ...stopHookResult.blockingErrors],
    maxOutputTokensRecoveryCount: 0,
    // 关键：保留 hasAttemptedReactiveCompact 标志！
    // 如果 compact 已经运行但无法恢复 prompt-too-long，
    // 重置此标志会导致无限循环：
    // compact → 仍然太长 → error → stop hook → compact → https://wanlanglin.github.io/-awesome-cc-harness/.
    hasAttemptedReactiveCompact,
    stopHookActive: true,
    transition: { reason: 'stop_hook_blocking' },
  }
  continue  // ← Continue Site 5
}

// query.ts 中的 10 种终止原因
return { reason: 'completed' }           // 正常完成（无工具调用 + Stop Hook 不阻止）
return { reason: 'blocking_limit' }      // 硬性 token 限制
return { reason: 'stop_hook_prevented' } // Stop Hook 阻止继续
return { reason: 'aborted_streaming' }   // 用户中断（模型响应中）
return { reason: 'aborted_tools' }       // 用户中断（工具执行中）
return { reason: 'hook_stopped' }        // Hook 附件停止继续
return { reason: 'max_turns', turnCount }// 达到最大轮次限制
return { reason: 'prompt_too_long' }     // 413 恢复耗尽
return { reason: 'image_error' }         // 图片/PDF 太大
return { reason: 'model_error', error }  // 意外异常

type Tool<
  Input extends AnyObject = AnyObject,
  Output = unknown,
  P extends ToolProgressData = ToolProgressData,
> = {
  // ===== 核心标识 =====
  name: string;                    // 工具名称（主标识符）
  aliases?: string[];              // 别名（向后兼容）
  userFacingName(): string;        // 显示名称

  // ===== Schema & 验证 =====
  inputSchema: ZodType<Input>;     // Zod 输入验证
  inputJSONSchema?: JSONSchema;    // 可选 JSON Schema（MCP 工具）
  outputSchema?: ZodType<Output>;  // 可选输出类型
  validateInput(input): Promise<ValidationResult>;

  // ===== 执行 =====
  call(
    args: Input,
    context: ToolUseContext,
    canUseTool: CanUseTool,
    parentMessage: AssistantMessage,
    progressCallback?: ProgressCallback<P>,
  ): Promise<ToolResult<Output>>;

  // ===== 权限 & 安全 =====
  checkPermissions(args, context): Promise<PermissionDecision>;
  isConcurrencySafe(args): boolean;      // 能否并行执行
  isDestructive(args): boolean;          // 不可逆操作？
  isReadOnly(): boolean;                 // 只读操作？
  preparePermissionMatcher(args): string; // Hook 模式匹配

  // ===== 行为 =====
  isEnabled(): boolean;                  // 特性门控检查
  interruptBehavior(): 'cancel' | 'block';
  requiresUserInteraction(): boolean;

  // ===== 渲染 =====
  renderToolUseMessage(args): ReactElement;
  renderToolResultMessage(result): ReactElement;
  renderToolUseProgressMessage(progress): ReactElement;

  // ===== 搜索 & 折叠 =====
  searchHint: string;                    // ToolSearch 的 3-10 词关键词
  shouldDefer: boolean;                  // 延迟加载
  alwaysLoad: boolean;                   // 永不延迟

  // ===== 描述（动态生成）=====
  description(isNonInteractive?: boolean): string;
  prompt(context): string;               // 系统提示片段
};

// 唯一的工具真实来源
function getAllBaseTools(): Tool[] {
  return [
    // === 始终加载 ===
    AgentTool,
    TaskOutputTool,
    BashTool,
    FileReadTool,
    FileEditTool,
    FileWriteTool,
    WebFetchTool,
    WebSearchTool,
    AskUserQuestionTool,
    SkillTool,
    // https://wanlanglin.github.io/-awesome-cc-harness/.更多始终可用的工具

    // === 特性门控 ===
    https://wanlanglin.github.io/-awesome-cc-harness/.(feature('PROACTIVE') ? [SleepTool] : []),
    https://wanlanglin.github.io/-awesome-cc-harness/.(feature('AGENT_TRIGGERS') ? [ScheduleCronTool] : []),
    https://wanlanglin.github.io/-awesome-cc-harness/.(feature('COORDINATOR_MODE') ? [TeamCreateTool, TeamDeleteTool] : []),
    https://wanlanglin.github.io/-awesome-cc-harness/.(isReplModeEnabled() ? [REPLTool] : []),
    // https://wanlanglin.github.io/-awesome-cc-harness/.更多条件工具
  ];
}

// Bun 的 bun:bundle 在编译时评估 feature() 调用
// 如果 feature('PROACTIVE') 编译为 false:
https://wanlanglin.github.io/-awesome-cc-harness/.(false ? [SleepTool] : [])
// → SleepTool 的全部代码被 tree-shake 移除
// 包括其引用的所有字符串和依赖

function assembleToolPool(builtInTools: Tool[], mcpTools: Tool[]): Tool[] {
  // 1. 过滤被 deny 规则禁止的 MCP 工具
  const filteredMcp = mcpTools.filter(t => !getDenyRuleForTool(t));

  // 2. 分别排序（保持 prompt cache 稳定性）
  const sortedBuiltIn = sortBy(builtInTools, t => t.name);
  const sortedMcp = sortBy(filteredMcp, t => t.name);

  // 3. 连接：内置工具在前（作为缓存前缀）
  const combined = [https://wanlanglinhttps://wanlanglin.github.io/-awesome-cc-harness/ithub.io/-awesome-cc-harness/.sortedBuiltIn, ...sortedMcp];

  // 4. 去重（内置优先）
  return uniqBy(combined, t => t.name);
}

用户/模型请求工具调用
    │
    v
┌─────────────────────────┐
│ 1. validateInput()       │  结构验证（必填字段、范围）
│    使用 Zod Schema       │
└────────┬────────────────┘
         │ 通过
         v
┌─────────────────────────┐
│ 2. checkPermissions()    │  工具特定的权限逻辑
│    返回 allow/ask/deny   │
└────────┬────────────────┘
         │ 未被拒绝
         v
┌─────────────────────────┐
│ 3. Rule-Based Perms      │  设置中的 allow/deny/ask 规则
│    checkRuleBasedPerms() │
└────────┬────────────────┘
         │ 未被拒绝
         v
┌─────────────────────────┐
│ 4. PreToolUse Hooks      │  用户定义的 Hook
│    可批准或阻止           │
└────────┬────────────────┘
         │ 未被阻止
         v
┌─────────────────────────┐
│ 5. User Prompt/Classifier│  最终审批（或自动分类器）
│    auto 模式：YOLO 分类器│
└────────┬────────────────┘
         │ 批准
         v
┌─────────────────────────┐
│ 6. call()                │  实际执行工具
│    返回 ToolResult       │
└────────┬────────────────┘
         │
         v
┌─────────────────────────┐
│ 7. PostToolUse Hooks     │  执行后回调
│    审计日志、通知等       │
└─────────────────────────┘

// src/services/tools/toolExecution.ts — 真实的执行管道
async function checkPermissionsAndCallTool(
  tool: Tool,
  toolUseID: string,
  input: Record<string, unknown>,
  toolUseContext: ToolUseContext,
  canUseTool: CanUseToolFn,
  assistantMessage: AssistantMessage,
  onToolProgress: (progress: ToolProgress) => void,
): Promise<MessageUpdate[]> {

  // ===== 步骤 1: Zod Schema 验证 =====
  const parsedInput = tool.inputSchema.safeParse(input)
  if (!parsedInput.success) {
    return [{ message: createUserMessage({
      content: formatZodValidationError(tool.name, parsedInput.error),
    }) }]
  }

  // ===== 步骤 2: 工具特定验证 =====
  const isValidCall = await tool.validateInput?.(parsedInput.data, toolUseContext)
  if (isValidCall?.result === false) {
    return [{ message: createUserMessage({
      content: isValidCall.message,
    }) }]
  }

  // ===== 步骤 3: PreToolUse Hook =====
  // Hook 可以：批准、阻止、修改输入、注入上下文
  let processedInput = parsedInput.data
  let hookPermissionResult: PermissionResult | undefined
  for await (const result of runPreToolUseHooks(https://wanlanglin.github.io/-awesome-cc-harness/.)) {
    switch (result.type) {
      case 'hookPermissionResult':
        hookPermissionResult = result.hookPermissionResult
        break
      case 'hookUpdatedInput':
        processedInput = result.updatedInput  // Hook 修改了输入！
        break
    }
  }

  // ===== 步骤 4: 权限解析（Hook + Rules 交互）=====
  // 关键设计：Hook 的 'allow' 不绕过 settings.json 的 deny/ask 规则
  const { decision, input: callInput } = await resolveHookPermissionDecision(
    hookPermissionResult, tool, processedInput,
    toolUseContext, canUseTool, assistantMessage, toolUseID,
  )
  if (decision.behavior !== 'allow') {
    return [/* 权限被拒绝的消息 */]
  }

  // ===== 步骤 5: 实际执行工具 =====
  let toolResult = await tool.call(
    callInput, toolUseContext, canUseTool,
    assistantMessage, onToolProgress,
  )

  // ===== 步骤 6: PostToolUse Hook =====
  // Hook 可以：修改 MCP 工具输出、注入额外上下文
  for await (const result of runPostToolUseHooks(https://wanlanglin.github.io/-awesome-cc-harness/.)) {
    if (result.updatedMCPToolOutput) {
      toolResult = { https://wanlanglin.github.io/-awesome-cc-harness/.toolResult, data: result.updatedMCPToolOutput }
    }
  }

  // ===== 步骤 7: 转换为 API 格式并返回 =====
  return resultingMessages
}

// src/services/tools/toolHooks.ts — 真实代码
export async function resolveHookPermissionDecision(
  hookPermissionResult, tool, input, toolUseContext,
  canUseTool, assistantMessage, toolUseID,
) {
  if (hookPermissionResult?.behavior === 'allow') {
    // Hook 说"允许"——但这不是最终判决！
    // deny/ask 规则仍然适用（安全不可变量）

    // 如果工具需要用户交互，且 Hook 提供了 updatedInput，
    // 那么 Hook 就是"用户交互"（如 headless 包装器）
    const interactionSatisfied =
      tool.requiresUserInteraction?.() &&
      hookPermissionResult.updatedInput !== undefined

    // 即使 Hook 允许，仍检查规则
    const ruleCheck = await checkRuleBasedPermissions(tool, input, toolUseContext)
    if (ruleCheck?.behavior === 'deny') {
      // Deny 规则覆盖 Hook 的 allow！
      return { decision: ruleCheck, input }
    }
    if (ruleCheck?.behavior === 'ask') {
      // Ask 规则仍需要对话框
      return { decision: await canUseTool(https://wanlanglin.github.io/-awesome-cc-harness/.), input }
    }

    // 无规则阻止 → Hook 的 allow 生效
    return { decision: hookPermissionResult, input }
  }
  // https://wanlanglin.github.io/-awesome-cc-harness/. deny 和 ask 处理
}

// src/tools/FileEditTool/utils.ts — 真实代码

// 问题：模型有时生成 "curly quotes"（智能引号）
// 但文件中是 "straight quotes"（直引号），或反之
const LEFT_DOUBLE_CURLY_QUOTE = '\u201C'   // "
const RIGHT_DOUBLE_CURLY_QUOTE = '\u201D'  // "

function normalizeQuotes(str: string): string {
  return str
    .replaceAll('\u2018', "'")   // ' → '
    .replaceAll('\u2019', "'")   // ' → '
    .replaceAll('\u201C', '"')   // " → "
    .replaceAll('\u201D', '"')   // " → "
}

// 三阶段查找算法
function findActualString(fileContent: string, searchString: string): string | null {
  // 阶段 1: 精确匹配
  if (fileContent.includes(searchString)) return searchString

  // 阶段 2: 引号规范化匹配
  const normalizedSearch = normalizeQuotes(searchString)
  const normalizedFile = normalizeQuotes(fileContent)
  const searchIndex = normalizedFile.indexOf(normalizedSearch)
  if (searchIndex !== -1) {
    // 返回文件中的 **原始** 字符串（保留原始引号风格）
    return fileContent.substring(searchIndex, searchIndex + searchString.length)
  }

  return null
}

// 替换算法
function applyEditToFile(
  originalContent: string,
  oldString: string,
  newString: string,
  replaceAll: boolean = false,
): string {
  const f = replaceAll
    ? (content, search, replace) => content.replaceAll(search, () => replace)
    : (content, search, replace) => content.replace(search, () => replace)

  if (newString !== '') return f(originalContent, oldString, newString)

  // 边界情况：删除操作
  // 如果 oldString 不以换行结尾，但文件中 oldString 后面紧跟换行，
  // 同时删除那个换行（防止留下空行）
  const stripTrailingNewline =
    !oldString.endsWith('\n') && originalContent.includes(oldString + '\n')

  return stripTrailingNewline
    ? f(originalContent, oldString + '\n', newString)
    : f(originalContent, oldString, newString)
}

// 并非所有工具都在第一轮加载
// shouldDefer = true 的工具不发送给模型
// 直到 ToolSearchTool 被调用发现它们

// 例：NotebookEditTool
{
  name: 'NotebookEdit',
  shouldDefer: true,        // 第一轮不加载
  searchHint: 'jupyter notebook cell edit insert',
  alwaysLoad: false,
}

// 例：BashTool
{
  name: 'Bash',
  shouldDefer: false,       // 始终加载
  alwaysLoad: true,         // 永不延迟
}

type PermissionMode =
  | 'default'            // 敏感操作始终询问
  | 'acceptEdits'        // 自动批准文件编辑，其他询问
  | 'bypassPermissions'  // 自动批准一切（危险）
  | 'dontAsk'           // 自动拒绝需要询问的操作
  | 'plan'              // 计划模式限制（只读 + 计划文件）
  | 'auto'              // AI 分类器自动审批（实验性）
  | 'bubble';           // 冒泡到父 Agent（子 Agent 用）

type PermissionRule = {
  source: PermissionRuleSource;  // 规则来源
  ruleBehavior: 'allow' | 'deny' | 'ask';
  ruleValue: {
    toolName: string;       // 例: "Bash", "Write", "mcp__server"
    ruleContent?: string;   // 例: "git *", "*.ts", "prefix:npm *"
  };
};

# 允许所有 git 命令
Bash(git *)

# 允许写入 TypeScript 文件
Write(*.ts)

# 拒绝所有 MCP 服务器工具
mcp__*

# 允许读取任何文件
Read

# 拒绝 rm -rf 命令
Bash(rm -rf *)

# 允许特定 MCP 服务器的所有工具
mcp__my-server(*)

优先级最高
    ↓
1. CLI 参数 (cliArg)              — 命令行覆盖
2. 会话命令 (command)              — /permissions 命令
3. Flag 设置 (flagSettings)        — CLAUDE_CODE_FLAG_SETTINGS
4. 策略设置 (policySettings)       — 组织策略
5. 本地设置 (localSettings)        — .claude/settings.json.local
6. 项目设置 (projectSettings)      — .claude/settings.json
7. 用户设置 (userSettings)         — ~/.claude/settings.json
    ↓
优先级最低

Managed Settings（MDM/企业）:
├── /managed/managed-settings.json        — 基础管理设置
├── /managed/managed-settings.d/*.json    — Drop-in 覆盖
└── macOS plutil / Windows Registry       — 操作系统级 MDM

// src/utils/permissions/permissions.ts — 真实代码
async function hasPermissionsToUseToolInner(
  tool: Tool, input: Record<string, unknown>, context: ToolUseContext,
): Promise<PermissionDecision> {

  if (context.abortController.signal.aborted) throw new AbortError()

  let appState = context.getAppState()

  // ===== 1a. 整个工具被 Deny =====
  const denyRule = getDenyRuleForTool(appState.toolPermissionContext, tool)
  if (denyRule) {
    return { behavior: 'deny', decisionReason: { type: 'rule', rule: denyRule },
      message: `Permission to use ${tool.name} has been denied.` }
  }

  // ===== 1b. 整个工具被 Ask =====
  const askRule = getAskRuleForTool(appState.toolPermissionContext, tool)
  if (askRule) {
    // 特殊情况：沙盒自动允许
    // 当 autoAllowBashIfSandboxed 开启时，沙盒化的命令跳过 ask 规则
    // 不会沙盒化的命令（排除命令、dangerouslyDisableSandbox）仍遵守 ask
    const canSandboxAutoAllow =
      tool.name === BASH_TOOL_NAME &&
      SandboxManager.isSandboxingEnabled() &&
      SandboxManager.isAutoAllowBashIfSandboxedEnabled() &&
      shouldUseSandbox(input)
    if (!canSandboxAutoAllow) {
      return { behavior: 'ask', decisionReason: { type: 'rule', rule: askRule } }
    }
    // 落入下方让 Bash 的 checkPermissions 处理命令级规则
  }

  // ===== 1c. 工具特定权限检查 =====
  let toolPermissionResult: PermissionResult = { behavior: 'passthrough' }
  try {
    const parsedInput = tool.inputSchema.parse(input)
    toolPermissionResult = await tool.checkPermissions(parsedInput, context)
  } catch (e) {
    if (e instanceof AbortError) throw e
    logError(e)
  }

  // ===== 1d. 工具实现拒绝 =====
  if (toolPermissionResult?.behavior === 'deny') return toolPermissionResult

  // ===== 1e. 需要用户交互的工具 =====
  if (tool.requiresUserInteraction?.() && toolPermissionResult?.behavior === 'ask') {
    return toolPermissionResult
  }

  // ===== 1f. 内容级 ask 规则（重要！）=====
  // 当用户配置了内容级 ask 规则如 Bash(npm publish:*)，
  // tool.checkPermissions 返回 {behavior:'ask', decisionReason:{type:'rule', ruleBehavior:'ask'}}
  // 这必须被尊重，即使在 bypassPermissions 模式下！
  if (toolPermissionResult?.behavior === 'ask' &&
      toolPermissionResult.decisionReason?.type === 'rule' &&
      toolPermissionResult.decisionReason.rule.ruleBehavior === 'ask') {
    return toolPermissionResult
  }

  // ===== 1g. 安全检查（不可绕过）=====
  // .git/, .claude/, .vscode/, shell 配置等路径
  // 即使 bypassPermissions 模式也必须提示
  if (toolPermissionResult?.behavior === 'ask' &&
      toolPermissionResult.decisionReason?.type === 'safetyCheck') {
    return toolPermissionResult
  }

  // ===== 2a. 模式检查 =====
  appState = context.getAppState()  // 重新获取最新状态
  const shouldBypassPermissions =
    appState.toolPermissionContext.mode === 'bypassPermissions' ||
    (appState.toolPermissionContext.mode === 'plan' &&
     appState.toolPermissionContext.isBypassPermissionsModeAvailable)
  if (shouldBypassPermissions) {
    return { behavior: 'allow', decisionReason: { type: 'mode', mode: 'https://wanlanglin.github.io/-awesome-cc-harness/.' } }
  }

  // ===== 2b. 整个工具被 Allow =====
  const allowRule = toolAlwaysAllowedRule(appState.toolPermissionContext, tool)
  if (allowRule) {
    return { behavior: 'allow', decisionReason: { type: 'rule', rule: allowRule } }
  }

  // ===== 3. passthrough → ask =====
  return toolPermissionResult.behavior === 'passthrough'
    ? { https://wanlanglin.github.io/-awesome-cc-harness/.toolPermissionResult, behavior: 'ask' }
    : toolPermissionResult
}

// ===== 外层包装：模式转换 =====
export const hasPermissionsToUseTool: CanUseToolFn = async (https://wanlanglin.github.io/-awesome-cc-harness/.) => {
  const result = await hasPermissionsToUseToolInner(https://wanlanglin.github.io/-awesome-cc-harness/.)

  // 允许 → 重置连续拒绝计数器
  if (result.behavior === 'allow') {
    if (feature('TRANSCRIPT_CLASSIFIER') && context.mode === 'auto') {
      persistDenialState(context, recordSuccess(currentDenialState))
    }
    return result
  }

  // ask → 模式转换
  if (result.behavior === 'ask') {
    if (appState.toolPermissionContext.mode === 'dontAsk') {
      return { behavior: 'deny', decisionReason: { type: 'mode', mode: 'dontAsk' } }
    }
    // auto 模式 → AI 分类器（见 5.5 节）
  }
  return result
}

                    工具调用请求
                        │
          ┌─────────────┼─────────────┐
          │             │             │
     Deny 规则?    Ask 规则?     Allow 规则?
       │ 是            │ 是           │ 是
       v              │             v
     拒绝          沙盒可以        允许
                  自动允许?
                   │ 否
                   v
               tool.checkPermissions()
                   │
          ┌────────┼────────┐
          │        │        │
        deny     ask      allow/
          │        │      passthrough
          v        │        │
        拒绝    内容级规则?   │
                 │ 是       │
                 v         │
               拒绝/询问   │
                           │
                 安全检查?──┤
                  │ 是     │
                  v        │
                 询问      │
                           │
              bypassPermissions?
                  │ 是     │ 否
                  v        v
                允许    Allow 规则?
                         │ 是  │ 否
                         v     v
                       允许   ask → 模式转换
                              ├─ dontAsk → deny
                              ├─ auto → AI 分类器
                              └─ default → 用户提示

// src/utils/permissions/permissionRuleParser.ts — 真实代码

// 输入: "Bash(python -c \"print\\(1\\)\")"
// 输出: { toolName: "Bash", ruleContent: "python -c \"print(1)\"" }
export function permissionRuleValueFromString(ruleString: string): PermissionRuleValue {
  // 找到第一个 **未转义** 的左括号
  const openParenIndex = findFirstUnescapedChar(ruleString, '(')
  if (openParenIndex === -1) {
    return { toolName: normalizeLegacyToolName(ruleString) }
  }

  // 找到最后一个 **未转义** 的右括号
  const closeParenIndex = findLastUnescapedChar(ruleString, ')')
  if (closeParenIndex === -1 || closeParenIndex <= openParenIndex) {
    return { toolName: normalizeLegacyToolName(ruleString) }
  }

  // 右括号必须在末尾
  if (closeParenIndex !== ruleString.length - 1) {
    return { toolName: normalizeLegacyToolName(ruleString) }
  }

  const toolName = ruleString.substring(0, openParenIndex)
  const rawContent = ruleString.substring(openParenIndex + 1, closeParenIndex)

  // 空内容 "Bash()" 或通配符 "Bash(*)" → 工具级规则
  if (rawContent === '' || rawContent === '*') {
    return { toolName: normalizeLegacyToolName(toolName) }
  }

  // 反转义: \\( → (, \\) → ), \\\\ → \\
  const ruleContent = unescapeRuleContent(rawContent)
  return { toolName: normalizeLegacyToolName(toolName), ruleContent }
}

// 判断字符是否被转义（前面有奇数个反斜杠）
function findFirstUnescapedChar(str: string, char: string): number {
  for (let i = 0; i < str.length; i++) {
    if (str[i] === char) {
      let backslashCount = 0
      let j = i - 1
      while (j >= 0 && str[j] === '\\') { backslashCount++; j-- }
      if (backslashCount % 2 === 0) return i  // 偶数个反斜杠 = 未转义
    }
  }
  return -1
}

// 规则 "mcp__server1" 匹配工具 "mcp__server1__tool1"
// 规则 "mcp__server1__*" 匹配 server1 的所有工具
function toolMatchesRule(tool, rule): boolean {
  if (rule.ruleValue.ruleContent !== undefined) return false  // 内容规则不匹配整个工具

  const nameForRuleMatch = getToolNameForPermissionCheck(tool)
  if (rule.ruleValue.toolName === nameForRuleMatch) return true

  // MCP 服务器级匹配
  const ruleInfo = mcpInfoFromString(rule.ruleValue.toolName)
  const toolInfo = mcpInfoFromString(nameForRuleMatch)
  return ruleInfo !== null && toolInfo !== null &&
    (ruleInfo.toolName === undefined || ruleInfo.toolName === '*') &&
    ruleInfo.serverName === toolInfo.serverName
}

阶段 1: Fast 分类器
├─ 使用较小/快速模型
├─ 检查：这个操作安全吗？
├─ 返回 confidence: high/medium/low
├─ 如果 high confidence + shouldBlock=false → 直接批准
└─ 如果不确定 → 进入阶段 2

阶段 2: Thinking 分类器
├─ 使用更大/更深思考的模型
├─ 分析完整上下文（对话历史 + 工具输入）
├─ 返回最终判断
└─ 如果仍不确定 → 降级为用户询问

安全工具快速路径:
├─ Read, Glob, Grep 等只读工具
├─ 跳过 API 调用（节省延迟和成本）
└─ 直接返回 allow

连续拒绝跟踪:
├─ 如果分类器连续拒绝多次
├─ 回退到用户提示
└─ 防止分类器过度保守时卡住

type PermissionDecisionReason =
  | { type: 'rule'; rule: PermissionRule }
  | { type: 'mode'; mode: PermissionMode }
  | { type: 'classifier'; classifier: string; reason: string }
  | { type: 'hook'; hookName: string; reason?: string }
  | { type: 'safetyCheck'; reason: string; classifierApprovable: boolean }
  // https://wanlanglin.github.io/-awesome-cc-harness/. 更多变体

// src/types/hooks.ts — 完整的 Hook 事件列表
type HookEvent =
  // 工具相关
  | 'PreToolUse'        // 工具执行前
  | 'PostToolUse'       // 工具执行后
  | 'PostToolUseFailure'// 工具执行失败后

  // 权限
  | 'PermissionRequest' // 权限请求
  | 'PermissionDenied'  // 权限被拒绝

  // 会话
  | 'SessionStart'      // 会话开始
  | 'SessionEnd'        // 会话结束
  | 'Stop'              // 模型停止
  | 'StopFailure'       // 停止失败

  // 用户输入
  | 'UserPromptSubmit'  // 用户提交提示

  // Agent
  | 'SubagentStart'     // 子 Agent 启动
  | 'SubagentStop'      // 子 Agent 停止
  | 'TeammateIdle'      // 队友空闲

  // 任务
  | 'TaskCreated'       // 任务创建
  | 'TaskCompleted'     // 任务完成

  // 压缩
  | 'PreCompact'        // 压缩前
  | 'PostCompact'       // 压缩后

  // 其他
  | 'Setup'             // 初始设置
  | 'Notification'      // 通知
  | 'Elicitation'       // 信息请求
  | 'ElicitationResult' // 信息请求结果
  | 'ConfigChange'      // 配置变更
  | 'CwdChanged'        // 工作目录变更
  | 'FileChanged'       // 文件变更
  | 'WorktreeCreate'    // Worktree 创建
  | 'WorktreeRemove'    // Worktree 移除
  | 'InstructionsLoaded'; // 指令加载完成

{
  "type": "command",
  "command": "npm test -- --bail",
  "if": "Bash(npm *)",
  "shell": "bash",
  "timeout": 30,
  "statusMessage": "Running testshttps://wanlanglin.github.io/-awesome-cc-harness/.",
  "once": false,
  "async": false,
  "asyncRewake": false
}

{
  "type": "prompt",
  "prompt": "Review this code change for security vulnerabilities: $ARGUMENTS",
  "model": "claude-sonnet-4-6",
  "timeout": 60
}

{
  "type": "http",
  "url": "https://hooks.slack.com/triggers/https://wanlanglin.github.io/-awesome-cc-harness/.",
  "headers": {
    "Authorization": "Bearer $SLACK_TOKEN"
  },
  "allowedEnvVars": ["SLACK_TOKEN"],
  "timeout": 10
}

{
  "type": "agent",
  "prompt": "Verify that the test suite passes and no regressions were introduced",
  "model": "claude-sonnet-4-6",
  "timeout": 120
}

// ~/.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "eslint --stdin --stdin-filename=$TOOL_INPUT_FILE_PATH",
            "if": "Write(*.ts)"
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"decision\": \"block\", \"reason\": \"sudo is not allowed\"}' ",
            "if": "Bash(sudo *)"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://audit.company.com/log",
            "headers": { "Authorization": "Bearer $AUDIT_TOKEN" },
            "allowedEnvVars": ["AUDIT_TOKEN"]
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "git stash",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

// 所有 Hook 的基础字段
{
  session_id: string,
  transcript_path: string,
  cwd: string,
  permission_mode?: string,
  agent_id?: string,
  agent_type?: string,
}

// PreToolUse 特有字段
{
  tool_name: "Write",
  tool_input: { file_path: "/src/index.ts", content: "https://wanlanglin.github.io/-awesome-cc-harness/." },
  tool_use_id: "toolu_xxx",
}

// PostToolUse 特有字段
{
  tool_name: "Bash",
  tool_input: { command: "npm test" },
  tool_response: { stdout: "https://wanlanglin.github.io/-awesome-cc-harness/.", exit_code: 0 },
  tool_use_id: "toolu_xxx",
}

// UserPromptSubmit
{
  prompt_text: "Fix the bug in login.ts",
}

// SessionStart
{
  source: "startup" | "resume" | "clear" | "compact",
}

type HookJSONOutput = {
  // 全局控制
  continue?: boolean;           // false = 停止对话
  stopReason?: string;
  decision?: 'approve' | 'block';
  reason?: string;
  systemMessage?: string;       // 注入系统消息
  suppressOutput?: boolean;

  // 权限相关
  permissionDecision?: 'allow' | 'deny' | 'ask';

  // 事件特定
  hookSpecificOutput?: {
    updatedInput?: object;           // 修改工具输入（PreToolUse）
    additionalContext?: string;       // 注入额外上下文
    watchPaths?: string[];           // 注册文件监视器
    updatedMCPToolOutput?: unknown;  // 修改 MCP 工具输出
    action?: 'accept' | 'decline' | 'cancel';
  }
};

// src/utils/hooks.ts — 真实代码（简化但保留关键逻辑）
async function* executeHooks({
  hookInput, toolUseID, matchQuery, signal, timeoutMs,
  toolUseContext, messages, forceSyncExecution, requestPrompt,
}) {
  // 安全检查 1: 全局禁用
  if (shouldDisableAllHooksIncludingManaged()) return
  if (isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)) return

  // 安全检查 2: 工作空间信任
  // 所有 Hook 都需要工作空间信任（防止 RCE 漏洞）
  if (shouldSkipHookDueToTrust()) return

  // 查找匹配的 Hook
  const matchingHooks = await getMatchingHooks(
    appState, sessionId, hookEvent, hookInput, tools,
  )
  if (matchingHooks.length === 0) return

  // ===== 快速路径优化 =====
  // 如果所有 Hook 都是内部回调（如 sessionFileAccessHooks、attributionHooks）
  // 跳过 span/progress/abortSignal/JSON处理 → 性能提升 70%
  const userHooks = matchingHooks.filter(h => !isInternalHook(h))
  if (userHooks.length === 0) {
    // 6.01µs → ~1.8µs per PostToolUse hit (-70%)
    for (const { hook } of matchingHooks) {
      if (hook.type === 'callback') {
        await hook.callback(hookInput, toolUseID, signal, context)
      }
    }
    return
  }

  // ===== 并行执行所有 Hook =====
  // 每个 Hook 有独立的超时
  // https://whttps://wanlanglin.github.io/-awesome-cc-harness/langlin.github.io/-awesome-cc-harness/. 聚合结果 ...
}

// src/utils/hooks.ts — execCommandHook 的关键细节
async function execCommandHook(hook, hookEvent, hookName, jsonInput, signal, https://wanlanglin.github.io/-awesome-cc-harness/.) {
  // 1. Shell 选择
  // PowerShell: pwsh -NoProfile -NonInteractive -Command
  // Bash: spawn(command, [], { shell: gitBashPath | true })

  // 2. 变量替换
  // ${CLAUDE_PROJECT_DIR} → 项目目录
  // ${CLAUDE_PLUGIN_ROOT} → 插件目录
  // ${CLAUDE_PLUGIN_DATA} → 插件数据目录
  // ${user_config.X} → 插件配置值

  // 3. stdin 写入（UTF-8 编码）
  child.stdin.write(jsonInput + '\n', 'utf8')

  // 4. stdout 逐行解析
  child.stdout.on('data', data => {
    stdout += data

    // ===== Prompt Request 协议 =====
    // Hook 可以请求用户输入！
    // 输出行格式: {"prompt": {"type": "text", "message": "Enter value:"}}
    if (requestPrompt) {
      for (const line of lines) {
        const parsed = jsonParse(line.trim())
        const validation = promptRequestSchema().safeParse(parsed)
        if (validation.success) {
          // 序列化异步 prompt 处理
          promptChain = promptChain.then(async () => {
            const response = await requestPrompt(validation.data)
            child.stdin.write(jsonStringify(response) + '\n', 'utf8')
          })
          continue
        }
      }
    }

    // ===== 异步检测 =====
    // 第一行输出如果是 {"async": true, https://wanlanglin.github.io/-awesome-cc-harness/.}
    // → 将进程转入后台，主线程继续
    if (!initialResponseChecked) {
      const firstLine = firstLineOf(stdout).trim()
      const parsed = jsonParse(firstLine)
      if (isAsyncHookJSONOutput(parsed) && !forceSyncExecution) {
        executeInBackground({ processId, hookId, https://wanlanglin.github.io/-awesome-cc-harness/. })
        shellCommandTransferred = true
        resolve({ stdout, stderr, output, status: 0 })
      }
    }
  })

  // 5. 等待完成
  // 关键：等待 stdout 和 stderr 流结束后再认为输出完成
  // 防止 'close' 事件在所有 'data' 事件处理前触发的竞态条件
  await Promise.all([stdoutEndPromise, stderrEndPromise])

  // 6. 剥离已处理的 prompt 请求行
  // 使用内容匹配而非索引，防止索引漂移导致的 prompt JSON 泄露
  const finalStdout = processedPromptLines.size === 0 ? stdout :
    stdout.split('\n').filter(line => !processedPromptLines.has(line.trim())).join('\n')

  return { stdout: finalStdout, stderr, output, status: exitCode }
}

// Hook 输出被解析为 JSON，提取决策和副作用
function processHookJSONOutput({ json, https://wanlanglin.github.io/-awesome-cc-harness/. }) {
  const result = {}

  // 全局控制
  if (json.continue === false) result.preventContinuation = true

  // 决策
  if (json.decision === 'approve') result.permissionBehavior = 'allow'
  if (json.decision === 'block') {
    result.permissionBehavior = 'deny'
    result.blockingError = { blockingError: json.reason || 'Blocked by hook' }
  }

  // 事件特定字段
  if (json.hookSpecificOutput?.hookEventName === 'PreToolUse') {
    if (json.hookSpecificOutput.updatedInput) {
      result.updatedInput = json.hookSpecificOutput.updatedInput  // 修改工具输入
    }
    result.additionalContext = json.hookSpecificOutput.additionalContext
  }

  if (json.hookSpecificOutput?.hookEventName === 'PostToolUse') {
    if (json.hookSpecificOutput.updatedMCPToolOutput) {
      result.updatedMCPToolOutput = json.hookSpecificOutput.updatedMCPToolOutput
    }
  }

  return result
}

// Hook 可以通过第一行 JSON 信号异步执行：
// stdout 第一行: {"async": true, "asyncTimeout": 60000}
// 此后 Hook 在后台运行

// 或通过配置：
{ type: 'command', command: 'https://wanlanglin.github.io/-awesome-cc-harness/.', async: true, asyncRewake: true }

// asyncRewake: 如果退出码为 2，排入通知队列唤醒模型
// 用例：后台运行测试套件，失败时通知 Agent

// 只对 git 命令运行
{ "if": "Bash(git *)" }

// 只对 TypeScript 文件写入运行
{ "if": "Write(*.ts)" }

// 只对 npm 命令运行
{ "if": "Bash(prefix:npm)" }

// 匹配所有 Bash 调用
{ "if": "Bash" }

┌─────────────────────────────────────────────────┐
│                 Claude Code                      │
│                                                  │
│  BashTool.call()                                │
│      │                                           │
│      v                                           │
│  shouldUseSandbox()                              │
│      │                                           │
│      ├─ 沙盒是否启用？                            │
│      ├─ dangerouslyDisableSandbox 是否允许？       │
│      ├─ 命令是否在排除列表中？                     │
│      │                                           │
│      v                                           │
│  SandboxManager.wrapWithSandbox(command)         │
│      │                                           │
│      v                                           │
│  @anthropic-ai/sandbox-runtime                   │
│      │                                           │
│      ├─ 文件系统限制                              │
│      ├─ 网络限制                                  │
│      └─ 进程限制                                  │
│                                                  │
└─────────────────────────────────────────────────┘

interface FsReadRestrictionConfig {
  allowRead: string[];   // 允许读取的路径模式
  denyRead: string[];    // 禁止读取的路径模式
}

interface FsWriteRestrictionConfig {
  allowWrite: string[];  // 允许写入的路径模式
  denyWrite: string[];   // 禁止写入的路径模式
}

// 路径语法:
// "/path"   — 相对于设置根路径
// "//path"  — 绝对路径（从根目录开始）
// "~/path"  — 用户主目录
// "./path"  — 当前工作目录
// "*.ext"   — 通配符模式

interface NetworkRestrictionConfig {
  allowedDomains: string[];     // 允许的域名模式
  deniedDomains: string[];      // 禁止的域名模式
  allowUnixSockets?: boolean;   // Unix socket 访问
  allowLocalBinding?: boolean;  // 本地端口绑定
}

// settings.sandbox.excludedCommands
// 匹配模式:
//   "cmd:"    — 前缀匹配
//   "cmd"     — 精确匹配
//   "cmd*"    — 通配符

// 注意: 这 **不是** 安全边界
// 仅为便利功能（跳过沙盒以避免兼容性问题）

// src/utils/sandbox/sandbox-adapter.ts — 真实代码
export function resolvePathPatternForSandbox(
  pattern: string, source: SettingSource,
): string {
  // "//" 前缀 → 从文件系统根目录开始的绝对路径
  // "//.aws/**" → "/.aws/**"
  if (pattern.startsWith('//')) {
    return pattern.slice(1)
  }

  // "/" 前缀 → 相对于设置文件目录
  // 权限规则中 "/foo/**" → "${settings_root}/foo/**"
  if (pattern.startsWith('/') && !pattern.startsWith('//')) {
    const root = getSettingsRootPathForSource(source)
    return resolve(root, pattern.slice(1))
  }

  // 其他模式（~/path, ./path, path）直接传递
  // sandbox-runtime 的 normalizePathForSandbox 会处理
  return pattern
}

// 沙盒初始化是异步的，但必须在第一个命令执行前完成
async function initialize(sandboxAskCallback?) {
  if (initializationPromise) return initializationPromise
  if (!isSandboxingEnabled()) return

  // 包装回调以强制执行 allowManagedDomainsOnly 策略
  const wrappedCallback = sandboxAskCallback ? async (hostPattern) => {
    if (shouldAllowManagedSandboxDomainsOnly()) {
      logForDebugging(`Blocked: ${hostPattern.host} (allowManagedDomainsOnly)`)
      return false
    }
    return sandboxAskCallback(hostPattern)
  } : undefined

  // 创建 Promise（在任何 await 之前同步创建，防止竞态条件）
  initializationPromise = (async () => {
    // 检测 worktree 主仓库路径（会话期间不变，缓存）
    if (worktreeMainRepoPath === undefined) {
      worktreeMainRepoPath = await detectWorktreeMainRepoPath(getCwdState())
    }

    const settings = getSettings_DEPRECATED()
    const runtimeConfig = convertToSandboxRuntimeConfig(settings)
    await BaseSandboxManager.initialize(runtimeConfig, wrappedCallback)

    // 订阅设置变更，动态更新沙盒配置
    settingsSubscriptionCleanup = settingsChangeDetector.subscribe(() => {
      const newConfig = convertToSandboxRuntimeConfig(getSettings_DEPRECATED())
      BaseSandboxManager.updateConfig(newConfig)
    })
  })()

  return initializationPromise
}

// 权限规则 → 沙盒路径转换
// Edit(/path/to/dir/*) → sandbox.filesystem.allowWrite
// Read(/patterns)      → sandbox.filesystem.allowRead
// WebFetch(domain:example.com) → sandbox.network.allowedDomains

function convertToSandboxConfig(
  permissionRules: PermissionRule[],
  sandboxSettings: SandboxSettings,
): SandboxRuntimeConfig {
  // 合并权限规则和沙盒设置
  // 权限规则中的 allow 规则 → sandbox 的 allow 列表
  // 沙盒设置直接映射
  // deny 规则始终包含安全硬编码
}

function isSandboxingEnabled(): boolean {
  return isSupportedPlatform()           // macOS, Linux, WSL2+
    && checkDependencies().errors.length === 0  // bubblewrap, socat
    && isPlatformInEnabledList()         // sandbox.enabledPlatforms
    && getSandboxEnabledSetting();       // 用户设置
}

// 依赖检查（带缓存）
function checkDependencies(): { errors: string[], warnings: string[] } {
  // 检查: bubblewrap 可执行文件
  // 检查: socat 可执行文件
  // 检查: cap_setfcap capability
}

// BashTool 的输入参数
{
  command: "docker build .",
  dangerouslyDisableSandbox: true  // 跳过沙盒
}

// 仅当设置允许时生效:
// settings.sandbox.allowUnsandboxedCommands = true

// 设计意图: 某些命令（如 Docker）不兼容沙盒
// 但必须显式请求并记录在案

# CLAUDE.md

## 项目概述
这是一个 Next.js 14 应用，使用 TypeScript + Tailwind CSS。

## 架构约束
- 组件放在 src/components/
- API 路由放在 src/app/api/
- 不要使用 class 组件
- 所有 API 调用必须使用 fetch，不要用 axios

## 命名规范
- 组件：PascalCase
- 工具函数：camelCase
- 常量：UPPER_SNAKE_CASE

## 测试
- 运行测试: npm test
- 测试框架: Jest + React Testing Library
- 覆盖率要求: >80%

## 已知问题
- #123: 登录页面在 Safari 下有布局问题
- 不要修改 legacy/ 目录下的文件

~/.claude/CLAUDE.md              # 全局（所有项目）
.claude/CLAUDE.md                # 项目级
.claude/CLAUDE.md.local          # 本地覆盖（不提交 git）
子目录/CLAUDE.md                 # 目录级（进入时加载）

// src/QueryEngine.ts — 系统提示构建
function buildSystemPrompt(): SystemPrompt {
  const parts = [];

  // 1. 基础系统提示（工具描述、行为指南）
  parts.push(getBaseSystemPrompt());

  // 2. 工具定义
  for (const tool of tools) {
    parts.push(tool.prompt(context));
  }

  // 3. CLAUDE.md 内容
  parts.push(loadClaudeMd());

  // 4. MCP 服务器指令
  for (const mcp of mcpClients) {
    parts.push(mcp.instructions);
  }

  // 5. 自定义系统提示（用户覆盖）
  if (customPrompt) parts.push(customPrompt);

  // 6. 记忆机制提示（如有记忆系统）
  if (memoryEnabled) parts.push(memoryMechanicsPrompt);

  return asSystemPrompt(parts.join('\n'));
}

type MemoryType =
  | 'user'       // 用户角色、偏好、知识水平
  | 'feedback'   // 工作方法指导（什么可做/避免）
  | 'project'    // 正在进行的工作、目标、倒计时
  | 'reference'; // 外部系统指针

---
name: user-prefers-terse-responses
description: 用户不喜欢冗长的总结，希望简洁直接的回复
type: feedback
---

不要在每次回复末尾总结刚做的事情——用户可以自己读 diff。

**Why:** 用户明确表示不喜欢尾部总结。
**How to apply:** 所有回复保持简洁，不加尾部总结段落。

- [User Role](user_role.md) — 高级 Go 工程师，React 新手
- [Terse Responses](feedback_terse.md) — 不要尾部总结
- [Auth Rewrite](project_auth.md) — 合规驱动的认证中间件重写
- [Bug Tracker](reference_linear.md) — 管道 bug 在 Linear INGEST 项目

// src/memdir/memoryScan.ts
function scanMemories(memoryDir: string): MemoryHeader[] {
  // 扫描 ~/.claude/memory/ 目录
  // 读取每个 .md 文件的 frontmatter
  // 按修改时间排序（最新优先）
  // 上限: MAX_MEMORY_FILES = 200
  return headers;
}

// 与查询循环集成
// 1. 在流式响应期间开始记忆扫描（预取）
startRelevantMemoryPrefetch();

// 2. 过滤相关记忆并创建附件消息
const attachments = getAttachmentMessages(memories, userMessage);

// 3. 附加到用户消息
messages.push(https://wanlanglin.github.io/-awesome-cc-harness/.attachments);

// src/memdir/memoryScan.ts — 真实代码
// 单次遍历：stat + read 合并（减少系统调用）
// 对于常见情况（N ≤ 200），相比先 stat 排序再 read，系统调用减半
export async function scanMemoryFiles(
  memoryDir: string, signal: AbortSignal,
): Promise<MemoryHeader[]> {
  try {
    const entries = await readdir(memoryDir, { recursive: true })
    const mdFiles = entries.filter(
      f => f.endsWith('.md') && basename(f) !== 'MEMORY.md',
    )

    const headerResults = await Promise.allSettled(
      mdFiles.map(async (relativePath): Promise<MemoryHeader> => {
        const filePath = join(memoryDir, relativePath)
        // 只读取前 FRONTMATTER_MAX_LINES 行（优化大文件）
        const { content, mtimeMs } = await readFileInRange(
          filePath, 0, FRONTMATTER_MAX_LINES, undefined, signal,
        )
        const { frontmatter } = parseFrontmatter(content, filePath)
        return {
          filename: relativePath,
          filePath,
          mtimeMs,
          description: frontmatter.description || null,
          type: parseMemoryType(frontmatter.type),
        }
      }),
    )

    return headerResults
      .filter((r): r is PromiseFulfilledResult<MemoryHeader> =>
        r.status === 'fulfilled')
      .map(r => r.value)
      .sort((a, b) => b.mtimeMs - a.mtimeMs)  // 最新优先
      .slice(0, MAX_MEMORY_FILES)  // 上限 200
  } catch {
    return []  // 目录不存在时优雅降级
  }
}

// 用于记忆选择提示和提取 Agent 提示
export function formatMemoryManifest(memories: MemoryHeader[]): string {
  return memories.map(m => {
    const tag = m.type ? `[${m.type}] ` : ''
    const ts = new Date(m.mtimeMs).toISOString()
    return m.description
      ? `- ${tag}${m.filename} (${ts}): ${m.description}`
      : `- ${tag}${m.filename} (${ts})`
  }).join('\n')
}

全转录保存策略:
├─ 每次 autocompact 前保存完整转录到磁盘
├─ 路径: ~/.claude/history/<session_id>/
├─ 用途: --resume 恢复、审计、调试
└─ 不参与压缩决策（仅备份）

预算跟踪跨压缩:
├─ taskBudgetRemaining 在压缩前捕获
├─ 跨多次压缩累计
└─ 确保总支出不超预算

// src/context.ts — 环境上下文收集
function collectContext(): UserContext {
  return {
    currentDate: new Date(),
    platform: process.platform,
    shell: process.env.SHELL,
    osVersion: getOSVersion(),
    modelInfo: getModelInfo(),
    cwd: process.cwd(),
    gitState: getGitState(),        // 分支、状态、远程
    terminalSize: getTerminalSize(),
    // https://wanlanglin.github.io/-awesome-cc-harness/.更多环境信息
  };
}

{
  // ===== 权限 =====
  "permissions": {
    "allow": ["Read", "Glob", "Grep", "Bash(git *)"],
    "deny": ["Bash(sudo *)", "Bash(rm -rf *)"],
    "ask": ["Write(*.env)", "Bash(npm publish)"],
    "defaultMode": "default",
    "additionalDirectories": ["/shared/libs"],
    "disableBypassPermissionsMode": "disable",
    "disableAutoMode": "disable"
  },

  // ===== Hooks =====
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "check-safety.sh",
            "if": "Bash(rm *)"
          }
        ]
      }
    ]
  },

  // ===== 沙盒 =====
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "allowUnsandboxedCommands": false,
    "fsRead": { "allow": ["**"], "deny": ["/etc/shadow"] },
    "fsWrite": { "allow": ["./**"], "deny": [".env", "*.key"] },
    "network": {
      "allowedDomains": ["*.github.com", "registry.npmjs.org"],
      "deniedDomains": ["*.malware.com"]
    },
    "excludedCommands": ["docker", "podman"],
    "lockedByPolicy": false
  },

  // ===== 其他 =====
  "model": "claude-sonnet-4-6",
  "env": {
    "NODE_ENV": "development"
  },
  "attribution": "Co-Authored-By: Claude",
  "cleanupPeriodDays": 30,
  "defaultShell": "bash",
  "allowedMcpServers": ["@anthropic/mcp-*"],
  "deniedMcpServers": ["*-untrusted"]
}

// src/utils/settings/settings.ts
function loadSettings(): MergedSettings {
  // 按优先级从低到高合并
  const layers = [
    loadUserSettings(),          // ~/.claude/settings.json
    loadProjectSettings(),       // .claude/settings.json
    loadLocalSettings(),         // .claude/settings.json.local
    loadPolicySettings(),        // 组织策略
    loadManagedSettings(),       // MDM/企业
    loadFlagSettings(),          // 环境变量
    loadCliArgSettings(),        // 命令行参数
  ];

  return deepMerge(layers);  // 后者覆盖前者
}

/managed/managed-settings.json
├─ 基础管理设置
├─ 由 MDM（Jamf, Intune 等）分发
└─ 可锁定沙盒: { "sandbox": { "lockedByPolicy": true } }

/managed/managed-settings.d/
├─ security-policy.json      # 安全策略 drop-in
├─ compliance-rules.json     # 合规规则 drop-in
└─ (按字母顺序加载，后者覆盖前者)

// src/schemas/ — Zod 验证
const SettingsSchema = z.object({
  permissions: PermissionsSchema.optional(),
  hooks: HooksSchema.optional(),
  sandbox: SandboxSchema.optional(),
  model: z.string().optional(),
  env: z.record(z.string()).optional(),
  // https://wanlanglin.github.io/-awesome-cc-harness/.
}).passthrough();  // 保留未知字段（向后兼容）

// src/utils/settings/settings.ts — 真实代码
// 数组合并策略：连接 + 去重（而非替换）
function settingsMergeCustomizer(objValue, srcValue) {
  if (Array.isArray(objValue) && Array.isArray(srcValue)) {
    return mergeArrays(objValue, srcValue)  // concat + uniq
  }
  // 非数组：标量覆盖，对象递归合并
}

// 类似 systemd 的 drop-in 目录模式：
// managed-settings.json        ← 基础（最低优先级）
// managed-settings.d/
//   10-otel.json               ← 可观测性团队的配置
//   20-security.json           ← 安全团队的配置
//   30-compliance.json         ← 合规团队的配置
// 按字母序排序合并，后者覆盖前者

// 真实代码：缓存读取时返回克隆副本
// 原因：lodash 的 mergeWith() 会修改第一个参数
// 如果直接返回缓存对象，调用者的合并操作会污染缓存
// 下一个读取者会看到被修改的数据——一个极难调试的 bug
const cached = getCachedParsedFile(path)
return cached ? structuredClone(cached) : loadAndCache(path)

// src/services/mcp/client.ts — 六种传输类型
type MCPTransport =
  | StdioClientTransport       // 子进程（stdin/stdout）
  | SSEClientTransport         // Server-Sent Events
  | StreamableHTTPTransport    // HTTP 流
  | WebSocketTransport         // WebSocket（支持 TLS/代理）
  | InProcessTransport         // 内存（TypeScript 模块）
  | SdkControlTransport;       // SDK daemon 控制

// ~/.claude/mcp.json（全局）
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_https://wanlanglin.github.io/-awesome-cc-harness/." }
    }
  }
}

// .claude/mcp.json（项目级，与 mcp.json 合并）
{
  "mcpServers": {
    "database": {
      "command": "python",
      "args": ["mcp_db_server.py"],
      "env": { "DB_URL": "postgresql://https://wanlanglin.github.io/-awesome-cc-harness/." }
    }
  }
}

// MCP 工具执行流程
async function callMcpTool(
  server: MCPClient,
  toolName: string,
  input: object,
): Promise<ToolResult> {
  // 1. 调用 MCP 服务器
  const result = await server.callTool(toolName, input);

  // 2. 处理流式进度
  if (result.isStreaming) {
    for await (const progress of result.stream) {
      yield progress;
    }
  }

  // 3. 结果截断和验证
  const truncated = truncateIfNeeded(result);

  // 4. OAuth token 刷新（如需要）
  if (result.error?.type === 'auth_error') {
    await refreshOAuthToken(server);
    return callMcpTool(server, toolName, input);  // 重试
  }

  // 5. 二进制内容持久化（大输出）
  if (isBinaryContent(result)) {
    await persistBinaryContent(result);
  }

  return truncated;
}

// src/services/mcp/client.ts — 真实的连接编排
// getMcpToolsCommandsAndResources() 的核心逻辑：

// 1. 按传输类型分区，不同并发度
//    本地服务器（stdio）: 低并发（batch ~3），避免进程生成争用
//    远程服务器（sse/http/ws）: 高并发（batch ~20），仅网络连接

// 2. 三级过滤
//    Level 1: 禁用检查（settings 中标记为 disabled）
//    Level 2: 认证缓存检查（15 分钟 TTL 的失败缓存）
//    Level 3: 实际连接尝试（memoized by name + config hash）

// 3. 流式结果回调（不等所有服务器连接完毕）
//    每个服务器连接完成后立即回调 onConnectionAttempt()
//    UI 可以增量渲染已连接的服务器

配置来源优先级：
  手动配置 > 插件自动发现 > Claude.ai 浏览器连接器

去重规则（"同一个服务器"的判定）：
  stdio 服务器：command 数组完全相同
  remote 服务器：URL 完全相同
  名称冲突：后者覆盖前者

企业策略：
  allowlist + denylist 三种匹配模式：
    名称匹配：精确服务器名
    命令匹配：stdio 服务器的 command 数组
    URL 匹配：通配符模式（https://*/api/* → 正则）
  denylist 从所有来源合并（永远生效）
  allowlist 受 shouldAllowManagedMcpServersOnly() 策略控制

// MCP 工具与内置工具共享同一个工具池
// assembleToolPool() 将两者合并

// 去重规则: 内置工具优先
// 如果 MCP 服务器提供了同名工具，内置版本被保留

// Deny 规则同样适用于 MCP 工具
// 可以在 settings.json 中:
{
  "permissions": {
    "deny": ["mcp__untrusted-server"]  // 禁止整个 MCP 服务器
  },
  "allowedMcpServers": ["@official/*"],
  "deniedMcpServers": ["*-untrusted"]
}

// 可选特性: MCP_SKILLS
// 从 MCP 服务器发现并注册 Skills
// skills/mcpSkills.ts

// MCP 服务器可以暴露 Skills（不仅是 Tools）
// Skills 是更高级的工作流抽象
// 通过 skills builder 模式注册

// Agent 定义结构
interface AgentDefinition {
  agentType: string;           // 例: "Explore", "Plan", "general-purpose"
  description: string;         // 用途描述
  whenToUse: string;           // 何时使用
  tools: string[] | '*';       // 可用工具（'*' = 所有）
  maxTurns?: number;           // 最大轮次限制
  model?: string | 'inherit';  // 模型选择
  permissionMode?: PermissionMode;  // 权限模式
  getSystemPrompt(): string;   // 系统提示生成
}

┌──────────────────────────────────────────────────┐
│                Agent Types                        │
│                                                   │
│  general-purpose（通用 Agent）                     │
│  ├─ 工具: 所有（*)                                │
│  ├─ 用例: 复杂多步骤任务                          │
│  └─ 模型: 继承父级                                │
│                                                   │
│  Explore（探索 Agent）                             │
│  ├─ 工具: 只读（Read, Glob, Grep, WebFetch, https://wanlanglin.github.io/-awesome-cc-harness/.）│
│  ├─ 用例: 代码库探索、搜索                        │
│  ├─ 不能: 编辑、写入、运行命令                    │
│  └─ 三种深度: quick, medium, very thorough        │
│                                                   │
│  Plan（规划 Agent）                                │
│  ├─ 工具: 只读 + Plan 文件写入                    │
│  ├─ 用例: 设计实现方案                            │
│  └─ 不能: 执行实际代码修改                        │
│                                                   │
│  custom（自定义 Agent）                            │
│  ├─ 定义: ~/.claude/agents/<name>.md              │
│  ├─ Frontmatter: tools, model, maxTurns           │
│  └─ 系统提示: Markdown 正文                       │
│                                                   │
│  Fork（隐式分叉 Agent）                            │
│  ├─ 实验性功能                                    │
│  ├─ 从父级上下文自动分叉                          │
│  └─ 继承父级的工具和权限                          │
│                                                   │
└──────────────────────────────────────────────────┘

父 Agent 请求: Agent(type: "Explore", prompt: "https://wanlanglin.github.io/-awesome-cc-harness/.")
    │
    v
AgentTool.call()
    │
    ├─ 1. 加载 Agent 定义（内置或自定义）
    ├─ 2. 构建隔离的消息数组（messages = []）
    ├─ 3. 选择工具集（定义中指定或继承）
    ├─ 4. 设置权限模式（bubble / default / 继承）
    ├─ 5. 启动独立的查询循环
    │     └─ 子 Agent 有自己的:
    │        ├─ 消息历史
    │        ├─ 工具上下文
    │        ├─ 压缩管道
    │        └─ Token 预算
    ├─ 6. 收集输出
    └─ 7. 返回摘要给父 Agent

<!-- ~/.claude/agents/code-reviewer.md -->
---
name: code-reviewer
description: Specialized agent for code review
tools: [Read, Grep, Glob]
model: claude-sonnet-4-6
maxTurns: 50
---

You are a code reviewer. Your job is to:
1. Read the changed files
2. Check for bugs, security issues, and style violations
3. Provide actionable feedback

You are READ-ONLY. You cannot modify any files.

Focus on:
- Security vulnerabilities (injection, XSS, etc.)
- Performance issues (N+1 queries, memory leaks)
- Code quality (naming, SRP, test coverage)

┌─────────────────────────────────────────────┐
│            Coordinator System                │
│                                              │
│  src/coordinator/                            │
│  ├─ 多 Agent 编排                            │
│  ├─ 团队创建/删除                            │
│  ├─ 任务分配                                 │
│  └─ 状态同步                                 │
│                                              │
│  utils/swarm/                                │
│  ├─ 协调逻辑                                 │
│  ├─ 队友工具                                 │
│  └─ 通信协议                                 │
│                                              │
│  工具:                                       │
│  ├─ TeamCreateTool  — 创建团队 Agent         │
│  ├─ TeamDeleteTool  — 删除团队 Agent         │
│  ├─ SendMessageTool — Agent 间消息传递       │
│  └─ TaskStopTool    — 停止任务               │
│                                              │
│  服务:                                       │
│  ├─ teamMemorySync/ — 多 Agent 记忆同步      │
│  ├─ AgentSummary/   — Agent 状态摘要         │
│  └─ swarm/          — Swarm 权限轮询         │
│                                              │
└─────────────────────────────────────────────┘

// src/Task.ts — 任务类型
type TaskType =
  | 'local_bash'          // Bash 命令执行
  | 'local_agent'         // 本地 Agent
  | 'remote_agent'        // 远程 Agent（CCR）
  | 'in_process_teammate' // 进程内队友（assistant 模式）
  | 'local_workflow'      // 工作流脚本
  | 'monitor_mcp'         // MCP 监控
  | 'dream';              // Dream 模式任务

interface TaskState {
  id: string;             // 前缀 + 8 位随机字符（base36）
  type: TaskType;
  status: 'pending' | 'running' | 'completed' | 'failed' | 'killed';
  description: string;
  toolUseId?: string;
  startTime: number;
  endTime?: number;
  totalPausedMs: number;
  outputFile: string;     // 磁盘上的输出文件
  outputOffset: number;
  notified: boolean;
}

Git Worktree 隔离模式:
├─ 每个子 Agent 在独立的 git worktree 中工作
├─ 防止文件冲突（多个 Agent 同时编辑同一文件）
├─ 工具: EnterWorktreeTool / ExitWorktreeTool
├─ 完成后:
│   ├─ 如果有变更: 保留 worktree，返回路径和分支
│   └─ 如果无变更: 自动清理 worktree
└─ 与沙盒集成: worktree 路径加入 sandbox allowWrite

// src/skills/bundled/index.ts
function initBundledSkills(): void {
  registerUpdateConfigSkill();   // /update-config
  registerKeybindingsSkill();    // /keybindings-help
  registerDebugSkill();          // /debug
  registerSimplifySkill();       // /simplify
  registerBatchSkill();          // /batch

  // 特性门控 Skills
  if (feature('AGENT_TRIGGERS_REMOTE')) {
    registerScheduleSkill();     // /schedule
  }
  if (feature('AGENT_TRIGGERS')) {
    registerLoopSkill();         // /loop
  }
  if (feature('BUILDING_CLAUDE_APPS')) {
    registerClaudeApiSkill();    // /claude-api
  }
}

<!-- ~/.claude/skills/my-deploy.md -->
---
name: deploy
description: Deploy the application to staging
args: environment
---

# Deploy Skill

When invoked with /deploy <environment>:

1. Run the test suite: `npm test`
2. Build the application: `npm run build`
3. Deploy to the specified environment:
   - staging: `aws deploy --env staging`
   - production: `aws deploy --env production` (requires confirmation)
4. Verify deployment health check
5. Report results

// src/skills/loadSkillsDir.ts
function loadSkillsDir(dir: string): SkillDefinition[] {
  // 1. 扫描 ~/.claude/skills/ 目录
  // 2. 读取每个 .md 文件
  // 3. 解析 frontmatter（name, description, args）
  // 4. 创建 SkillDefinition
  // 5. 注册为可用命令
}

// src/skills/loadSkillsDir.ts — Skill 前置数据解析
// 25+ 个 frontmatter 字段：

// 身份: name, description, version, when_to_use
// 执行: model, disable-model-invocation, user-invocable, context('fork')
// 工具: allowed-tools, disallowed-tools
// 参数: arguments (数组/逗号分隔), argument-hint
// Hooks: 通过 HooksSchema() 验证
// 路径: parseSkillPaths() (与 CLAUDE.md 规则相同格式)

// 两种目录格式：
// 新格式: /skills/skill-name/SKILL.md (每个 skill 一个目录)
// 旧格式: /commands/namespace/file.md (扁平 markdown)
// 旧格式的命名空间: /commands/auth/login/SKILL.md → "auth:login"

// 安全限制：
// MCP skills (远程/不可信) 禁止执行内联 Shell 命令
// 本地 skills 可以用 `!command` 语法执行 Shell

始终加载 (11 个):
  updateConfig, keybindings, verify, debug, loremIpsum,
  skillify, remember, simplify, batch, stuck

特性门控 (7 个):
  dream         ← KAIROS/KAIROS_DREAM (后台记忆整合)
  hunter        ← REVIEW_ARTIFACT
  loop          ← AGENT_TRIGGERS (循环执行)
  schedule      ← AGENT_TRIGGERS_REMOTE (远程调度)
  claudeApi     ← BUILDING_CLAUDE_APPS
  claudeInChrome← 自动检测
  skillGenerator← RUN_SKILL_GENERATOR

src/plugins/          — 插件系统核心
src/services/plugins/ — 插件加载、版本管理、市场
src/utils/plugins/    — 插件工具、缓存

Plugin 特性:
├─ 版本管理（SemVer）
├─ 缓存系统（减少重复加载）
├─ Marketplace 集成
├─ 插件级 Hook 注入
├─ 独立数据目录（${CLAUDE_PLUGIN_DATA}）
└─ 配置隔离（${user_config.X}）

# CLAUDE.md

## 项目架构
- src/: 源代码
- tests/: 测试文件
- docs/: 文档

## 开发规范
- 语言: TypeScript strict mode
- 测试: vitest
- 格式化: prettier
- 提交: conventional commits

## 重要约束
- 不要修改 migrations/ 目录（已部署的迁移不可变）
- 所有 API 端点必须有认证中间件
- 不要使用 any 类型

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm test *)",
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "deny": [
      "Bash(sudo *)",
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)"
    ]
  }
}

// .claude/settings.json（hooks 部分）
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Writing file: '$(echo $HOOK_INPUT | jq -r '.tool_input.file_path')",
            "if": "Write(*.ts)"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --quiet 2>/dev/null || true",
            "if": "Bash(npm *)",
            "async": true
          }
        ]
      }
    ]
  }
}

// .claude/settings.json（提交到 git）
{
  "permissions": {
    "allow": [
      "Bash(npm test *)",
      "Bash(npm run lint *)",
      "Bash(git *)"
    ],
    "deny": [
      "Bash(sudo *)",
      "Bash(rm -rf /)",
      "Bash(npm publish *)",
      "Write(*.env*)",
      "Write(*.key)",
      "Write(*.pem)"
    ],
    "defaultMode": "default"
  },
  "sandbox": {
    "enabled": true,
    "fsWrite": {
      "deny": [".env", ".env.*", "*.key", "*.pem", "secrets/"]
    },
    "network": {
      "allowedDomains": [
        "*.github.com",
        "registry.npmjs.org",
        "api.anthropic.com"
      ]
    }
  }
}

<!-- .claude/agents/architect.md -->
---
name: architect
description: Reviews architecture decisions and suggests improvements
tools: [Read, Grep, Glob]
model: claude-opus-4-6
maxTurns: 30
---

You are an architecture reviewer. Analyze the codebase and provide:
1. Dependency analysis
2. Coupling/cohesion assessment
3. SOLID principle compliance
4. Suggestions for improvement

Focus on high-level design, not line-by-line code review.

<!-- .claude/agents/test-writer.md -->
---
name: test-writer
description: Writes comprehensive tests for existing code
tools: [Read, Write, Edit, Bash, Glob, Grep]
model: claude-sonnet-4-6
maxTurns: 100
---

You are a test engineer. For any given code:
1. Analyze the code and identify test cases
2. Write comprehensive tests (unit + integration)
3. Run the tests to verify they pass
4. Ensure >80% coverage for touched files

// .claude/mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    }
  }
}

<!-- .claude/skills/review-pr.md -->
---
name: review-pr
description: Comprehensive PR review workflow
args: pr_number
---

# PR Review Workflow

1. Fetch the PR diff: `gh pr diff $ARGUMENTS`
2. Read all changed files
3. For each file:
   - Check for security issues
   - Check for performance concerns
   - Check for test coverage
   - Check for style consistency
4. Generate a structured review comment
5. Post the review: `gh pr review $ARGUMENTS --comment --body "https://wanlanglin.github.io/-awesome-cc-harness/."`

// /managed/managed-settings.json
{
  "permissions": {
    "deny": [
      "Bash(sudo *)",
      "Bash(curl * | bash)",
      "Bash(wget * | bash)",
      "Write(*.env*)",
      "Write(*.pem)",
      "Write(*.key)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "sandbox": {
    "enabled": true,
    "lockedByPolicy": true,
    "network": {
      "deniedDomains": ["*.malware.com", "*.phishing.net"]
    }
  },
  "deniedMcpServers": ["*-untrusted", "*-experimental"]
}

// /managed/managed-settings.d/audit.json
{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://audit.company.com/api/agent-actions",
            "headers": {
              "Authorization": "Bearer $AUDIT_API_KEY",
              "Content-Type": "application/json"
            },
            "allowedEnvVars": ["AUDIT_API_KEY"],
            "async": true
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"session_started\": true}' | curl -s -X POST -d @- https://audit.company.com/api/sessions",
            "async": true
          }
        ]
      }
    ]
  }
}

R01: 阻止 sudo 命令
R02: 禁止写入 .git/, .env, SSH 密钥
R03: 禁止 Shell 写入受保护文件
R04: 写入项目根目录外需要确认
R05: rm -rf 需要确认
R06: 禁止 git push --force
R07-R09: 模式特定防护（work/codex/breezing）
R10: 禁止 --no-verify, --no-gpg-sign
R11: 禁止 git reset --hard main/master
R12: 警告直接推送到 main/master
R13: 警告编辑受保护文件

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node guard-rules.js",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

不是: function query() → Promise<FinalResult>
而是: async function* query() → AsyncGenerator<StreamEvent>

为什么: 客户端可以在模型思考时就开始渲染
         用户可以随时中断
         进度对用户可见

不是: 显式状态枚举 + switch/case
而是: while(true) + 7 个 continue 站点

为什么: 恢复路径是自然的（continue = 重试）
         状态转换是局部的（只需更新 State 对象）
         新恢复路径可以添加而不重构

不是: if (config.feature_x) { https://wanlanglin.github.io/-awesome-cc-harness/. }
而是: if (feature('FEATURE_X')) { https://wanlanglin.github.io/-awesome-cc-harness/. }  // bun:bundle 编译时求值

为什么: 外部发行版不包含任何内部特性代码（连字符串都没有）
         不存在运行时分支预测开销
         代码大小最小化

不是: 将内置工具和 MCP 工具混合排序
而是: 内置工具排序后作为稳定前缀，MCP 工具排序后追加

为什么: Anthropic API 的 prompt cache 基于前缀匹配
         MCP 工具变化时，内置工具前缀不变 → 缓存不失效
         大幅降低 API 成本

Layer 1: CLAUDE.md（指导性约束）
Layer 2: Permission Rules（声明性约束）
Layer 3: Hooks（可编程约束）
Layer 4: YOLO Classifier（AI 约束）
Layer 5: Sandbox（系统级约束）
Layer 6: Hardcoded Denials（不可覆盖约束）

为什么: 每一层都可能被绕过
         多层叠加使绕过概率指数下降
         最内层（硬编码）无法通过配置禁用

不是: 修改源码添加新功能
而是: settings.json + agents/*.md + skills/*.md + hooks

为什么: 非工程师也能定制 Harness
         定制与核心代码解耦
         升级时不丢失定制

设计: 工具延迟加载、记忆按需附加、四级压缩管道
       ToolSearch 发现机制、Microcompact 老化策略

为什么: 上下文窗口有限（即使 1M token）
         无关信息降低模型性能
         成本与 token 使用量成正比

7 级设置: CLI > Flag > Policy > Managed > Local > Project > User

为什么: 不同层级有不同的信任级别
         企业管理员可以强制策略
         项目维护者可以设定合理默认
         用户可以个人微调

设计: 子 Agent 从空白消息列表开始
       完成后只返回摘要
       父级上下文不被污染

为什么: 探索性任务可能产生大量噪音
         子 Agent 的失败不应影响父级
         Token 预算隔离

设计: 文件编辑通过 Edit（替换字符串），不是 Write（覆盖）
       每个工具调用有 undo 能力
       自动快照（文件历史）

为什么: Agent 会犯错
         用户需要轻松回滚
         "先行动后审查"比"先审查后行动"更高效

┌──────────────────────────────────────────────┐
│         Entropy Management Patterns           │
│                                               │
│  1. 定期清理 Agent                            │
│     /loop 1h "检查死代码、未使用导入、        │
│                过期 TODO、不一致的命名"         │
│                                               │
│  2. 文档验证 Agent                            │
│     SessionEnd Hook → 检查 CLAUDE.md          │
│     是否与代码实际状态一致                     │
│                                               │
│  3. 依赖审计 Agent                            │
│     /schedule "每周一 0:00" →                  │
│     "检查过期依赖、安全漏洞、许可证合规"       │
│                                               │
│  4. 测试覆盖率守卫                            │
│     PostToolUse Hook（Write *.ts）→            │
│     "运行覆盖率检查，如果下降则警告"           │
│                                               │
└──────────────────────────────────────────────┘

src/bridge/
├── bridgeMain.ts             — 主循环
├── bridgeMessaging.ts        — 消息协议
├── bridgePermissionCallbacks.ts — 权限处理
├── replBridge.ts             — REPL 桥接
├── jwtUtils.ts               — JWT 认证
└── sessionRunner.ts          — 会话执行

支持:
├── VS Code 扩展
├── JetBrains 扩展
├── 双向通信（IDE ↔ Claude Code）
├── 权限同步
└── 会话状态同步

5 阶段工作流:

Phase 1: Interview（访谈）
├─ 收集需求
├─ 理解上下文
└─ 最多启动 3 个 Explore Agent（并行）

Phase 2: Design（设计）
├─ 启动 Plan Agent
├─ 生成实现方案
└─ 可启动多个以探索不同方向

Phase 3: Review（审查）
├─ 读取关键文件验证方案
├─ 确保与用户意图一致
└─ 通过 AskUserQuestion 澄清

Phase 4: Final Plan（最终计划）
├─ 写入 ~/.claude/plans/<name>.md
├─ 包含上下文、步骤、文件路径
└─ 验证部分描述如何测试

Phase 5: Exit Plan Mode
├─ 调用 ExitPlanMode
├─ 等待用户批准
└─ 批准后开始执行

// 特性门控: AGENT_TRIGGERS + AGENT_TRIGGERS_REMOTE

// ScheduleCronTool — 创建定时 Agent
{
  schedule: "0 9 * * MON",   // 每周一早 9 点
  prompt: "Review open PRs and post summary to Slack",
  model: "claude-sonnet-4-6",
}

// RemoteTriggerTool — 远程触发
{
  trigger: "deploy-check",
  prompt: "Verify deployment health",
}

src/voice/                   — 语音输入
src/services/voice.ts        — 语音/STT 集成
src/services/voiceStreamSTT.ts — 流式语音转文字

特性门控: VOICE_MODE
支持:
├── 语音输入转文字
├── 流式处理（边说边识别）
└── 集成到主查询循环

核心理念: Harness 应该能随模型能力提升而简化

示例:
├── 今天: 需要 13 条防护规则阻止危险操作
│   └── 未来更好的模型可能不需要其中一半
│
├── 今天: 四级压缩管道应对有限上下文
│   └── 未来更大的上下文窗口可能只需要一级
│
├── 今天: YOLO 分类器需要两阶段检查
│   └── 未来主模型可能自带更好的安全意识
│
└── 设计启示:
    ├── 每个 Harness 组件应该可以独立禁用
    ├── 设置覆盖优于硬编码
    ├── 随着模型改进，简化而非堆叠
    └── "最好的 Harness 是你最终不需要的那个"

// src/Tool.ts — 真实代码（精简注释版）
export type ToolUseContext = {
  // ===== 配置（只读）=====
  options: {
    commands: Command[]           // 可用的 Slash 命令
    debug: boolean                // 调试模式
    mainLoopModel: string         // 主循环使用的模型
    tools: Tools                  // 可用工具列表
    verbose: boolean              // 详细输出
    thinkingConfig: ThinkingConfig// 思考模式配置
    mcpClients: MCPServerConnection[]  // MCP 服务器连接
    mcpResources: Record<string, ServerResource[]>  // MCP 资源
    isNonInteractiveSession: boolean   // 非交互式会话
    agentDefinitions: AgentDefinitionsResult  // Agent 定义
    maxBudgetUsd?: number         // 最大预算（美元）
    customSystemPrompt?: string   // 自定义系统提示
    appendSystemPrompt?: string   // 追加系统提示
    querySource?: QuerySource     // 查询来源标识
    refreshTools?: () => Tools    // 工具列表刷新函数
  }

  // ===== 控制 =====
  abortController: AbortController  // 取消信号
  messages: Message[]               // 当前消息历史

  // ===== 状态读写 =====
  readFileState: FileStateCache     // 文件状态缓存
  getAppState(): AppState           // 获取应用状态
  setAppState(f: (prev) => AppState): void  // 更新应用状态

  // ===== 回调 =====
  setToolJSX?: SetToolJSXFn         // 设置工具 UI
  addNotification?: (n: Notification) => void  // 添加通知
  sendOSNotification?: (opts) => void          // 发送系统通知
  setInProgressToolUseIDs: (f) => void         // 跟踪进行中的工具
  setResponseLength: (f) => void               // 跟踪响应长度
  updateFileHistoryState: (updater) => void    // 更新文件历史
  updateAttributionState: (updater) => void    // 更新归因状态

  // ===== Agent 相关 =====
  agentId?: AgentId                 // Agent 标识
  agentType?: string                // Agent 类型
  requireCanUseTool?: boolean       // 是否需要权限检查

  // ===== 动态 Skill/Memory =====
  nestedMemoryAttachmentTriggers?: Set<string>  // 嵌套记忆触发器
  loadedNestedMemoryPaths?: Set<string>         // 已加载的记忆路径
  dynamicSkillDirTriggers?: Set<string>         // 动态 Skill 目录触发器
  discoveredSkillNames?: Set<string>            // 已发现的 Skill 名称

  // ===== 权限 =====
  localDenialTracking?: DenialTrackingState     // 本地拒绝跟踪
  toolDecisions?: Map<string, {https://wanlanglin.github.io/-awesome-cc-harness/.}>            // 工具决策记录
  contentReplacementState?: ContentReplacementState  // 内容替换状态

  // ===== 高级 =====
  requestPrompt?: (sourceName, summary?) =>     // Hook prompt 请求
    (request: PromptRequest) => Promise<PromptResponse>
  handleElicitation?: (serverName, params, signal) =>  // MCP elicitation
    Promise<ElicitResult>
  onCompactProgress?: (event) => void           // 压缩进度回调
  criticalSystemReminder_EXPERIMENTAL?: string  // 关键系统提醒
}

// 来自 claude-code-harness/core/src/guardrails/

// R01: 阻止 sudo — 永远不允许提权
{ rule: 'R01', test: (input) => /^sudo\s/.test(input.command),
  action: 'deny', reason: 'sudo commands are not allowed' }

// R02: 禁止写入敏感路径
{ rule: 'R02', test: (input) => SENSITIVE_PATHS.some(p => input.file_path?.startsWith(p)),
  action: 'deny', paths: ['.git/', '.env', '~/.ssh/'] }

// R03: 禁止 Shell 写入受保护文件
{ rule: 'R03', test: (input) => isShellWriteToProtectedFile(input),
  action: 'deny' }

// R04: 项目根目录外写入需确认
{ rule: 'R04', test: (input) => !isWithinProjectRoot(input.file_path),
  action: 'ask', reason: 'Writing outside project root' }

// R05: rm -rf 需确认
{ rule: 'R05', test: (input) => /rm\s+(-rf|-r\s+-f|-f\s+-r)/.test(input.command),
  action: 'ask', reason: 'Recursive delete detected' }

// R06: 禁止 force push
{ rule: 'R06', test: (input) => /git\s+push\s+.*--force/.test(input.command),
  action: 'deny', reason: 'Force push is not allowed' }

// R07-R09: 模式特定防护
{ rule: 'R07', mode: 'work', https://wanlanglin.github.io/-awesome-cc-harness/. }   // Work 模式限制
{ rule: 'R08', mode: 'codex', https://wanlanglin.github.io/-awesome-cc-harness/. }  // Codex 集成限制
{ rule: 'R09', mode: 'breezing', https://wanlanglin.github.io/-awesome-cc-harness/. } // Breezing 模式限制

// R10: 禁止跳过安全钩子
{ rule: 'R10', test: (input) => /--no-verify|--no-gpg-sign/.test(input.command),
  action: 'deny', reason: 'Skipping safety hooks is not allowed' }

// R11: 禁止 hard reset 到 main
{ rule: 'R11', test: (input) => /git\s+reset\s+--hard\s+(main|master)/.test(input.command),
  action: 'deny' }

// R12: 警告直接推送到 main
{ rule: 'R12', test: (input) => isDirectPushToMain(input),
  action: 'warn' }

// R13: 警告编辑受保护文件
{ rule: 'R13', test: (input) => PROTECTED_FILES.includes(input.file_path),
  action: 'warn', files: ['package-lock.json', 'yarn.lock', 'Cargo.lock'] }

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "node guard-rules.js",
          "if": "Bash(sudo *)"
        }]
      }
    ]
  }
}

#!/usr/bin/env python3
"""mini_harness.py — 一个 200 行的 Claude Code 式 Agent Harness"""
import anthropic, json, os, subprocess, re
from pathlib import Path

client = anthropic.Anthropic()
MODEL = "claude-sonnet-4-6"

# ====================================================
# Layer 1: Tool System (对应 Claude Code 的 src/Tool.ts)
# ====================================================
TOOLS = [
    {
        "name": "bash",
        "description": "Run a shell command. Returns stdout and exit code.",
        "input_schema": {
            "type": "object",
            "properties": {
                "command": {"type": "string", "description": "The command to run"}
            },
            "required": ["command"]
        }
    },
    {
        "name": "read_file",
        "description": "Read a file and return its contents.",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "File path to read"}
            },
            "required": ["path"]
        }
    },
    {
        "name": "write_file",
        "description": "Write content to a file.",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "File path to write"},
                "content": {"type": "string", "description": "Content to write"}
            },
            "required": ["path", "content"]
        }
    }
]

# ====================================================
# Layer 2: Permission Rules (对应 Claude Code 的 permissions.ts)
# ====================================================
DENY_PATTERNS = [
    r"^sudo\s",           # R01: 禁止 sudo
    r"rm\s+-rf\s+/",      # R05: 禁止 rm -rf /
    r"git\s+push\s+--force", # R06: 禁止 force push
]

ALLOW_TOOLS = {"read_file"}  # 只读工具始终允许

def check_permission(tool_name: str, tool_input: dict) -> tuple[bool, str]:
    """Layer 2: 权限检查 (简化版 hasPermissionsToUseTool)"""
    if tool_name in ALLOW_TOOLS:
        return True, "allowed by rule"

    if tool_name == "bash":
        cmd = tool_input.get("command", "")
        for pattern in DENY_PATTERNS:
            if re.search(pattern, cmd):
                return False, f"denied: matches {pattern}"

    # 默认：询问用户（对应 Claude Code 的 'ask' 模式）
    answer = input(f"  Allow {tool_name}({json.dumps(tool_input)[:80]})? [y/n] ")
    return answer.lower() == 'y', "user decision"

# ====================================================
# Layer 3: Tool Execution (对应 Claude Code 的 toolExecution.ts)
# ====================================================
def execute_tool(tool_name: str, tool_input: dict) -> str:
    """Layer 3: 执行工具"""
    if tool_name == "bash":
        result = subprocess.run(
            tool_input["command"], shell=True,
            capture_output=True, text=True, timeout=30
        )
        return f"exit_code={result.returncode}\n{result.stdout}{result.stderr}"
    elif tool_name == "read_file":
        return Path(tool_input["path"]).read_text()
    elif tool_name == "write_file":
        Path(tool_input["path"]).write_text(tool_input["content"])
        return f"Written to {tool_input['path']}"
    return "Unknown tool"

# ====================================================
# Layer 4: Context Engineering (对应 Claude Code 的 CLAUDE.md)
# ====================================================
def load_context() -> str:
    """Layer 4: 加载 CLAUDE.md 上下文"""
    claude_md = Path("CLAUDE.md")
    if claude_md.exists():
        return f"\n<project_context>\n{claude_md.read_text()}\n</project_context>\n"
    return ""

SYSTEM_PROMPT = f"""You are a coding assistant. Use tools to help the user.
Be concise. Don't explain what you're about to do — just do it.
{load_context()}"""

# ====================================================
# Layer 5: Agent Loop (对应 Claude Code 的 query.ts)
# ====================================================
def agent_loop():
    """Layer 5: 核心 Agent 循环"""
    messages = []
    print("Mini Harness (type 'exit' to quit)")

    while True:
        user_input = input("\n> ")
        if user_input.lower() == 'exit':
            break

        messages.append({"role": "user", "content": user_input})

        # 内循环：工具调用链（对应 queryLoop 的 while(true)）
        while True:
            response = client.messages.create(
                model=MODEL, max_tokens=4096,
                system=SYSTEM_PROMPT,
                messages=messages, tools=TOOLS,
            )

            # 收集助手消息
            messages.append({"role": "assistant", "content": response.content})

            # 无工具调用 → 打印文本并退出内循环
            if response.stop_reason != "tool_use":
                for block in response.content:
                    if hasattr(block, 'text'):
                        print(f"\n{block.text}")
                break

            # 执行工具调用
            tool_results = []
            for block in response.content:
                if block.type != "tool_use":
                    continue

                # 权限检查（Layer 2）
                allowed, reason = check_permission(block.name, block.input)
                if not allowed:
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": f"Permission denied: {reason}",
                        "is_error": True,
                    })
                    print(f"  ✗ {block.name} denied: {reason}")
                    continue

                # 执行工具（Layer 3）
                try:
                    result = execute_tool(block.name, block.input)
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": result,
                    })
                    print(f"  ✓ {block.name} completed")
                except Exception as e:
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": f"Error: {e}",
                        "is_error": True,
                    })

            messages.append({"role": "user", "content": tool_results})

if __name__ == "__main__":
    agent_loop()

# 1. 设置 API key
export ANTHROPIC_API_KEY="sk-ant-https://wanlanglin.github.io/-awesome-cc-harness/."

# 2. 创建一个 CLAUDE.md
echo "# Project Rules
- Use TypeScript for all new files
- Run tests after making changes: npm test" > CLAUDE.md

# 3. 运行
python mini_harness.py

# 4. 测试权限系统
> run sudo rm -rf /
  ✗ bash denied: matches ^sudo\s

> read the file package.json
  ✓ read_file completed  (自动允许，无需确认)

> run npm test
  Allow bash({"command": "npm test"})? [y/n] y
  ✓ bash completed

第 1 周: 基础
├── 阅读本教程第 1-3 章
├── 搭建 Level 1 个人 Harness（CLAUDE.md + 基本权限）
├── 动手实验: 在自己的项目中使用 Claude Code
└── 理解: Agent Loop, Tool Dispatch, 计划模式

第 2 周: 约束与安全
├── 阅读本教程第 4-7 章
├── 配置 Permission Rules
├── 编写 PreToolUse Hook
└── 理解: Permission Model, Hooks, Sandbox

第 3 周: 上下文与记忆
├── 阅读本教程第 8-9 章
├── 优化 CLAUDE.md
├── 配置 Settings 层级
├── 动手实验: 写一个 PreToolUse Hook
└── 理解: Context Engineering, Memory, Compaction

第 4 周: 扩展与协作
├── 阅读本教程第 10-12 章
├── 配置 MCP 服务器（从 GitHub MCP 开始）
├── 创建自定义 Agent 和 Skill
└── 理解: MCP, Sub-Agents, Skills

第 5 周: 多 Agent 与生产化
├── 阅读本教程第 13-14 章
├── 搭建团队 Harness
├── 实现 Plan→Work→Review 循环
└── 理解: Team Protocols, Worktree Isolation, Entropy Management

第 6 周+: 高级
├── 深入研究 Claude Code 源码（从 query.ts 开始）
├── 构建组织级 Harness
└── 探索: Bridge, Voice, Remote Triggers