第6章：工具系统与三道静默闸门 —— AgentTool 流水线

// crates/agent/src/thread.rs:5042-5110 核心定义
pub trait AgentTool
where
    Self: 'static + Sized,
{
    /// 输入参数结构体：必须同时满足反序列化、序列化与 JSON Schema 生成
    type Input: for<'de> Deserialize<'de> + Serialize + JsonSchema;

    /// 输出结果结构体：必须能够转化为模型可见的内容块
    type Output: for<'de> Deserialize<'de> + Serialize + Into<LanguageModelToolResultContent>;

    /// 工具在 LLM 视野中的全局唯一名字（如 "edit_file", "terminal"）
    const NAME: &'static str;

    /// 自动从 Input 的 docstring 中提取工具说明
    fn description() -> SharedString {
        let schema = schemars::schema_for!(Self::Input);
        SharedString::new(
            schema.get("description")
                .and_then(|d| d.as_str())
                .unwrap_or_default(),
        )
    }

    /// ACP 协议层定义的工具分类（如 Action / Read / Terminal 等）
    fn kind() -> acp::ToolKind;

    /// 工具在 UI 卡片上初始展示的标题（支持根据尚未解析完成的输入做预渲染）
    fn initial_title(&self, input: Result<Self::Input, serde_json::Value>, cx: &mut App) -> SharedString;

    /// 自动生成标准的 JSON Schema 描述
    fn input_schema() -> Schema {
        language_model::tool_schema::root_schema_for::<Self::Input>()
    }

    /// 是否支持流式输入接收（边生成边解析）
    fn supports_input_streaming() -> bool { false }

    /// 是否与特定 Provider 兼容
    fn supports_provider(_provider: &LanguageModelProviderId) -> bool { true }

    /// 是否允许在受限（不可信）工作区中向模型暴露
    fn allow_in_restricted_mode() -> bool { true }

    /// 工具的核心执行体
    fn run(
        self: Arc<Self>,
        input: ToolInput<Self::Input>,
        event_stream: ToolCallEventStream,
        cx: &mut App,
    ) -> Task<Result<Self::Output, Self::Output>>;

    /// 会话重放时重现历史事件
    fn replay(&self, _input: Self::Input, _output: Self::Output, _event_stream: ToolCallEventStream, _cx: &mut App) -> Result<()> {
        Ok(())
    }

    /// 类型擦除辅助方法
    fn erase(self) -> Arc<dyn AnyAgentTool> {
        Arc::new(Erased(Arc::new(self)))
    }
}

fn run(...) -> Task<Result<Self::Output, Self::Output>>;

// crates/agent/src/tools.rs:142-170
const _: () = {
    const fn str_eq(a: &str, b: &str) -> bool {
        let a = a.as_bytes();
        let b = b.as_bytes();
        if a.len() != b.len() { return false; }
        let mut i = 0;
        while i < a.len() {
            if a[i] != b[i] { return false; }
            i += 1;
        }
        true
    }

    const NAMES: &[&str] = ALL_TOOL_NAMES;
    let mut i = 0;
    while i < NAMES.len() {
        let mut j = i + 1;
        while j < NAMES.len() {
            if str_eq(NAMES[i], NAMES[j]) {
                panic!("Duplicate tool name in tools! macro");
            }
            j += 1;
        }
        i += 1;
    }
};

// crates/agent/src/tools.rs:185-201
// Adding a tool here (and constructing it in `Thread::add_default_tools`) is
// not enough to make the model actually receive it. Three further gates will
// silently drop the tool rather than fail to compile:
//
// 1. `assets/settings/default.json`: the `write` and `ask` agent profiles each
//    carry an explicit `tools` allowlist. `Thread::enabled_tools` filters out
//    any tool not present there with value `true`, so it never reaches the model.
// 2. `test_all_tools_are_in_tool_info_or_excluded` in
//    `crates/settings_ui/src/pages/tool_permissions_setup.rs`: every tool must
//    be in the permission-UI `TOOLS` list (if it calls
//    `decide_permission_from_settings`) or in `EXCLUDED_TOOLS`.
// 3. `tool_feature_flag_enabled`: some tools are gated behind a feature flag and
//    are dropped unless it is active. The agent-profile UI uses the same gate so
//    it never offers a tool the agent can't actually use.

// crates/agent/src/tools.rs:240-252
pub fn tool_feature_flag_enabled(tool_name: &str, cx: &App) -> bool {
    match tool_name {
        RenameTool::NAME => cx.has_flag::<RenameToolFeatureFlag>(),
        FindReferencesTool::NAME
        | GetCodeActionsTool::NAME
        | ApplyCodeActionTool::NAME
        | GoToDefinitionTool::NAME => cx.has_flag::<LspToolFeatureFlag>(),
        CreateThreadTool::NAME | ListAgentsAndModelsTool::NAME => {
            cx.has_flag::<CreateThreadToolFeatureFlag>()
        }
        _ => true,
    }
}

// crates/agent/src/tools.rs:275-290
#[test]
fn fetch_and_terminal_are_forbidden_in_restricted_mode() {
    assert!(!tool_allowed_in_restricted_mode(FetchTool::NAME));
    assert!(!tool_allowed_in_restricted_mode(TerminalTool::NAME));

    // 其它工具允许（如 read_file, edit_file），但网络与命令行被物理切断
    for name in ALL_TOOL_NAMES {
        let expected = *name != FetchTool::NAME && *name != TerminalTool::NAME;
        assert_eq!(tool_allowed_in_restricted_mode(name), expected);
    }
}

# 1. 查看 tools! 宏中注册的 23 个工具全清单
sed -n '205,235p' crates/agent/src/tools.rs

# 2. 验证三道静默闸门的警告注释
sed -n '185,202p' crates/agent/src/tools.rs

# 3. 检查受限模式下仅封杀 fetch 和 terminal 的测试断言
sed -n '275,290p' crates/agent/src/tools.rs

# 4. 查看 AgentTool trait 中 run 方法的 Result<Output, Output> 签名
sed -n '5090,5110p' crates/agent/src/thread.rs

# 5. 查看特性开关所保护的具体工具列表
sed -n '240,255p' crates/agent/src/tools.rs