为会修改内容的工具设置关卡
阅读约需 57分钟 分钟,12节中含12个示例。
学完本章,你将能够把智能体的改动保留在它自己的副本中,直到有人表示同意;能够检查这个同意是否覆盖了对方所读到的那一处确切改动;还能把一次拒绝作为运行终止的原因交还给智能体。
本书中的智能体负责维护 unitcraft。这个库的每一处改动都归维护者所有,而智能体在该库的一份临时副本上工作。测试和编辑都在副本中进行。仍然需要有一道环节来决定,改动何时进入维护者所拥有的库,而在这里,维护者就是提出该问题的人。任务 T-04 清楚地说明了其中的利害。它的问题请求再增加一个单位,即英寸,而智能体的副本中已有一处添加该单位的编辑。这处编辑是否落地,应由人来决定,智能体不应替他们做决定。
本章构建的是工具框架中负责发出询问的部分。智能体的文件工具只会写入本次运行的副本,只有在有人同意之后,工具框架应用该次运行的差异,库才会发生变化。在此之上还有两项检查:一是在 finish 时读取差异的关卡,二是在每次工具调用前后比较库字节内容的守卫。关卡和守卫都是教学用的代码,属于第二层防线,二者都不是沙箱。对于智能体所写的代码,首要的防御手段是容器或虚拟机,第 7 章对此有所说明。本章的示例都不运行容器或虚拟机,也没有任何录制内容展示它们。每次工具调用都被包裹在对案例库字节内容的一次比较之中,而守卫采用失败即关闭(fail closed)的方式:库一旦发生变化,本次运行就以 library_changed 结束,工具框架不应用任何内容,也不恢复任何内容。第一节说明副本无法阻止的情形。
这部分尚未翻译,因此以英文显示。
The copy comes first
The agent's file tools reach files only through its copy. Each run gets its own copy, made by scratch_copy in run_task, and the tools work through a Workspace rooted at that copy. Workspace.locate resolves every path the model gives. It refuses a path that is absolute, one with a .. part, one with a NUL byte or a backslash, one that resolves through a symlink to a place outside the copy, and any write into .github/. Through these tools, a path that does not resolve inside the copy never reaches the disk.
Those checks cover the paths the tools take. They do not cover code the agent runs. run_tests runs pytest on the copy, and pytest runs whatever the model wrote there. A test module the model adds is code too. The test run imports it and runs it with the harness's own user rights and no sandbox, so it can write to any path that user can write, including the library. The runner does not load conftest.py files (run_pytest passes --noconftest), but it does collect test modules, and that is the route this section means. The gate cannot stop that write, because the gate reads only the diff at finish. The library guard, in its section, sees the write once run_tests returns, ends the run as library_changed, and restores nothing. It detects the write after it happens. It does not prevent it.
This is the open side of the harness, and it is the main limit of this chapter. Chapter 7 describes the book's teaching sandbox, which runs the agent's commands with caps and a clean environment. Its table lists what it leaves open, and writes outside the copy are on that list. A container or a virtual machine is the primary defence for running code a model wrote, and chapter 7 explains both. The checks in this chapter are teaching code, written so a reader can open them, copy them and test them. They are not a substitute for that isolation.
The library changes in one place. apply in lib/permissions.py writes new bytes into the library, and its only caller is the gate's answer to a proposal, after a yes. library_copy makes the throwaway library that the examples apply to, so the book's case folder is never written. When a run ends, Gate.settle reports what the copy still holds, and nothing in the copy is written back to the library.
A write can also fail partway through an apply. The next example gives a proposal of two files, and puts a folder where the second file goes, so the second write fails.
1"""A proposal of two files where the second cannot be written, because a folder stands where it goes. The first file2is put back, the error goes back as the handoff, and the library holds the bytes it held before the finish."""3from lib.case import CASE4from lib.permissions import Gate, answer, gated, library_copy5from lib.tasks import snapshot6from lib.tools import V1, Workspace78with library_copy() as library, library_copy() as scratch:9 (library / "unitcraft" / "extra.py").mkdir()10 before = snapshot(library, ".")11 (scratch / "README.md").write_text("A new line in the readme.\n", encoding="utf-8")12 (scratch / "unitcraft" / "extra.py").write_text('"""Extra."""\nTOTAL = 1\n', encoding="utf-8")13 gate = Gate(library, lambda p: answer(p, True))14 result = gated(V1, gate).call(Workspace(scratch), "finish", {"summary": "Two files."})15 print("ended:", result.end)16 print("handoff:", result.question)17 print("README as before:", snapshot(library, "README.md") == snapshot(CASE, "README.md"))18 print("library bytes unchanged:", snapshot(library, ".") == before)19 print("applied:", gate.counts["applied"], "refused:", gate.counts["refused"])20 assert result.end == "ask_user" and "apply failed (IsADirectoryError)" in result.question21 assert snapshot(library, ".") == before and gate.counts["applied"] == 0
python apply-all-or-nothing.pyended: ask_user
handoff: p-1 was not applied: apply failed (IsADirectoryError); library restored
README as before: True
library bytes unchanged: True
applied: 0 refused: 1
apply puts back each file it had touched and each folder it had made, and the gate holds the proposal with the error as its reason: p-1 was not applied: apply failed (IsADirectoryError); library restored. The README, which was written first, is as it was before the finish, and the library's bytes are unchanged. The gate catches an OSError as a held proposal. Any other exception also puts the files back and is then raised, and no example here shows that path.
Working rule: Give each run its own copy, refuse every path that resolves outside it, and let exactly one function write to the original, called only after a yes. Then name what the run's code can still do to the original, check that with a guard, and do not count the gate as the protection.
这个测试框架处于哪种模式
设置关卡之前,要先回答一个问题:当智能体停下来请求许可时,由谁来回答?Claude Code 的交互模式会询问会话中的人。Claude Agent SDK 提供了几种在这一点上各不相同的权限模式,测试框架必须说明自己与其中哪一种相似,因为这个答案决定了:在无人可以响应时,需要批准的调用会如何处理。这个测试框架没有终端,也没有会话。它是无头运行,唯一能够回答的一方,是调用者传入的回调函数。
厂商文档对这几种情形做了区分。Claude Code 的权限页面指出,规则按拒绝、询问、允许的顺序检查,第一条匹配的规则决定结果。该页面还指出,Claude Code 默认在修改文件之前询问,而在工作目录内的只读操作则无需提示即可运行。Agent SDK 的权限页面描述了 dontAsk 模式:在该模式下,任何本来会弹出提示的调用都会被直接拒绝,而不会调用批准回调。本章没有运行过这两款产品,因此其中关于它们的说法均来自厂商,并已作相应标注。
这个测试框架保留了它的回调。需要得到肯定答复的变更会调用批准者,并等待答复。厂商的 dontAsk 模式在一个关键之处与此不同:它不调用回调就拒绝这类调用,而这个测试框架总是调用回调。本书把这种方式称为带回调的无头运行,而不是 dontAsk。无论运行使用哪种模型适配器,关卡都是相同的,因为它包装的是工具,而不是模型。第 4 章的模型协议才是随模型不同而变化的部分。
工作准则: 在添加关卡之前,先说明所处的模式。当调用者有能够回答的回调时,让关卡调用它并等待答复。没有配置批准者的关卡会拒绝启动:本章的代码会抛出错误。若设计要在无人能回答时转交处理,则需要它自己的路径,而本章中没有任何示例展示这种路径。
关卡设在 finish 中
智能体所做的大部分事情,都不会改动维护者所拥有的任何内容。它列出文件、读取文件并运行可见测试。它对副本所做的编辑是它自己的工作,本来就是要做的。唯一请求改动库的调用是finish,因此关卡的检查就设在这里,finish也正是提出提案的地方。
关卡包裹工具集中的每一个工具,每个工具的类别都来自lib/permissions.py中的同一张表。读取类工具(list_files、read_file、run_tests和ask_user)直接通过,库守卫会监视其中每一个。run_tests属于读取类,但它运行的是模型编写的代码,如副本一节所述。编辑与写入(edit_file和write_file)在副本中运行,关卡会对每次调用计数。finish是一项提案。它的类别来自测试框架的表,而不来自模型写下的任何内容,因此无论是模型的摘要,还是工具自身的描述,都不能设定它。发送给模型的名称、描述和模式,在有关卡和无关卡时完全相同,所以通过带关卡的工具发出的请求,与不带关卡时发出的请求是同一个请求。
提案是副本相对于库的完整差异,而不是模型写的摘要。pending列出每个字节有差异的文件,diff_text为每个文件写出一个标头,后面跟着该文件的统一差异。提案的标识是已更改字节的哈希,详见绑定一节。审批方会收到提案的 ID、摘要、已更改文件的列表、按原样显示的差异文本以及哈希。它的回答包含是或否、理由,以及它所回答的 ID 和哈希。摘要是作为模型对该改动的声称而展示的,关卡不把它当作证据。如果副本中没有任何改动,finish会带着自己的结果直接通过,因此没有改动任何内容的运行不会被询问任何问题。否则,审批方在工具调用内部被调用,运行会等待回答。当关卡处于强制状态时,finish 工具自身的主体只有在回答为是之后才会运行。
OWASP 关于过度代理的指南要求在执行高影响操作之前由人员批准,并要求智能体只拥有所需的工具。这是指导意见,而不是测量结果,本章把它当作该设计的理由,而不是该设计有效的证明。
任务集包含该案例上的 20 个任务,其中大多数由隐藏检查评分(任务集涵盖全部任务)。其运行是用工具集 v1 且不带关卡记录的,所用模型为 Qwen3-4B-Instruct-2507,也就是第 1 章所重放的模型。关卡不改变任何请求,因此通过它进行重放,发出的请求相同,得到的记录回复也相同。先从应当可行的路径开始:重放已记录的 T-04 运行,并由一位回答为是的人员审批。
1"""The recorded T-04 run (add the inch) with the gate and a scripted yes: its one changed file reaches the library, and2the hidden check fails before the apply and passes after it. The second part shows two yeses that cannot apply: a copy3that changed after the person looked, and an answer that names another proposal."""4from lib.case import load_tasks5from lib.permissions import Answer, Gate, gated, library_copy, replay_task, scripted6from lib.tasks import hidden_check_passes7from lib.tools import V1, Workspace89task = load_tasks(only=["T-04"])[0]10with library_copy() as library:11 assert not hidden_check_passes(task, library)12 gate = Gate(library, scripted((True, "")))13 run = replay_task("T-04", gate, library)14 print("ended:", run.ended)15 print("proposals:", gate.counts["proposals"], "asked:", gate.counts["asked"])16 print("applied:", gate.counts["applied"], "files applied:", gate.counts["files applied"])17 print("visible tests after the apply:", Workspace(library).run_tests().splitlines()[0])18 print("hidden check after the apply:", hidden_check_passes(task, library))19 assert run.ended == "finish" and gate.counts["applied"] == 1 and hidden_check_passes(task, library)20 run.close()2122with library_copy() as library, library_copy() as scratch:23 ws = Workspace(scratch)24 (scratch / "unitcraft" / "extra.py").write_text('"""Extra."""\nTOTAL = 1\n', encoding="utf-8")2526 def drift(proposal): # the copy changes in the window between the person's yes and the apply27 (scratch / "unitcraft" / "extra.py").write_text('"""Extra."""\nTOTAL = 2\n', encoding="utf-8")28 return Answer(True, proposal.id, proposal.sha256)2930 late = gated(V1, Gate(library, drift)).call(ws, "finish", {"summary": "Add a constant."})31 print("drifted copy, handoff:", late.question)32 wrong = gated(V1, Gate(library, lambda p: Answer(True, "p-7", p.sha256)))33 print("answer for another proposal, handoff:", wrong.call(ws, "finish", {"summary": "Add a constant."}).question)34 assert late.end == "ask_user" and "changed after" in late.question35 assert not (library / "unitcraft" / "extra.py").exists()
python gate-applies-only-on-yes.pyended: finish
proposals: 1 asked: 1
applied: 1 files applied: 1
visible tests after the apply: 8 failed, 22 passed
hidden check after the apply: True
drifted copy, handoff: p-1 was not applied: the copy changed after the answer
answer for another proposal, handoff: p-1 was not applied: the answer is to another proposal or diff
回答为是时,改动被应用,而隐藏检查只在应用之后才通过。运行以finish结束,关卡应用了它所询问的那项提案。改动落入之后,可见测试套件报告8 failed, 22 passed。该计数并不为任务评分,评分的是隐藏检查,而示例断言它在应用之前失败、应用之后通过。
示例的后半部分检查两种无法应用的“是”。在第一种中,副本在审批方内部、人员查看之后发生了变化。在第二种中,回答指向的是另一项提案。两者都因各自的理由被拒绝:第一种是p-1 was not applied: the copy changed after the answer,第二种是p-1 was not applied: the answer is to another proposal or diff。在这两种情况下,库都保持不变,示例对此做了断言。
finish 工具的主体也属于同一条规则。
1"""A finish that publishes does its work only after a yes. With a no the body never runs; with a yes it runs once,2after the change is applied to the library."""3from dataclasses import replace45from lib.permissions import Gate, answer, gated, library_copy6from lib.tools import V1, ToolResult, Workspace78published = []91011def finish_and_publish(ws, args):12 published.append(args.summary)13 return ToolResult("run ended", brief="finish", end="finish", summary=args.summary)141516publishing = replace(V1, tools=tuple(replace(t, run=finish_and_publish) if t.name == "finish" else t17 for t in V1.tools))181920def finish_with(yes: bool):21 with library_copy() as library, library_copy() as scratch:22 gate = Gate(library, lambda p: answer(p, yes, "decided"))23 (scratch / "unitcraft" / "n.py").write_text("N = 1\n", encoding="utf-8")24 result = gated(publishing, gate).call(Workspace(scratch), "finish", {"summary": "Publish."})25 return result, gate, (library / "unitcraft" / "n.py").exists()262728no_result, _, no_added = finish_with(False)29print("no: ended", no_result.end, "| publish ran:", len(published), "| file added:", no_added)30yes_result, gate, yes_added = finish_with(True)31print("yes: ended", yes_result.end, "| publish ran:", len(published), "| file added:", yes_added)32print("applied:", gate.counts["applied"])33assert no_result.end == "ask_user" and len(published) == 1 and not no_added34assert yes_result.end == "finish" and yes_added and gate.counts["applied"] == 1
python finish-body-waits-for-yes.pyno: ended ask_user | publish ran: 0 | file added: False
yes: ended finish | publish ran: 1 | file added: True
applied: 1
这段代码给运行提供了一个会执行发布的finish,并把同一项提案重放两次。回答为否时,发布主体不会运行,文件也不会被添加:ended ask_user | publish ran: 0 | file added: False。回答为是时,文件被添加,主体运行一次:ended finish | publish ran: 1 | file added: True。
工作准则: 从唯一能够改动库的那次调用中提出副本的完整差异,并在应用之前立即对该差异重新计算哈希。无论回答是什么,在人员查看之后发生了变动的副本都会被拒绝,因为应用写入的是已经过哈希的字节。工具自身的主体只在回答为是之后才运行。
一次批准只对应一个请求
只有当“同意”针对的是批准人读过的那项变更时,它才有价值。一旦一个关卡要处理多个提案,这个问题就会出现,多次运行共用一个关卡时就是如此。如果没有任何东西把两项变更联系起来,针对某一项变更给出的答复就可能被沿用到下一项变更上。
关卡用标识把它们联系起来。每个提案从关卡上的计数器领取下一个 ID,先是 p-1,然后是 p-2,依此类推,同时提案还带有变更字节的 SHA-256 哈希。该哈希按路径顺序覆盖每个变更文件的确切字节,而不只是批准人看到的文本。答复必须同时指明这两者。关卡在应用任何内容之前会先比对二者,然后对副本重新计算哈希,正如关卡一节所述。Microsoft 关于工具批准的 Agent Framework 页面描述了同样的模式。该页面指出,本地批准响应只有在与同一会话中记录的待处理批准请求相匹配时,才会授权一次工具调用;框架会忽略未绑定的响应,并记录一条警告。它关于关闭该机制的说明提到,关闭绑定可能会让伪造或重放的响应批准一次特权调用。
人所读到的文本是经过转义写出的,而不是原始文本。diff_text 会把终端可能响应的每个字符都写成可见的转义形式。因此,回车符或转义序列在差异中会以文本形式显示,而不是 UTF-8 文本的文件则只显示其字节的哈希。
该脚本写入两个文件,其内容在终端中会隐藏一行。一个文件含有回车符,会覆盖它前面的那一行;另一个含有转义符,会擦除一行。批准人看到这两行,且均已转义。脚本打印 2 标出控制字符的标题行,以及 0 所示文本中的原始回车符或转义符。其中的批准人回答“否”,因此没有任何内容被应用。
1"""A file that is not UTF-8 text is shown by the hash of its bytes, and the yes binds to those bytes. When the copy's2bytes change after the yes, the apply is refused, even though both versions decode to the same replacement characters."""3from lib.permissions import Change, Gate, answer, digest_changes, gated, library_copy4from lib.tools import V1, Workspace56with library_copy() as library, library_copy() as scratch:7 (scratch / "unitcraft" / "blob.bin").write_bytes(b"DATA \xff\n")89 def swap_then_yes(proposal):10 print("shown as:", proposal.diff.split(";")[0])11 (scratch / "unitcraft" / "blob.bin").write_bytes(b"DATA \xfe\n")12 return answer(proposal, True)1314 gate = Gate(library, swap_then_yes)15 result = gated(V1, gate).call(Workspace(scratch), "finish", {"summary": "Add a blob."})16 print("ended:", result.end)17 print("handoff:", result.question)18 print("applied:", gate.counts["applied"], "| blob in library:", (library / "unitcraft" / "blob.bin").exists())19 one = digest_changes([Change("x.bin", None, b"\xff")])20 two = digest_changes([Change("x.bin", None, b"\xfe")])21 print("hashes differ for \\xff and \\xfe:", one != two)22 assert result.end == "ask_user" and "changed after" in result.question and gate.counts["applied"] == 023 assert one != two
python answer-binds-bytes.pyshown as: == unitcraft/blob.bin: added, not UTF-8 text
ended: ask_user
handoff: p-1 was not applied: the copy changed after the answer
applied: 0 | blob in library: False
hashes differ for \xff and \xfe: True
该脚本展示了另一半情形。它添加一个字节不是有效 UTF-8 的文件,批准人看到的是 == unitcraft/blob.bin: added, not UTF-8 text。在“同意”之后,副本中的一个字节被换成另一个字节,而这两个字节解码后都是同一个替换字符。应用被拒绝:p-1 was not applied: the copy changed after the answer。脚本还断言这两个字节串的哈希不同,因此该哈希并不是解码后文本的哈希。
在一个示例中,两次运行可以共用一个关卡。
1"""Two proposals in one transcript, through one gate: the recorded T-04 run is answered yes and its inch reaches the2library; a stored T-09 run (fix the Celsius offset) is answered no and handed back. Each answer is logged with the3proposal ID and the hash of the diff it answers."""4from lib.case import CASE5from lib.permissions import Gate, library_copy, replay_task, scripted, stored_task6from lib.tasks import snapshot78with library_copy() as library:9 gate = Gate(library, scripted((True, ""), (False, "not in this change")))10 first = replay_task("T-04", gate, library)11 second = stored_task("T-09", gate, library)12 print("T-04 ended:", first.ended, "| T-09 ended:", second.ended)13 print("transcript, T-04:", first.trace.lines()[-1])14 print("transcript, T-09:", second.trace.lines()[-1])15 for line in gate.log:16 print("gate:", line)17 print("applied:", gate.counts["applied"], "refused:", gate.counts["refused"])18 assert first.ended == "finish" and second.ended == "ask_user" and gate.counts["applied"] == 119 assert snapshot(library, "unitcraft/units.py") != snapshot(CASE, "unitcraft/units.py")20 assert snapshot(library, "unitcraft/temperature.py") == snapshot(CASE, "unitcraft/temperature.py")21 first.close()22 second.close()
python approval-in-transcript.pyT-04 ended: finish | T-09 ended: ask_user
transcript, T-04: step 5: finish: p-1 yes, applied 1 files
transcript, T-09: step 6: finish: p-2 was not applied: the person said no: not in this change
gate: p-1 1 files, diff 06ee73fd984f: asked
gate: p-1 answer yes, bound to p-1 and 06ee73fd984f
gate: p-1 applied: 1 files
gate: p-2 1 files, diff 95fb833675dd: asked
gate: p-2 answer no, bound to p-2 and 95fb833675dd
gate: p-2 not applied: the person said no: not in this change
applied: 1 refused: 1
这段代码运行已记录的 T-04 运行并回答“同意”。然后运行一个已存储的 T-09 运行并回答“否”。T-09 运行不会重放其记录的 requests。它的工具结果来自这份副本,而副本可能与记录不同,所以它逐步送入已存储的回复。每个答复都记录在其提案旁边。T-09 的记录行为 step 6: finish: p-2 was not applied: the person said no: not in this change,而 T-04 的行以“同意”和应用结尾。关卡的日志完整地保存了同样的配对:每个答复一行,写明提案以及该答复所指明哈希的前十二个字符。想知道某次“同意”应用了哪个差异的读者,可以把这些字符与当时展示的提案相匹配。两条断言保证了结果:T-04 的变更进入了库,而 T-09 的变更没有。
ID 只在一个关卡内递增,所以两个关卡都会发出 p-1。这是一个尚未解决的限制,未解决限制一节对此作了说明。
工作准则: 给每个提案一个 ID 和其字节的哈希,要求答复同时指明这两者,并在应用之前再次检查二者。向批准人展示把每个控制字符都写出来的文本。把每个答复作为配对记录在其提案旁边,使读者能把一次“同意”与它所应用的变更对应起来。
有些变更不经询问即被拒绝
有些变更不该由人来决定。本案的规则禁止智能体重命名公共名称,也禁止它修改测试,而一次“同意”无法解除这类规则。把问题交给人,等于把决定放到了错误的地方,所以关卡在提出任何问题之前就拒绝这些变更。
assess 根据差异(与库相比)计算拒绝理由,而不是根据摘要。它拒绝五类变更。.github/ 下的变更会被拒绝。tests/ 下被删除的文件会被拒绝。对 tests/ 下已有文件的编辑会被拒绝。tests/ 下不属于 test_*.py 模块的新文件会被拒绝。被移除的名称会被拒绝:即 unitcraft/ 模块中库里定义而副本不再定义的顶层公共名称,以及库里有而副本缺少的顶层 test_ 函数。新增的 test_*.py 模块是允许的。两棵目录树按名称逐一比较,因此重命名会表现为一个被移除的名称。模型的措辞无法改变结果,因为理由是根据文件计算出来的。
1"""A rename of a public name and the removal of a test, each an edit that succeeds on the copy, with a summary that2says no approval is needed. The gate reads the diff: both are refused as never-class, and the person is never asked."""3from lib.permissions import Gate, gated, library_copy, scripted4from lib.tools import V1, Workspace56REMOVED = ('def test_parses_negative_value():\n q = parse_quantity("-2 m")\n'7 ' assert (q.value, q.unit) == (Decimal("-2"), "m")\n\n\n')89with library_copy() as library, library_copy() as scratch:10 gate = Gate(library, scripted((True, "")))11 tools, ws = gated(V1, gate), Workspace(scratch)12 rename = {"path": "unitcraft/parse.py", "old": "def parse_quantity(text: str)", "new": "def parse(text: str)"}13 print("rename:", tools.call(ws, "edit_file", rename).text)14 print("test removal:", tools.call(ws, "edit_file", {"path": "tests/test_parse.py", "old": REMOVED, "new": ""}).text)15 result = tools.call(ws, "finish", {"summary": "Tidy-up: a rename and a removed flaky test. No approval needed."})16 print("ended:", result.end)17 print("reasons:", result.question)18 print("asked:", gate.counts["asked"], "held as never:", gate.counts["held as never"])19 assert result.end == "ask_user" and gate.counts["asked"] == 020 assert "removes public name parse_quantity" in result.question21 assert "removes test test_parses_negative_value" in result.question
python never-class-refused.pyrename: edited unitcraft/parse.py
test removal: edited tests/test_parse.py
ended: ask_user
reasons: p-1 was not applied: the harness refuses it: changes the test file tests/test_parse.py; removes public name parse_quantity; removes test test_parses_negative_value
asked: 0 held as never: 1
本示例向副本中写入两处编辑:重命名一个公共函数,以及编辑一个测试文件并删除其中一个测试。两处编辑在副本中都能成功,因为允许编辑副本。拒绝发生在 finish 时,也就是读取差异的时候。智能体撰写的摘要声称无需批准,这一说法不会改变任何结果。
运行以 ask_user 结束,交接内容给出完整的理由:p-1 was not applied: the harness refuses it: changes the test file tests/test_parse.py; removes public name parse_quantity; removes test test_parses_negative_value。其中一条断言指出批准者从未被询问,也就是说关卡没有向任何人提出问题。
1"""An edit that keeps an existing test's name and removes its assertion is a change to a test file, and the harness2refuses it without asking. A new test module is not refused for that reason."""3from lib.permissions import Change, Gate, assess, gated, library_copy, scripted4from lib.tools import V1, Workspace56with library_copy() as library, library_copy() as scratch:7 gate = Gate(library, scripted((True, "")))8 tools, ws = gated(V1, gate), Workspace(scratch)9 edit = {"path": "tests/test_parse.py", "old": ' assert (q.value, q.unit) == (Decimal("-2"), "m")',10 "new": " assert True"}11 print("edit:", tools.call(ws, "edit_file", edit).text)12 result = tools.call(ws, "finish", {"summary": "Make the negative-value test pass."})13 print("ended:", result.end)14 print("reasons:", result.question)15 print("asked:", gate.counts["asked"], "held as never:", gate.counts["held as never"])16 new_module = assess(library, scratch, [Change("tests/test_new.py", None, b"def test_ok():\n pass\n")])17 print("new test module reasons:", new_module)18 assert result.end == "ask_user" and gate.counts["asked"] == 019 assert "changes the test file tests/test_parse.py" in result.question and new_module == []
python gutted-test-refused.pyedit: edited tests/test_parse.py
ended: ask_user
reasons: p-1 was not applied: the harness refuses it: changes the test file tests/test_parse.py
asked: 0 held as never: 1
new test module reasons: []
脚本走的是更小的一步。智能体修改已有测试中的一条断言,使该测试断言 True。这次编辑不经询问即被拒绝,因为对 tests/ 下已有文件的任何编辑都会被拒绝:p-1 was not applied: the harness refuses it: changes the test file tests/test_parse.py。对新测试模块做同样的检查,找不到拒绝它的理由,示例也断言了这一点,所以添加测试不会因这条理由被拒绝。
这项检查比较粗略,本章对此有明确说明。它比较的是顶层名称,因此公共函数体内部的变更要等待一次“同意”。像 parse_quantity = None 这样的重新绑定仍然定义了该名称,所以不会被拒绝。其余情形见未解决的局限一节。
工作准则: 对照由测试护具(harness)持有的清单读取差异,拒绝项目所禁止的变更,并在交接中指明它违反了哪条规则。清单要简短,并说明它不检查什么,因为针对名称的检查无法保护函数的行为。一次“同意”不能让被禁止的变更变得允许,所以不要为此提出询问。
拒绝要交还给模型
“不”是一个答复,运行必须据此行动。如果工具链丢弃了它,这次修改就会消失,而智能体也无从得知自己的工作为何没有生效。因此,关卡会把拒绝作为工具结果交还给模型,其形式与第 3 章处理错误参数时所用的相同,并且运行以 ask_user 结束,这是一次移交,其中的问题就是同一段文字(模型能读懂的错误)。
拒绝是一个工具结果,因此它和其他结果一样会占用上下文的空间,第 5 章也在那里对它计数(模型拥有的窗口)。Microsoft 的 Agent Framework 页面包含一个 Go 示例,它既返回拒绝,也返回批准,这样模型就能对人的决定作出回应。
1"""The recorded T-04 run with the gate and a scripted no. The refusal is the step's tool result, the run ends as a2handoff whose question is that refusal, and the library stays as it was."""3from lib.case import CASE, load_tasks4from lib.loop import run_task5from lib.models import ReplayModel6from lib.permissions import Gate, gated, library_copy, replay_ids, scripted7from lib.tasks import snapshot8from lib.tools import V1910task = load_tasks(only=["T-04"])[0]11with library_copy() as library:12 gate = Gate(library, scripted((False, "the inch belongs in a later change")))13 run = run_task(ReplayModel("task-set", "T-04"), task, gated(V1, gate), max_steps=V1.step_cap,14 ids=replay_ids("T-04"), case=library)15 print("ended:", run.ended)16 print("last step:", run.trace.lines()[-1])17 print("handoff question:", run.question)18 print("refused:", gate.counts["refused"], "applied:", gate.counts["applied"])19 unchanged = snapshot(library, ".") == snapshot(CASE, ".")20 print("library unchanged:", unchanged)21 assert run.ended == "ask_user" and run.question.startswith("p-1 was not applied") and unchanged22 run.close()
python refusal-handed-back.pyended: ask_user
last step: step 5: finish: p-1 was not applied: the person said no: the inch belongs in a later change
handoff question: p-1 was not applied: the person said no: the inch belongs in a later change
refused: 1 applied: 0
library unchanged: True
对 T-04 的同一次回放再次运行,这次给出的是“不”和一条理由。运行以 ask_user 结束,其最后一步就是这条拒绝本身。移交所携带的问题就是拒绝的文本,内容为 p-1 was not applied: the person said no: the inch belongs in a later change。人给出的理由就在这段文本中,因此阅读移交内容的人可以看到做出了什么决定以及原因。库没有变化,示例也对此作了断言。
**工作准则:**把“不”作为携带此人理由的工具结果交还给模型,并以一次移交结束运行,其中的问题就是同一段文字。不要吞掉这个“不”,也不要把它作为循环必须捕获的异常抛出。
包装器检查每一次调用
门控检查的是经由 finish 到达库的内容。还有别的途径可以改动库:run_tests 所运行的代码。因此,门控为每个工具包上一层守卫,在调用前后比较库的字节。如果字节发生了变化,而这一变化并非门控自己应用的,运行就会以 library_changed 结束,交接说明会列出相关文件。这是运行结束的第七种方式:第 2 章给出了循环产生的六种,守卫又增加了这一种。系统不会还原任何内容,也不会再针对已被改动的库运行任何其他操作。
1"""A test module written into the copy makes run_tests write the library. The guard sees the library's bytes change2around the run_tests call and ends the run as library_changed. It reports the file and restores nothing."""3from lib.permissions import Gate, gated, library_copy, scripted4from lib.tools import V1, Workspace56with library_copy() as library, library_copy() as scratch:7 marker = library / "unitcraft" / "marker.py"8 test_module = ("from pathlib import Path\n"9 f"Path({str(marker)!r}).write_text('MARK = 1\\n', encoding='utf-8')\n")10 gate = Gate(library, scripted())11 tools, ws = gated(V1, gate), Workspace(scratch)12 print("write test module:", tools.call(ws, "write_file", {"path": "tests/test_marker.py", "text": test_module}).text)13 result = tools.call(ws, "run_tests", {})14 print("run_tests ended:", result.end)15 print("handoff:", result.question)16 print("marker written:", marker.exists(), "| library changes counted:", gate.counts["library changed"])17 print("proposals:", gate.counts["proposals"])18 assert result.end == "library_changed" and marker.exists() and "unitcraft/marker.py" in result.question19 assert gate.counts["proposals"] == 0
python library-guard-fails-closed.pywrite test module: wrote tests/test_marker.py
run_tests ended: library_changed
handoff: the case library changed around run_tests: unitcraft/marker.py; the run stops, and nothing is restored
marker written: True | library changes counted: 1
proposals: 0
脚本向副本中写入一个测试模块。测试运行导入该模块时,模块会向库中写入一个标记。守卫以 library_changed 结束这次运行,交接说明为 the case library changed around run_tests: unitcraft/marker.py; the run stops, and nothing is restored。标记文件留在库中,而且没有提出任何提案:0。守卫是在事后报告这次写入的,正如副本一节所述。
对工具调用的检查还有第二种方式,即按名称检查。
lib/permissions.py 中的表是工具类别的唯一来源,不在表中的工具被归为 never。门控会在该工具自身的代码运行之前拒绝这次调用,拒绝信息以文本形式返回给模型。工具的描述在这里不起作用:描述声称某个工具只读,这只是一种说法,由表来决定类别。
1"""A tool outside the harness's table is refused before its own code runs, even when its description says it only2reads. The refusal goes back to the model as text, and the tool's body never runs."""3from dataclasses import replace45from lib.permissions import Gate, classify, gated, library_copy, scripted6from lib.tools import V1, NoArgs, Tool, ToolResult, Workspace78ran = []91011def reset(ws, args): # stands in for any effect the table does not know about12 ran.append(1)13 return ToolResult("did something", brief="did something")141516with library_copy() as library, library_copy() as scratch:17 gate = Gate(library, scripted())18 extra = Tool("reset_library", "A read-only helper.", NoArgs, reset)19 tools = gated(replace(V1, tools=V1.tools + (extra,)), gate)20 result = tools.call(Workspace(scratch), "reset_library", {})21 print("class:", classify("reset_library"))22 print("result:", result.text)23 print("body ran:", len(ran))24 print("never calls:", gate.counts["never calls"])25 assert not ran and result.text.startswith("error:") and gate.counts["never calls"] == 1
python unknown-tool-refused.pyclass: never
result: error: reset_library is not a tool this harness runs
body ran: 0
never calls: 1
脚本添加了一个描述为只读辅助工具的工具,并调用它。它的类别是 never,结果是 error: reset_library is not a tool this harness runs。它的函数体运行了 0 次,门控记录的 1 调用为 0 次。第 9 章把这条规则应用于 MCP 工具,这些工具的注解来自服务器,并不是类别。
工作准则: 为表中的每个工具划定类别,对表中没有列出的任何名称,在其函数体运行之前就予以拒绝。
允许列表不会跳过检查
跳过关卡的常见办法是允许列表。列表中的工具无需询问即可运行,设在询问环节的关卡也就被该工具绕过了。在 Agent SDK 中,在较早步骤已获批准的工具会跳过审批回调,因此只存在于回调中的检查会被该工具绕过。Agent SDK 的页面对此有说明。Claude Code 对规则的排序有所不同,先拒绝,再询问,最后允许,其权限页面指出,允许规则不能在拒绝规则中开出例外。
这道关卡没有允许列表。工具集中的每个工具都要经过包装器,包装器会拒绝表中未列出的名称,而对变更的检查位于 finish 中,差异(diff)就在那里被读取。工具上的任何标志都不能决定这项检查是否运行,因为没有任何工具可以免于经过包装器。依赖模型或服务器可以设置的标志的关卡,不能算作关卡。第 9 章把这条规则应用于 MCP 工具,并让这些工具经过本章的审批,而不是经过允许列表。
工作准则: 不要让工具或其服务器提供的名称、描述或标志来决定检查是否运行。要把检查放在工具所做的每一项变更都必须经过的路径上。如复制一节所说,测试所运行的代码不在这条路径上,而标志只描述工具,仅此而已。
跨任务集
到目前为止,每个示例都只跟踪单次运行。本案例要回答的问题是:在所有已记录的运行中,包括那些不应改变任何内容的运行,闸门会怎样处理。
1"""The 20 recorded task-set runs replayed with the gate observing, each matching its recorded ending and step count, and2the gate counting what it would have held (the four stop tasks T-16 to T-19 first). Counts only."""3from lib.case import CASE, DATA, load_tasks4from lib.permissions import Gate, library_copy, replay_task5from lib.tasks import snapshot6from lib.trace import IdCounter78import json910CHANGES = ("edit_file", "write_file")11rows = (DATA / "recorded" / "task-set" / "runs.jsonl").read_text(encoding="utf-8").splitlines()12recorded = {r["task"]: r for r in map(json.loads, rows)}13runs, gates, pendings = {}, {}, {}14with library_copy() as library:15 ids = IdCounter()16 for task in load_tasks():17 gate = Gate(library, enforce=False)18 run = replay_task(task.id, gate, library, ids=ids)19 assert (run.ended, run.steps) == (recorded[task.id]["ended"], recorded[task.id]["steps"]), task.id20 runs[task.id], gates[task.id], pendings[task.id] = run, gate, gate.settle(run.scratch)21 for tid in ("T-16", "T-17", "T-18", "T-19"):22 gate, pend, run = gates[tid], pendings[tid], runs[tid]23 refused = sum(1 for r in run.trace.records if r["tool"] in CHANGES and r["brief"].startswith("error"))24 print(f"{tid} ended: {run.ended}, steps: {run.steps}")25 print(f" change calls: {gate.counts['change calls']}, refused by the tool: {refused}")26 print(f" never-class calls: {gate.counts['never calls']}, changes in the copy at the end: {len(pend.files)}")27 print(f" held as never: {len(pend.never)}, waiting for a yes: {len(pend.files) - len(pend.never)}")28 changed = sorted(t for t in pendings if pendings[t].files)29 print("runs:", len(runs))30 print("runs with a change left in the copy:", len(changed), ", tasks:", ", ".join(changed))31 print("change calls, all runs:", sum(g.counts["change calls"] for g in gates.values()))32 print("never-class calls, all runs:", sum(g.counts["never calls"] for g in gates.values()))33 print("held as never, all runs:", sum(len(p.never) for p in pendings.values()))34 print("proposals that would wait for a yes, all runs:", sum(g.counts["waiting for a yes"] for g in gates.values()))35 print("library changed by the replays:", snapshot(library, ".") != snapshot(CASE, "."))36 assert snapshot(library, ".") == snapshot(CASE, ".") and gates["T-18"].counts["never calls"] == 137 for run in runs.values():38 run.close()
python gate-over-task-set.pyT-16 ended: step_cap, steps: 16
change calls: 8, refused by the tool: 8
never-class calls: 0, changes in the copy at the end: 0
held as never: 0, waiting for a yes: 0
T-17 ended: ask_user, steps: 9
change calls: 4, refused by the tool: 4
never-class calls: 0, changes in the copy at the end: 0
held as never: 0, waiting for a yes: 0
T-18 ended: ask_user, steps: 4
change calls: 1, refused by the tool: 1
never-class calls: 1, changes in the copy at the end: 0
held as never: 0, waiting for a yes: 0
T-19 ended: ask_user, steps: 9
change calls: 4, refused by the tool: 4
never-class calls: 0, changes in the copy at the end: 0
held as never: 0, waiting for a yes: 0
runs: 20
runs with a change left in the copy: 5 , tasks: T-04, T-05, T-08, T-09, T-14
change calls, all runs: 70
never-class calls, all runs: 1
held as never, all runs: 0
proposals that would wait for a yes, all runs: 5
library changed by the replays: False
本示例让闸门重放每一次已记录的任务集运行,这个闸门只观察,不执行拦截。闸门照常做出决定,统计它会拦下的内容,并返回各工具自己的结果,因此每次运行都终止在录制时的结局。每次重放都经过断言,确认其结局和步数与录制一致,并且资料库保持原样。这些数字统计的是闸门将会采取的动作,所以在开启强制执行之前先行试用是安全的。
停止类任务 T-16 至 T-19 都试图修改文件,而工具拒绝了其中的每一次调用,因此它们的副本都没有变化。闸门对这些调用做了计数。T-18 是唯一试图写入 .github/ 的任务。闸门把这次调用记为禁止类调用,所有运行合计为 1 次。它把 0 项变更按禁止处理,因为在任何变更到达副本之前,工具就已经拒绝了该调用。
副本确实保留了变更的地方,闸门会就此询问相关人员。在全部重放中,有 5 项提议会等待一个“同意”。这些数字显示的是闸门会如何处理这些副本,却无法显示人会如何回答。这就是本章的示例使用预设答案的原因,也是真正的审批者必须是人,或是由人控制的进程的原因。
工作准则: 在对闸门启用强制执行之前,先在不强制执行的情况下让已记录的运行通过它重放,并把每个结局和每个数字与你的预期相比较。出乎意料的数字,是关于闸门或关于这些运行的一项发现,应当在任何人依赖该闸门之前把它弄清楚。
会放行变更的供应商默认设置
下面的若干种失败,都源于那些看似合理的默认设置。每一条都是读者可能相信的说法,这里把它与供应商文档的记载以及本套测试框架的实际做法对照。供应商的说法均注明了出处页面,本书没有运行过其中任何一条。
- 允许规则可以覆盖拒绝规则。Claude Code 文档的说法恰恰相反:拒绝规则先于其他规则求值,参见允许列表一节的说明。
- 绕过模式意味着没有关卡。SDK 文档指出,在绕过模式下,拒绝规则和询问规则依然生效,而且
allowed_tools列表并不对其构成限制。 - 批准一次就是永久批准。Claude Code 的表格把“不再询问”的选择限定在:对于 shell 命令,作用于某个仓库和某条命令;对于文件修改,作用于当前会话。Microsoft 的页面则说,长期有效的批准保存在会话状态中,并不与创建它们的工具实例绑定,因此同名的替换工具可能匹配到已保存的规则。
- 任何回答都可以。Microsoft 的 Agent Framework 默认会忽略未绑定到待处理请求的响应。在这里,回答必须指明提案及其哈希值,如绑定一节所示。
- 返回允许的钩子会跳过检查。SDK 文档指出,返回允许的钩子并不会跳过拒绝和询问这两个步骤。
- 模型自己输出的文本可以授予批准。在本框架中,写着“已批准”或“无需批准”的摘要不会改变任何结果。永不放行类示例表明,摘要中的声明不会改变拒绝的结论,因为拒绝来自差异比对。
工作准则: 当供应商的默认设置允许用一个回答、一个标志或一个钩子来代替检查时,不要照搬该默认设置。应把检查写成能指明其所批准的对象:提案、它的字节内容,以及所适用的规则。然后测试错误的回答、被移动的副本和声称已获批准的情形是否都会失败。
本关卡未涵盖的内容
本章代码的安全审查留下了下列局限,本节是列出这些局限的唯一位置。每一项都是教学代码中的缺口,本章均未补上。
- 代理运行的代码(副本部分)。
run_tests以框架自身的权限运行模型编写的代码。守卫只在写入库之后报告该写入,不会恢复任何内容。第 7 章的沙箱为测试设置了资源上限和干净的环境,但并不阻止对其他路径的写入。容器或虚拟机是首要的防御手段,而这里没有任何示例运行它们。 - 顶层名称检查(F-7)。“绝不”类别只比较
unitcraft/和tests/中的顶层名称,不比较更深的层级。仅在某个块内部定义的名称,在两棵树中都不计入。公共函数体内的改动,以及诸如parse_quantity = None的重新绑定,并不会被拒绝,而是等待一个“是”。 - **审批者异常(F-8)。**审批者一旦抛出异常,循环就以该异常结束,且不应用任何改动。这不属于移交。工具抛出
ToolError之外的错误时,同样会逃出循环:在对当前代码的一份临时副本所做的探测中,edit_file中的单个孤立代理项把该副本的文件截断为零字节,随后抛出了UnicodeEncodeError。 - **运行范围内的 ID(F-9)。**每个关卡都从
p-1开始为其提案编号。因此,只要两份差异的字节相同,为某个关卡的p-1记录的答复就会与另一个关卡的p-1相匹配,于是从旧日志重放的答复可以批准另一次运行中的改动。字节是所展示的那些,但该 ID 在不同运行之间并不唯一。跨运行保存的日志还需要记录该次运行的 ID。 - **符号链接(F-10)。**关卡的文件列表会跟随副本中的符号链接。指向副本之外某个文件的链接,会把该文件的字节带入差异,而涵盖该差异的“是”随后可以把这些字节作为普通文件应用到库中。此人能在差异中看到这些字节,但提案读取的是副本并不拥有的文件。修复办法是跳过链接,而本章没有这样做。
- 此人读到的内容。“是”涵盖的是审批者所展示的差异。只展示部分文本的审批者,给予此人的内容少于哈希所涵盖的内容,而本章的示例展示完整的差异。
**工作准则:**把每一项局限写在产生它的代码旁边,并且只在一个位置点明一次,这样读者在依赖关卡之前,就能看清它不做什么。
本章做出的决定
下面的决定足够简短,可以对照前文的示例逐条核对。
- 副本是框架自带工具的写入位置,框架只通过一条写入路径修改库,而且只在得到“同意”之后才调用这条路径。容器或虚拟机是运行所执行代码的主要防线。副本和关卡都是教学用代码,尚未解决的限制说明了它们留下的缺口。
- 关卡位于
finish中,读取的是副本的完整差异,而不是摘要。 - 类别来自框架自己的表。无论是模型的措辞,还是工具的描述,都不能设定类别;表中没有列出的工具,在其主体运行之前就会被拒绝。
- “同意”绑定的是提案的 ID 和提案字节的 SHA-256 哈希,并且在应用之前会立即对副本再次计算哈希。
- finish 自身的主体只有在得到“同意”之后才会运行。
- “不同意”会使运行以
ask_user结束,而那个人给出的理由会成为提出的问题。 - 框架通过回调以无界面方式运行。它不是厂商的
dontAsk模式,本书也不这样称呼它。
有三件事是有意保持开放的。审批者归调用方所有,示例用脚本模拟审批者,以便离线运行。框架直接拒绝的变更清单很短,更长的清单应由案例的维护者决定,而不是由关卡决定。关卡检查的是对库的变更,而不是智能体运行的命令,这一点在第 7 章中讨论。
框架只有在得到“同意”之后才会对库应用变更,而“同意”只应用那个人看到过并且已计算哈希的字节。关卡不检查运行所执行的代码。守卫能检测到此类代码对库做出的变更并结束运行,但无法阻止该变更;相应的防御措施见副本一节。
**工作准则:**把关卡做出的每一项决定,连同展示该决定的示例一起写下来,并列出关卡留给调用方的事项。没有示例支撑的决定只是一种主张,本章会将其标明为主张。
本章,在本版次中
版次 2026.11.2示例于 2026年11月20日 通过本章 12个示例 个示例中有 12 个通过
译自英文版图书,版次 2026.11.2。