工具让 Agent 读取项目、修改文件、运行命令、访问语言服务和调用外部集成。工具目录不是权限目录,出现在目录中的工具不一定能在当前角色或机器上执行。
Resident tools
高频工具直接提供给模型:
execreadeditwritetaskgoalglobgreptodowebfetchwebsearchtool_searchtool_definetool_undefineworkflowteam
team 只对主会话 lead 可见,teammate 使用受限的 send_message 和 team_task。文件工具受 Workspace 和统一路径边界限制。exec 要求显式 Shell dialect,并把长命令转为后台任务。
webfetch 与 websearch 的提取、fallback、网络和计量边界见 Web 与 Search。
workflow 在 QuickJS 沙箱内运行模型编写的 JavaScript 编排脚本。脚本内除 agent() 子代理派发外,还有 await tool(name, args) 全局可直接调用宿主工具(如 read、grep),多步操作在一次模型往返内完成。桥内每次调用仍走完整工具执行路径(执行侧权限复验、hooks、审批、MCP 门控),单次输出按上限截断,每次运行最多 64 次工具调用,递归调用 tool("workflow") 会被拒绝。每次调用和 agent() 派发一样写入 workflow journal,中断后凭 run_id 续跑时逐条回放缓存,不重复执行。
动态工具
tool_define 让模型在运行时定义新工具:提交名称、描述、JSON Schema 参数和一段 QuickJS 实现源码,经用户 Approval(审批卡展示完整源码)后立即可用。动态工具的限定名是 dyn__<name>_<hash8>,hash8 是实现内容的 sha256 前 8 位——同一名字改实现即得到新名字,重定义无歧义,时间线卡片以「动态」徽标标识。
动态工具的实现在与 workflow 相同的 QuickJS 沙箱内执行,可以经 await tool(name, args) 组合现有工具(同样走完整执行路径),但不允许递归调用 workflow 或 tool_define/tool_undefine。定义随会话事件流持久化,fork 和 resume 后自动恢复,仅当前会话有效。
tool_undefine 按限定名卸载本会话已注册的动态工具:与注册走同一 Approval 口径(自主授权或当次人工批准,无审批通道时失败关闭),卸载事件同样落入会话事件流,fork/resume 后保持一致。卸载只影响后续调用——历史中已执行的 dyn__* 调用记录原样保留,卸载后该名字的新调用失败关闭。同名不同实现的再注册会得到新限定名,同实现则可以重新注册。沙箱超时(缺省 5 分钟)与实现源码上限(缺省 20000 字符)可在个人配置的 [sandbox] 下调整,见 Configuration。
按需工具
低频工具通过 tool_search 渐进披露:
deletelspagentworktreeskillknowledgeschedulebrowser
Browser 只有在个人配置中显式启用实验开关后才进入目录。MCP 工具有独立目录和策略,不属于内置 deferred tools 清单。模型先发现契约,再调用具体工具,避免一次性把全部工具说明塞入上下文。
权限来源
工具是否可用由以下条件共同决定:
- Agent 角色和 permission profile。
- Workspace 信任。
- 本机运行时和外部服务状态。
- Safety 判定。
- 用户 Approval。
研究和规划角色默认没有写入和命令权限。execution 角色可以获得更完整的工具面,但仍不能覆盖 Safety 的硬拒绝。Shell 在宿主机执行,不是沙盒;每条命令都必须显示完整 command 和 cwd,并获得当次 Approval。
可观察性
时间线中的每次工具调用是一张摘要卡片:状态点、工具名称、关键参数摘要和元信息徽标。卡片默认折叠,展开后可以在同一张卡内回看精确 arguments 和完整输出;edit 和 write 展开后渲染结构化 diff,而不是原始 JSON。连续的只读探索调用会聚合成一行分组卡片,显示调用次数和按工具的分布,展开后逐卡回看。Cmd+O 或 Session 头部的开关可以全局展开或折叠全部工具详情,手动开合过的卡片保持自己的选择。
长输出会截断展示,但实际任务状态仍由后端工具运行记录决定。