工具系统参考手册
工具是智能体在会话中用于感知环境并执行操作的底层能力。部分工具静默运行；除非权限规则另有声明，涉及修改系统的工具默认需要人工确认审批。
文件 I/O
Read
读取文本文件、图片和 PDF。长行内容完整返回而不截断。
PDF 在客户端本地完成页面渲染与内嵌文本提取，无需网络往返，且支持按页码范围限制读取，以便大文档分块阅读。
当所选模型不支持视觉多模态时，读取图片会自动返回元数据（格式类型与分辨率）而非图片像素本身，以便智能体感知文件存在并通过程序检查。
图像识别也会检查文件内容，因此无扩展名或使用 .bin 后缀保存的 PNG 仍会按图像读取。
Write
创建新文件或完整覆盖现有文件。需要审批。
Edit
在文件中执行精确字符串替换。需要审批。
已完成的编辑结果采用 32 行内联预算，按文件顺序完整保留 diff hunk，超出部分汇总显示并可通过 Ctrl+O 在完整转录视图中查看。
当智能体在单批次调用中针对同一文件发出多个 Edit/Write 调用时，Ante 会按调用顺序串行依次执行，确保后序编辑始终基于前序修改结果进行。针对不同文件的调用仍保持并发执行。
Glob
根据 Glob 通配符模式查找文件。结果按路径排序，默认每页返回 100 个文件。页面会在达到 head_limit 条目数或共享输出预算时结束（以先到者为准）；将页脚中的 next_offset 作为下一次调用的 offset，即可继续读取且不会跳过或重复文件。将 head_limit 设为 0 可取消条目数上限，但输出预算仍然生效。
Glob 在搜索截止时间前已找到匹配项时，会返回带明确超时页脚的部分页面；若超时前一项也未找到，则报错并建议缩小路径或模式。默认截止时间为 20 秒；可将 ANTE_FILE_SEARCH_TIMEOUT 设为正整数秒数，同时覆盖 Glob 和 Grep 的期限。
Grep
使用 ripgrep 正则表达式搜索文件内容。输出模式可以返回匹配文件路径（默认）、匹配计数或匹配内容行。结果按路径排序，默认每页 250 个条目；head_limit、offset、next_offset 与输出预算的行为和 Glob 相同。分页只会在完整条目之间截断，因此续页不会从路径、计数或内容行的中间开始。
Grep 会在页脚报告无法读取、解码、打开或过大的文件。与 Glob 一样，超时时会把已找到的匹配项作为明确标记的部分页面返回；只有没有任何匹配项可返回时才报错。
在内容模式下，超长行会裁剪为最多 500 个字符（含截断标记）。匹配行保留首个匹配的起点附近内容；上下文行保留开头。需要完整行时请使用 Read。
终端与 Shell
Bash
执行 Shell 命令。每次调用均在独立的非交互子进程中运行 —— 进程状态不跨调用持久化。命令在 ANTE_SESSION 环境变量中接收调用方的当前会话 ID，避免继承过期的父进程值。可选的 max_wait_ms 字段控制 Ante 在内联等待命令完成的时长（默认 10000ms，限制在 250–600000ms 之间）。超出该等待窗口绝不会杀死命令或触发超时：Ante 会返回位于 ~/.ante/run/jobs/<proc-id>/ 下的后台任务句柄，包含 pid、部分输出以及持续追加写入的 status.json、stdout.txt 和 stderr.txt 文件。对于服务或监听进程建议传入如 250 的短窗口；请勿附加 &（属于多余符号且会被自动剥离）。
若命令在等待窗口内执行完毕，Ante 会直接在内联返回输出并显式清理句柄文件。一旦返回后台句柄，该任务在 Ante 重启后依然存活且活跃期间绝不被回收；任务结束后，其目录在闲置保留 24 小时后会在后续启动时统一回收。后台任务退出时，Ante 会在模型的下一个步骤边界或轮次开始时以通知块的形式自动将完成通知重新注入会话（包含退出码、运行时长、输出尾部及文件路径），无需手动轮询状态或设置长时间等待。在返回句柄前中断 Bash 调用会终止整个进程组（包含子进程与孙进程）。要停止已经转入后台运行的任务，请使用 kill -- -<pid> 向其进程组发送信号。需要审批。
结果以 status: exited 和明确的 exit_code 开头，并仅在非空时分别给出 stdout 与 stderr。后台结果则以 status: running 开头，并列出进程 ID 与句柄文件。被信号终止的命令采用 Shell 的 128 + signal 退出码约定。
受跟踪的后台任务完成时，客户端会收到关联原始工具调用的 TaskEnd 事件；TUI 会原地更新该调用的任务状态。
针对交互式程序和持久 Shell，智能体通过内置的 tmux 技能在常规 Bash 调用中驱动命名 tmux 会话（ante-*）—— 发送的每个击键均经过正常的 Bash 权限检查。可通过 /term <name> 随时查看或在会话中键入内容。
内置核心工具
Agent
派生子智能体以自主处理复杂任务。智能体根据任务特征自动挑选委派的子智能体，并可按需传入单次调用的 model 参数覆盖该子任务的模型（未指定时回退到子智能体定义或当前会话模型）。 可通过设置文件中的 max_concurrent_subagents 限制并发数量；达到上限后的调用会等待空位。
AskUser
在轮次进行中向用户提出 1 到 4 个结构化的多选题，以澄清意图或确认决策。TUI 会在输入框区域以交互组件形式渲染问题，支持选项预览、自由文本补充说明和多选；按 Enter 确认推荐选项，按 Esc 跳过以交由模型自行判断，点击“继续讨论”可返回正常对话。在 Slack / Discord 等网关中，问题会渲染为编号选项。子智能体不配备 AskUser，且无人值守会话不会因提问而挂起暂停。
每个问题接受 1 到 4 个选项。单选项问题也有效，但没有实质选择时通常用普通对话更清楚。无效的 AskUser 调用会在聊天中显示错误。
WebFetch
获取指定 URL 的内容并转换为 Markdown，交由当前会话模型直接分析。输入仅包含 URL；WebFetch 不会调用第二个提炼模型。超长响应会自动转存到系统缓存目录（如 macOS 上的 ~/Library/Caches，Linux 上的 $XDG_CACHE_HOME）下的临时文件中供智能体分片读取，而非生硬截断。请求使用 ante/<version> 作为 User-Agent；HTTP 失败时会尽可能附带最多 2 KB 的文本响应体。需要审批。
优先使用用户提供的 URL，或从文件、工具输出及搜索结果中发现的 URL。地址不确定时先搜索，再抓取。
WebSearch
检索互联网并返回带引用的搜索结果。需要审批。使用模型提供商的原生网络搜索能力，因此仅在声明了 supports_web_search 的提供商（Anthropic、OpenAI、Gemini、Grok、OpenRouter 和 Antix）下可用，并在这些提供商上自动加入工具集；其他提供商不提供该工具。单次搜索设有 90 秒上限 —— 超时报错并建议使用更窄的查询词，避免挂起整个工具调用批次。
临时搜索失败会在提供商客户端自身重试之外最多再重试三次；仅当等待时间能纳入同一个 90 秒预算时才按 Retry-After 等待。若限流无法及时恢复，错误信息会建议利用已知信息继续或抓取已知 URL，避免立即再次搜索。
可选工具
这些工具默认未开启。可通过 --include-tools 显式启用。
TodoWrite
通过任务清单维护多步骤工作的执行进度。默认 TUI 会话不再置顶任务清单；可通过 --include-tools TodoWrite 显式开启。
ViewImage
通过 file_path 与可选的 detail 为当前模型读取本地图片。默认 high 将最长边限制为 2000 像素；low 限制为 768 像素；original 保留原始分辨率。图片仍须通过格式、文件大小与解码限制验证。
MCP 工具
由配置的 MCP 服务器 提供的工具会以 mcp__<server>__<tool> 形式暴露给智能体。它们与内置工具并列展示，从智能体的角度看行为完全相同。MCP 工具同样受 --tools/--include-tools/--exclude-tools 命令行过滤约束，因此未点名它们的限制性 --tools 基础集会将其移除；若需按服务精确过滤，请使用 enabled_tools 配置项。
默认工具集
Ante 默认启用 Read、Bash、Grep、Glob、AskUser、WebFetch、Edit、Write 和 Agent。当会话的提供商支持原生网络搜索时，会自动追加 WebSearch。
TodoWrite 与 ViewImage 为可选启用工具。
工具过滤控制
在会话中控制可用工具：
# 用这些工具精确替换默认工具集
ante --tools Read,Glob,Grep -p "分析代码"
# 在默认集基础上引入可选工具
ante --include-tools TodoWrite,ViewImage -p "描述 assets/ 中的截图"
# 剔除指定工具
ante --exclude-tools Bash,Write -p "纯只读分析"
每个参数接收一个逗号分隔的值并可重复使用。空格分隔列表会报错，旧参数名 --allowed-tools 已不再接受（--disallowed-tools 仍作为 --exclude-tools 的弃用别名保留）。
在这些参数中传入匹配器语法（如 Bash(cargo test *)）仅会按工具名进行过滤 —— 仍保留整个 Bash 工具可用。若要限制工具允许执行的具体操作，请配合使用权限规则。