把一个自报的注解当作论断,而不是控制
在 1.0.4 上扫描四个 Pi 包里 AgentTool.replay 的读取者,并按每个控制是否及时行动、且在触及范围之外,把它放到梯子上。
能力不是权限,而你能写下的几乎没有一个东西是边界——操作系统边界才是。本页用 AgentTool.replay 在 Pi 1.0.4 上展示这一点:一个由工具在它自身上填写的字段,而类型里没有任何东西核实它。
那个声明,以及那次扫描
write_file 自报自己 replay: "safe"——声明中没有任何东西检查这个论断:
// The tool chooses its own recovery policy. Nothing here checks that the choice is true.
const writeFile: AgentTool<typeof Params> = {
name: "write_file",
label: "write_file",
description: "write a file",
parameters: Params,
replay: "safe", // a claim by the inspected party
async execute() {
return { content: [{ type: "text", text: "ok" }], details: undefined };
},
};伴随的测试扫描那四个包已发布的 JavaScript,寻找读取者:
test("1.0.4: no shipped JavaScript in the Pi packages reads a tool's replay field", () => {
const readers: string[] = [];
let scanned = 0;
for (const pkg of ["pi-agent-core", "pi-coding-agent", "pi-mcp", "pi-codemode"]) {
for (const file of jsFiles(join(packages, pkg, "dist"))) {
scanned++;
for (const [i, line] of readFileSync(file, "utf8").split("\n").entries()) {
const code = line.trim();
if (code.startsWith("//") || code.startsWith("*") || code.startsWith("/*")) continue;
if (READS_REPLAY.test(code)) readers.push(`${file}:${i + 1}`);
}
}
}
assert.ok(scanned > 50, `scanned ${scanned} files`);
// Version-sensitive on purpose: if a later release reads the field, this fails and chapter 42 must be re-read.
assert.deepEqual(readers, []);一个空的结果不是空洞的:同一个正则同时匹配 tool.replay === "safe" 和 { replay: "never" },所以一个读取了这个字段的版本会失败——而本页必须被重读。
论断层级
一个流程起引导作用;一道边界必须在后果之前行动,并且位于它所约束之物的触及范围之外。只有最后一级台阶无条件地通过两项:
| 控制 | 在后果之前行动? | 在触及范围之外? | 所以它是 |
|---|---|---|---|
指令(AGENTS.md) |
否——改变被提议什么,而不是什么运行 | 否 | 影响 |
工具列表(--tools) |
是,对于一个从未被授予的工具 | 是——但约束的是词汇,不是触及范围 | 一道关于能被调用什么的边界 |
beforeToolCall / tool_call 闸门 |
是——在 ch39 / ch16 中测量 | 取决于它运行在哪里 | 一个作用于一次调用的流程 |
| 操作系统边界、容器 | 是——限制后果能是什么 | 是 | 一道权限边界 |
可迁移的规则:一个由被检查方选定的值不能充当那次检查的闸门。 一个自报自己无害、从而让闸门跳过那个人的工具,是在选择自己的监督——第 21 章观察到一道闸门相信了一个假的 readOnlyHint。
机制与局限
有文档记载: AgentTool.replay 的声明,以及 security.md 关于监视转录记录、使用项目信任和审阅更改都不构成一道安全边界的警告。已观察: replay.test.ts(一个工具能设置 replay,那次扫描覆盖超过 50 个已发布文件,1.0.4 中不存在读取者——对版本敏感)和 mcp.test.ts(一道以服务器自己的提示为键的闸门相信了一个谎言)。本书提出: 四级台阶、论断层级,以及关于被检查方的规则。
这里没有运行过容器、微虚拟机或凭据代理——那些行是有文档记载的选项,不是测试过的配置——而这个账本里没有任何机制是对着一个真实模型演练的。
Understand this example
Copy this prompt into your AI tool. No code runs here.
Apply this example
Copy this prompt into your AI tool. No code runs here.