代理工具
SOBA Agent 的 built-in tools、direct shell、MCP tools，以及 tool calls 和 slash commands 的边界。
工具是模型在 agent loop 中可以调用的函数。它们和 slash 命令不同：
- slash 命令由用户在 TUI 中执行；
- tools 由代理在推理后调用，并经过 trust/permission flow；
- direct shell
!由用户直接执行，不经过模型。
1. Built-in tools
| Tool | 作用 |
|---|---|
ls | 查看目录内容 |
read | 读取文件或行范围 |
write | 写入文件 |
edit | 修改文件 |
bash | 通过 agent loop 执行 shell 命令，并在 TUI 中实时显示脱敏后的输出 |
checkpoint | 记录 milestone/checkpoint |
activate_skill | 从 catalog 激活 skill |
read_project_memory | 读取 Project Memory |
write_project_memory | 写入 Project Memory |
MCP tools 会在 MCP server 启动后额外注册。它们的名称格式如下：
mcp_<server-id>_<tool-name>Server/tool IDs 会被规范化为 OpenAI-compatible function names。
2. Trust 和 permissions
每个 tool call 都会被分类为 safe、normal 或 dangerous。
| 级别 | 示例 |
|---|---|
safe | read, ls, git status, bun test |
normal | write, edit, 本地 build |
dangerous | rm, sudo, curl, git push, destructive git |
模式：
/permissions ask
/permissions repo
/permissions full
/permissions clearrepo 并不表示“一切都安全”。它只会取消当前仓库内部 dangerous 操作的确认提示。网络、特权和外部
dangerous 动作在 repo 模式下仍然需要确认。
full 会在当前会话结束前关闭重复的 dangerous 确认。只应在你愿意让代理运行 curl 或 git push 等外部命令的
环境中使用。
对于 dangerous 命令，SOBA 还会记录 permission receipts。当 SOBA 能推断出更安全路径时，确认提示和 proof
receipt 会包含 least-privilege alternatives，例如把 rm -rf dist && bun run build 拆成 scoped repo cleanup
和单独的非破坏性 build 命令。
Project skills 有单独的 trust boundary：
/project-trust status
/project-trust approve
/project-trust revoke在 runtime 中切换 permission mode 的内部 API 是 TrustManager.setPermissionMode()。对用户来说，正常入口是
/permissions slash 命令。
3. Direct shell !
Direct shell 用于你自己快速执行命令：
!git status --short
!bun test
!!bun run build区别：
| 方式 | 谁调用 | 代理接收输出 | 用户看到实时输出 |
|---|---|---|---|
!command | 用户 | 否 | 是 |
!!command | 用户 | 否 | 否 |
bash tool | 代理 | 是 | 是 |
如果需要代理分析输出，请让它自己执行命令：
Run bun test and fix the real failures from the output.模型启动 bash 时，结果块会立即出现，在命令运行期间保持展开，并持续追加经过敏感信息脱敏的输出块。
并行命令按 tool-call ID 分开，不会混合。最终 tool result 会替换实时预览，不产生重复内容。按 Ctrl+C
会停止 active tool，保留已经收到的输出，同时 agent turn 继续。
实时输出块只用于观察：不会写入 transcript、flight log 或 proof receipt。最终 tool result 仍是模型和 proof 系统唯一持久化的来源。实时预览最多保留最近 50 KB。
4. Project Memory tools
read_project_memory 和 write_project_memory 只在 agent loop 内工作。
示例 prompt：
Read Project Memory, then suggest a plan. Do not change anything.更新示例：
Update Project Memory: add a convention that tests mirror src and are run with bun test.
Do not save secrets.对于长期事实，可以要求 SOBA 在能够验证来源时附上 source receipt：
Update Project Memory with the provider registry loading rule.
Include source.file, source.lines, source.lastVerified, source.confidence, and staleIfFilesChange.5. MCP tools
MCP tools 会在 server 启动后出现：
/mcp status
/mcp start repo-metrics
/mcp status之后代理可以调用类似这样的 tool：
mcp_repo_metrics_repo_summaryMCP 的 trust 来自 .soba/mcp.json，不是服务器发送的 metadata。
6. 如何为 tools 写 prompts
好的 prompt：
Check the project.
First read package.json and tests, then run targeted bun test.
If a test fails, fix only the cause of the failure.
Do not make a git commit.不好的 prompt：
Do everything.请说明清楚：
- 哪些文件可以改；
- 哪些验证命令必须执行；
- 哪些动作禁止执行；
- 什么时候应该停下来询问。