Example

把一个自报的注解当作论断,而不是控制

在 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(一道以服务器自己的提示为键的闸门相信了一个谎言)。本书提出: 四级台阶、论断层级,以及关于被检查方的规则。

这里没有运行过容器、微虚拟机或凭据代理——那些行是有文档记载的选项,不是测试过的配置——而这个账本里没有任何机制是对着一个真实模型演练的。

完整源码与测试 和 MCP 闸门证据 。

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.