/**
 * Enter Plan Mode Tool
 *
 * 进入计划模式的工具。
 * 参考 Claude Code 的 EnterPlanMode 实现。
 *
 * 在开始非平凡的实现任务前主动使用，让用户在编写代码之前先批准方案。
 *
 * 使用场景：
 * - 新功能实现
 * - 多种可行方案需要选择
 * - 代码修改影响范围较大
 * - 架构决策
 * - 多文件变更
 * - 需求不明确需要探索
 *
 * 不适用场景：
 * - 单行修复（错别字、明显 bug）
 * - 用户给出了非常具体详细的指令
 * - 纯研究/探索任务
 */

import type { ToolWithMetadata } from '../types.js';
import type { ToolResult } from '../../types/index.js';

/**
 * Enter Plan Mode 工具
 */
export const enterPlanModeTool: ToolWithMetadata = {
  name: 'enter_plan_mode',
  description: `进入计划模式，在开始非平凡的实现任务前主动使用。

使用场景：
- 新功能实现：如 "添加登出按钮"、"实现用户认证"
- 多种可行方案：如 "给 API 添加缓存"（Redis/内存/文件）
- 代码修改：如 "更新登录流程"、"重构组件"
- 架构决策：如 "添加实时更新功能"（WebSocket/SSE/轮询）
- 多文件变更：如 "重构认证系统"
- 需求不明确：如 "让应用更快"、"修复 checkout 的 bug"

何时不使用：
- 单行修复（错别字、明显 bug、小调整）
- 用户给出了非常具体详细的指令
- 纯研究/探索任务（使用 Task 工具的 explore agent）

计划模式中的限制：
进入后只能使用只读工具：
✅ read_file, list_directory, search_files, grep
✅ web_search, web_extract
✅ task（探索代理）
✅ ask_user_question
❌ write_file, edit_file, bash（执行命令）

完成计划后使用 exit_plan_mode 退出并提交方案供用户审批。`,

  metadata: {
    name: 'enter_plan_mode',
    category: 'agent',
    description: '进入计划模式，用于规划实现方案',
    keywords: ['plan', 'mode', 'enter', '计划', '模式', '规划', '方案'],
    deferLoading: false, // 始终可用
  },

  parameters: {
    // 无参数
  },

  async execute(_params: Record<string, unknown>): Promise<ToolResult> {
    return {
      success: true,
      output: '已进入计划模式。现在可以使用只读工具探索代码库，完成后使用 exit_plan_mode 提交方案。',
      metadata: {
        type: 'enter_plan_mode',
        // 标记模式切换
        modeTransition: {
          from: 'act',
          to: 'plan',
        },
      },
    };
  },
};
