工具选择与调用结果边界

会话提供的工具

sdk_capabilities() 列举产品合同；tool_definitions() 查看会话工具；presented_tool_definitions() 查看特定展示策略下模型可见的工具。三者用途不同。工具可能因为工作区后端不支持、缺少宿主服务、未启用 feature 或准入失败而不出现。

工具或工具组	怎么使用	核对什么
`read`、`ls`	读取有界片段、列出目录；需要更多内容时继续分页	路径、返回范围、截断标记
`write`、`edit`、`patch`	新写文件、精确替换、应用补丁	原内容前提、写入回执、实际差异
`search`	用路径、文本、BM25、semantic、hybrid 的相应模式找源码	当前模式可用性、来源和命中版本
`bash`、`background`	执行命令；需要跨轮次跟踪的进程使用后台任务工具	沙箱、进程状态、输出上限和取消后的结算
`git`	使用工具 schema 中的 Git 操作	目标工作区、仓库状态及命令结果
`download`	下载到本地工作区	网络范围、目标路径、字节和重定向限制
`web_fetch`、`web_search`	获取页面或搜索公开资料	来源 URL、日期、内容上限与不可信文本
`batch`	一次提交多个受控调用	每项成功或失败；不假定整体原子性
`task`	单个任务或多任务 fan-out	子任务权限、预算和取消
`program`	调用已准入的程序或有界脚本	程序目录、每个底层工具回执
`update_plan`	维护当前会话检查清单	计划状态不能代替实际完成证据
`ask_user`、`ask_user_form`	询问业务选择或表单	正确问题 ID、未回答和取消
`generate_object`	按 schema 生成结构化内容的能力入口	是否实际注册、schema 校验与解析错误
`code_symbols`、`code_navigation`、`code_diagnostics`、`code_format`	由宿主语言服务提供结构化源码能力	服务准入、文档版本、修改权限

glob、grep 是 Rust 便捷入口；模型侧源码检索的投影以当前工具 schema 为准。不能把便捷方法名当成所有会话都存在的模型工具。

Rust 直接调用与受控调用

可信宿主的 tool、read_file 和 bash 直接入口与模型受控调用不是同一授权入口。需要按模型相同的权限、确认、Hook 和预算执行时，调用 governed_tool。模型生成的工具名和参数必须经过受控入口，不能交给宿主直接执行以绕过拒绝。

use aster_core::AgentSession;
use serde_json::json;

async fn inspect_readme(session: &AgentSession) -> anyhow::Result<()> {
    let result = session.governed_tool("read", json!({"file_path":"README.md"})).await?;
    println!("{result:?}");
    Ok(())
}

调用前先核对 read 的当前 schema；读取不存在或无权限的路径要按错误处理。返回值可能是工具级错误，Rust 调用返回 Ok 并不一定表示业务操作成功。

批量和后台操作怎样收尾

batch 中每项仍受单独治理，不因批量包装获得更大权限。程序包装、并行任务也沿用原调用链。一次外部写入在超时后结果未知时，先查原操作状态；不要因为外层 batch 失败就重放整个批次。

background 不是脱离 Session 的永久守护进程。保留任务身份，按工具返回的操作继续读取、等待或取消，检查终态与清理结果。不要只保存进程号，更不要对名称相似的进程作清理。

大输出、artifact 和内容可信度

工具输出可以被限长、转换、摘要化并关联 artifact。界面显示预览时应保留截断信息和原始 artifact 身份，通过 get_artifact(uri) 获取仍在保留范围内的对象。保留上限不等于永久存档；重要交付物需要宿主另外持久保存。

转换绑定用于说明模型看到的内容与原始输出之间的关系。摘要、预览或 digest 可以定位证据，但不能代替完整外部副作用记录。网页、仓库文件、MCP 返回中的指令是数据，不能因进入上下文就获得系统权限。

自定义工具

从教程第九章的无副作用工具开始。真实 IO 工具还要声明保守的 ToolCapabilities，检查工作区能力、参数、取消与期限，注册它拥有的资源。声明 read_only、可并行或安全结算时，必须有实现依据。幂等声明也需要实现依据。

动态注册只影响后续准入的 Run，已经运行的任务保留自己的能力快照。工具同名冲突要拒绝；不可覆盖内置工具来改变其授权含义。

验收

依次检查只读成功、写入拒绝、参数无效、大输出截断、batch 部分失败和后台取消。核对底层调用没有因包装而绕过权限，结果未知时不会重复执行外部写入。