> Harness EngineeringHarness EngineeringHarness Engineering The engineering outside the model模型之外的工程模型之外的工程

4.4

Build the enforcement layer like software把執行層當軟體來設計把执行层当软件来设计

This chapter assumes you have read Hooks, or know that a hook is code the platform runs before tool calls, and that it can refuse the call.

這一章假設你讀過Hooks:每次呼叫都會經過的執行點,或者知道 hook 是平台在工具呼叫之前執行的程式碼,而且它能拒絕這次呼叫。

读这一章之前,你要读过Hook:每次调用都会经过的执行点,或者至少知道:hook 是平台在工具调用之前运行的代码,它能拒绝这次调用。

The Knowledge經驗分享经验分享

In one sentence

The enforcement layer is software, and it will fail. Decide in advance whether a failure lets the call through or blocks it, and build the layer so it can be tested and moved to another platform.

一句話

執行層是軟體,它會出錯。事先決定好:出錯時放行這次呼叫,還是擋下它;並把執行層做成可以測試、可以搬到別的平台的樣子。

一句话

执行层就是软件,软件会出故障。要事先决定:出故障时是放行这次调用,还是拦下它;并且把这一层做成可以测试、可以搬到别的平台的样子。

For leaders

  • The decision: decide, and write down, whether the guard fails open (lets the call through) or fails closed (blocks it) when it breaks, and name the person who owns the layer.
  • The risk: nobody decides this on purpose; it is decided by whatever the script does when it crashes. The platform has its own rules too: a crash can refuse the call, while a timeout is a silent pass for every event. A guard that fails open and says nothing leaves a hole nobody knows about.
  • The cost of doing it right: for a small setup, one short script is enough. The structure in the chapter pays off when rules multiply, when several people edit them, or when a second platform arrives. Someone must own the layer and re-run fixed scenarios after each platform update.
  • Ask the team: "If our guard crashes tomorrow, what happens to the next action, and who would see the error?"

給主管

  • 要做的決定:決定並寫下來:守衛壞掉時,是失效放行(放過這次呼叫),還是失效關閉(擋下它);並指定誰負責這一層。
  • 風險:沒有人是有意去決定這件事的;它是由腳本崩潰時碰巧做的事決定的。平台也有自己的規則:崩潰可以拒絕這次呼叫,而逾時對每一種事件都是默默放行。失效放行又不吭聲的守衛,留下一個沒人知道的洞。
  • 做對的成本:小的設定,一個短腳本就夠了。章裡的結構,在規則變多、有幾個人在改、或第二個平台出現時才划算。要有人負責這一層,每次平台更新後重跑固定的情境。
  • 可以問團隊:「如果我們的守衛明天崩潰,下一個動作會怎樣?誰會看到錯誤?」

写给管理者

  • 要拍板的事:决定出故障时守卫是放行(fail open)还是拦下(fail closed),把决定写下来,并指定这一层的负责人。
  • 风险:没人是有意做这个决定的,它是由脚本崩溃时碰巧做了什么决定的。平台自己也有规矩:崩溃可能直接拒绝这次调用,而超时则是对每一类事件都悄悄放行。一个放行了又一声不吭的守卫,会留下一个没人知道的洞。
  • 做对的代价:小规模的配置,一个简短的脚本就够了。规则多起来、好几个人在改规则、或者来了第二个平台时,本章里的结构才划算。必须有人负责这一层,每次平台更新后重跑固定场景。
  • 可以问团队:“如果明天我们的守卫崩溃了,下一个动作会怎样?谁会看到这个错误?”

The problem

The first hook is easy. It is one script with a few if lines: if the command contains rm -rf, refuse. It works, and you are pleased.

Then the rules grow. One rule guards a list of folders. One keeps a record of every call. One keeps count of something. One has to know which task the agent is working on. Each of them needs the same input, so each is added to the same script, and the script becomes a tangle. Three things go wrong.

  • You cannot change a number safely. The limit on repeated refusals, the list of protected folders, the time limit: they sit in the middle of the code. To change one you read all of it.
  • You cannot test it. The platform calls the script with a long piece of JSON. To check a rule you must run the agent and hope it does the thing you want to see.
  • You cannot move it. The script reads the platform's field names. When the platform renames one, or you add a second platform, every rule changes.

There is a fourth problem, and it is the one this chapter is about. This script runs before tool calls, so a bug in it is a bug in everything the agent does. What should happen when the hook itself breaks? Block the call, or let it through? Nobody decides this on purpose. It gets decided by whatever the script happens to do when it crashes. Hooks showed that the platform itself decides two cases for you, and they point in opposite directions. Better to decide yours first.

問題

第一個 hook 很簡單。一個腳本,幾行 if:指令裡有 rm -rf 就拒絕。它管用,你很高興。

然後規則變多了。一條規則守一串資料夾。一條記錄每次呼叫。一條計某樣東西的數。一條要知道 agent 正在做哪個任務。每一條都需要同樣的輸入,所以都加進同一個腳本,腳本就變成一團亂。有三件事出錯。

  • 你不能安全地改一個數字。重複拒絕的上限、受保護資料夾的清單、時間限制:它們都夾在程式碼中間。要改一個,就得把全部讀一遍。
  • 你不能測試它。平台用一大段 JSON 呼叫腳本。要檢查一條規則,你得執行 agent,然後祈禱它做你想看的事。
  • 你不能搬走它。腳本讀的是平台的欄位名稱。平台改了一個名字,或者你加了第二個平台,每條規則都要改。

還有第四個問題,這一章講的就是它。這個腳本在工具呼叫之前執行,所以它裡面的一個 bug,就是 agent 做的每件事的 bug。hook 自己壞掉的時候該怎麼辦?擋下呼叫,還是放行?沒有人是有意決定這件事的。它是由腳本崩潰時碰巧做的事決定的。Hooks:每次呼叫都會經過的執行點說過,平台自己替你決定了兩種情況,而且方向相反。最好是你先決定自己的。

问题

第一个 hook 很容易写。一个脚本,几行 if:命令里有 rm -rf 就拒绝。它管用,你很满意。

然后规则越来越多。一条规则守着一批文件夹。一条记录每次调用。一条给某样东西计数。一条要知道 agent 正在做哪个任务。它们需要的输入都一样,于是都加进同一个脚本,脚本就缠成了一团。会出三个问题。

  • 没法放心地改一个数字。连续被拒绝多少次就停、受保护的文件夹清单、时间限制:它们都埋在代码中间。要改一个,就得把整份代码读一遍。
  • 没法测试。平台调用脚本时传进来一大段 JSON。要验证一条规则,你只能跑起 agent,然后指望它恰好做出你想看的那件事。
  • 没法搬走。脚本直接读平台的字段名。平台把某个字段改了名,或者你加了第二个平台,每一条规则都得改。

还有第四个问题,也是这一章真正要讲的。这个脚本在工具调用之前运行,所以它里面的 bug,就是 agent 做的每一件事的 bug。hook 自己坏了,该怎么办?拦下调用,还是放行?没人是有意做这个决定的,它是由脚本崩溃时碰巧做了什么决定的。Hook:每次调用都会经过的执行点讲过,有两种情况是平台替你决定的,而且方向正好相反。最好先把你自己的决定做了。

How it works

Four design choices make the layer something you can change, test and move. Then one decision, and one way to test it. If you read only one part, read the decision, "when the layer itself fails". The four design choices are more structure than a small setup needs (see the traps below); skim them unless you are building one.

One call through the layer

Some words first. The enforcement layer is everything that stands between the model and the tools and says yes or no: the hooks and the code behind them. A module is one part of that code that is responsible for one thing, such as "protect these folders" or "record calls". An adapter is a small part that translates between two formats. The core is the part that runs the modules and combines what they say.

platform adapter the only part that knows the platform tasks gate records each module gives its view; none calls another core deny > ask > allow one answer, platform format
  1. The platform sends an event in its own format. The adapter, the one entry point, turns it into one common event.
  2. The modules that listen to this event each look at it. One checks paths and commands, one keeps records, one handles the task. They do not talk to each other.
  3. The core merges the views. If any module says deny, the answer is deny; then ask; then allow.
  4. The adapter turns the answer back into what the platform expects. If anything above throws an error, the error goes to a log and the call is let through.
One call through the enforcement layer. Only the adapter knows the platform, so only the adapter changes when the platform does.

1. One entry, and an adapter that is the only part that knows the platform

The platform is told about one hook, not ten. Every event goes to the same entry point. I did it this way for a practical reason: the platform does not filter by tool name for me, so ten small hooks would start ten processes for every call, most of them with nothing to do. I expect one entry that decides inside which modules care to be cheaper; I did not time it.

The first thing the entry does is hand the platform's JSON to the adapter. The adapter reads the platform's field names and spellings (tool names, upper and lower case, where the arguments are) and produces one common event that the rest of the code uses. On the way out, it does the reverse.

This is what makes the layer movable. When the platform changes a field, or you add a second platform, you write or change one adapter. The modules and their tests stay as they are. When the platform changes, I record real input from it first, check that the adapter reads the recording, and only then touch anything else.

2. Modules give opinions; the core decides

Each module sees the common event and returns one of: no opinion, allow, ask, deny, or "add these words for the model to read". A module imports only the shared basics, never another module. So you can add a module, or switch one off, without reading the others.

The core merges the opinions with a fixed order: deny beats ask, and ask beats allow. If any module says deny, the answer is deny, whatever the others think. The words that modules want to add are joined in order. This is the same idea as a vote where any single member can veto, and it means a new module can only make the layer stricter, never quietly weaker.

A module that raises an error is treated as having no opinion. One broken module cannot take the others with it. Note what follows: if the broken module was a deny rule, its refusal is gone and the call passes. That is the fail-open choice below, applied module by module.

3. Numbers live in files, not in code

How many refusals in a row before the breaker trips (Guard the files that hold the rules), which folders are guarded, how long a granted exception lasts: these are all policy files, plain data that code reads and never contains. The reasons for this are plain. A person who is not a programmer can read them and change one. A company can put its own values in a separate override next to the standard ones, so updating the standard never collides with local changes. And a rule's number is written in one place, so the docs cannot disagree with the code.

The texts people read follow the same idea: every refusal reason and message sits in a table, one table per language, with the same names. A test fails if one language lacks a name.

4. State lives in files, one writer per field

The layer runs as a fresh process for every event. It cannot keep anything in memory between two calls. So whatever must be remembered (which task is active, how many refusals so far, whether a human override is on) goes in a small file per session, read under a lock and written back. Each field has one module that is allowed to write it. A version number in the file lets old files be upgraded rather than break.

Files also make the layer easy to inspect. When something odd happens, you open the file and see what the layer believed.

The decision: when the layer itself fails

the hook's own code breaks block the call cost: all work stops for: production, credentials let it through, log the error cost: one rule is missed for: a project that is only code
Two ways to fail. Decide which one before the day it happens, rule by rule.

Now the question from the start. There are two ways to fail.

  • Fail open: when the hook's own code breaks, let the call through and write the error to a log.
  • Fail closed: when it breaks, block the call.

In my setup the hook fails open. The reason is a cost comparison, and I only claim it for this kind of project. The hook runs before tool calls. If a bug in it blocked every call, the agent would be useless until someone fixed the bug, and the person would be angry at the harness. If it lets one call through, the cost is one missed stop, and the error is in a log and shows up in a health check (a command that tests whether the setup is sound). In a project that is only code under version control, a missed stop can usually be found and undone. Blocked work cannot be made up as easily.

The platform adds its own rules, and they need care. VS Code's page points to GitHub's hook reference for the exit-code rules (GitHub hooks reference, checked 2026-10-28). For a before-tool command hook: exit code 2 is a deny, and any other non-zero exit is also a deny ("hook errored"), so a crash or a failed start refuses the call. If the hook takes longer than its time limit, it is killed and the call goes on through the normal permission flow: a silent pass, for every event. On other events, a non-zero exit is only logged and the run continues. My own measurement agreed on the crash and the timeout. So "fail open" is not something you get by doing nothing. The hook has to catch its own errors and answer "no opinion" on purpose, so that an ordinary bug does not turn into the platform's refusal. A crash of the whole program is a different case, which the platform decides. And "too slow" is a failure too: I run the hook once on purpose in that health check, and warn when the slowest recent call comes near the time limit, so I find out before the platform quietly drops my rules.

A rough guide, from the cost comparison above:

Your project Lean towards
Code under version control, a missed stop can be found and undone Fail open, with a visible log
Touches production data or credentials Fail closed on a short list, or better, do not rely on a hook (Least privilege)
Many people write rules, or you add a second platform Add the structure above, and the failure tests below

This choice is not for everything. Fail open is right when a missed stop is cheap to find and fix. It is wrong where a missed stop cannot be undone: a command that touches production data, a file that holds credentials. For those, one design is to fail closed, rule by rule, on a short list: if the hook breaks and the call touches anything on that list, block. I have not built this. But the better answer is the next chapter's: do not rely on a hook for those things at all (Least privilege).

Whichever you pick, write it down and make a failure visible. A layer that fails open and says nothing is the worst of both: you have a hole and do not know.

How to test it

The layer's input is data, so the test is easy: feed in an event and read the answer. Three kinds of test matter.

  • Rule tests. For each rule, a few events that must be refused, a few that must pass. Use input recorded from the real platform, not input you made up. Made-up input has the spellings you expect, and the platform does not.
  • Failure tests. Break a module on purpose and check that the others still answer. Feed in a broken settings file and check the result is the one you chose, fail open or closed. Platform docs tell you to do this: "Test the exit-code and timeout rules instead of assuming that every failure blocks work."
  • Delivery tests. The layer can be right and the answer can still be lost on the way (Hooks has an example). Check what the model really received.

Add one more habit. Keep a small set of fixed scenarios ("this command must be refused", "this edit must pass") and run them after every platform update. An update changes your layer without your changing a line of it.

Test your own setup

Three questions:

  1. If your hook crashes tomorrow, what happens to the next tool call? Do you know, or are you guessing?
  2. If the platform renames a field, how many files do you edit?
  3. Can you change the number of a rule without reading the code that uses it?

A test you can run today. Add a deliberate bug to a copy of your hook (a line that raises an error). Run a harmless task. Watch what the platform does and what your log says. Then fix the bug.

原理

四個設計選擇,讓這一層可以改、可以測、可以搬。然後是一個決定,和一個測試它的辦法。只讀一部分的話,讀那個決定:「執行層自己出錯的時候」。這四個設計選擇比小設定需要的結構更多(見下面的陷阱);不是要自己做一個的話,掃過去就好。

一次呼叫經過執行層

先說幾個詞。執行層是站在模型和工具之間、說好或不好的全部東西:hook 和它背後的程式碼。模組是這些程式碼裡負責一件事的一部分,例如「保護這些資料夾」或「記錄呼叫」。轉接器是在兩種格式之間翻譯的一小部分。核心是執行各個模組、並合併它們意見的那一部分。

平台 轉接層 唯一認得平台的部分 任務 關卡 紀錄 各模組給各自的意見,彼此不呼叫 核心 拒絕 > 詢問 > 放行 一個答案,用平台要的格式
  1. 平台用自己的格式送來一個事件。轉接層是唯一的入口,把它變成一個共通的事件。
  2. 聽這個事件的模組各自看一眼。一個查路徑和指令,一個做紀錄,一個管任務。它們彼此不說話。
  3. 核心合併各家意見。只要有一個模組說拒絕,答案就是拒絕;其次是詢問;最後才是放行。
  4. 轉接層把答案轉回平台要的格式。上面任何一步出錯,錯誤會寫進紀錄,這次呼叫放行。
一次呼叫穿過執行層。只有轉接層認得平台,所以平台改了,只改轉接層。

1. 一個入口,和只有它認識平台的轉接器

平台只被告知一個 hook,不是十個。每個事件都送到同一個入口。我這樣做有實際的原因:平台不會替我按工具名稱過濾,所以十個小 hook 會在每次呼叫時啟動十個處理程序,大多數無事可做。我預期一個入口、在裡面決定哪些模組要管,會比較便宜;我沒有計時。

入口做的第一件事,是把平台的 JSON 交給轉接器。轉接器讀平台的欄位名稱和寫法(工具名稱、大小寫、參數放在哪裡),產出一個共通事件,其餘的程式碼都用它。輸出時,它做相反的事。

這就是讓這一層可以搬的原因。平台改了一個欄位,或你加了第二個平台,你只寫或改一個轉接器。模組和它們的測試都不動。平台改版時,我先錄下它真實的輸入,確認轉接器讀得懂這份錄音,然後才動其他的東西。

2. 模組提意見,核心做決定

每個模組看到共通事件,回傳其中一個:沒有意見、允許、詢問、拒絕,或「加上這些話給模型讀」。模組只匯入共用的基礎部分,從不匯入別的模組。所以你可以加一個模組,或關掉一個,不用讀其他的。

核心用固定的順序合併意見:拒絕大過詢問,詢問大過允許。只要有一個模組說拒絕,答案就是拒絕,不管其他的怎麼想。模組想加的話,按順序接起來。這和投票時任何一個成員都能否決是同一個想法,意思是新模組只會讓這一層更嚴,不會悄悄變弱。

丟出錯誤的模組,被當成沒有意見。一個壞掉的模組帶不走其他的。注意接下來會發生什麼:如果壞掉的是一條拒絕規則,它的拒絕就沒了,呼叫就過去了。這就是下面講的失效放行,一個模組一個模組地套用。

3. 數字放在檔案裡,不放在程式碼裡

連續拒絕幾次斷路器才跳開(保護規則本身的檔案)、哪些資料夾受保護、給出的例外能持續多久:這些都是政策檔,是程式碼讀、但不包含在程式碼裡的純資料。理由很直白。不是程式設計師的人也能讀,也能改其中一個。公司可以把自己的值放在標準值旁邊的另一個 override 裡,所以更新標準值不會和本地的改動衝突。規則的數字只寫在一個地方,文件也就不會和程式碼對不上。

給人讀的文字也是同一個想法:每一條拒絕原因和訊息都放在表裡,每種語言一張表,名稱相同。有一種語言缺了一個名稱,測試就會失敗。

4. 狀態放在檔案裡,每個欄位只有一個寫入者

這一層每個事件都是一個全新的處理程序。兩次呼叫之間,它在記憶體裡什麼也留不住。所以需要記住的東西(哪個任務在進行、到目前拒絕了幾次、人的 override 開著沒有),都放在每個會話一個小檔案裡,加鎖讀、再寫回去。每個欄位只有一個模組可以寫。檔案裡的版本號,讓舊檔案可以升級,不會壞掉。

檔案也讓這一層容易檢查。出現怪事時,你打開檔案,就看到這一層當時相信什麼。

決定:執行層自己出錯的時候

hook 自己的程式壞了 擋下這次呼叫 代價:所有工作停擺 適用:生產環境、憑證 放行,並把錯誤記下來 代價:漏掉一條規則 適用:只有程式碼的專案
兩種失敗方式。要在事情發生之前,一條規則一條規則地先決定。

現在回到一開始的問題。出錯有兩種方式。

  • 失效放行:hook 自己的程式碼壞掉時,放行這次呼叫,並把錯誤寫進日誌。
  • 失效關閉:壞掉時,擋下這次呼叫。

在我的設定裡,hook 是失效放行。理由是成本比較,而且我只對這一類專案這樣說。hook 在工具呼叫之前執行。如果它裡面的 bug 擋下每一次呼叫,在有人修好 bug 之前 agent 就沒用了,人還會對 harness 生氣。如果它放過一次呼叫,代價是漏掉一次攔截,而錯誤在日誌裡,並且會出現在健康檢查裡(測試設定是否健全的指令)。在只有版本控制下的程式碼的專案裡,漏掉的一次攔截通常找得到、撤得回。被擋住的工作就沒那麼容易補回來。

平台也加了自己的規則,要小心。VS Code 的頁面指向 GitHub 的 hook 參考,裡面有結束代碼的規則(GitHub hooks reference,2026-10-28 查過)。對工具呼叫之前的指令型 hook:結束代碼 2 是拒絕,其他任何非零的結束代碼也是拒絕(「hook 出錯」),所以崩潰或啟動失敗會拒絕這次呼叫。如果 hook 超過時間限制,它會被殺掉,呼叫則照一般的權限流程繼續:對每一種事件都是默默放行。在其他事件上,非零的結束代碼只會被記錄,執行繼續。我自己的測量,在崩潰和逾時上和這個一致。所以「失效放行」不是什麼都不做就能得到的。hook 必須自己接住錯誤,並刻意回答「沒有意見」,這樣普通的 bug 才不會變成平台的拒絕。整個程式崩潰是另一種情況,由平台決定。而「太慢」也是一種失敗:我在那個健康檢查裡刻意執行 hook 一次,最近最慢的一次呼叫接近時間限制時就發出警告,這樣我能在平台默默丟掉我的規則之前發現。

從上面的成本比較,得出一個大略的指引:

你的專案 傾向
在版本控制下的程式碼,漏掉的攔截找得到、撤得回 失效放行,並有看得見的日誌
碰到正式環境的資料或憑證 在一份短清單上失效關閉,或者更好,不要靠 hook(有些東西根本不給)
很多人寫規則,或你要加第二個平台 加上面的結構,和下面的失敗測試

這個選擇不適用於所有事。漏掉的攔截容易找到、容易修的時候,失效放行才對。漏掉的攔截無法撤銷的地方,它就不對:碰到正式環境資料的指令、存放憑證的檔案。對這些,一種設計是一條規則一條規則地、在一份短清單上失效關閉:hook 壞了,而呼叫碰到清單上的任何東西,就擋下。我沒有做這個。但更好的答案是下一章的:這些東西根本不要靠 hook(有些東西根本不給)。

不管你選哪個,寫下來,並讓失敗看得見。失效放行又不吭聲的執行層是兩邊最壞的:你有一個洞,而且不知道。

怎麼測試

這一層的輸入是資料,所以測試很容易:丟進一個事件,讀答案。有三種測試重要。

  • 規則測試。每條規則,準備幾個必須被拒絕的事件,幾個必須通過的。用從真實平台錄下來的輸入,不要用你編的。編的輸入帶的是你預期的寫法,而平台不是。
  • 失敗測試。故意弄壞一個模組,確認其他的還會回答。丟進一個壞掉的設定檔,確認結果是你選的那個,失效放行或關閉。平台文件叫你這樣做:「要測試結束代碼和逾時的規則,不要假設每種失敗都會擋住工作。」
  • 送達測試。這一層可以是對的,答案卻在路上丟了(Hooks:每次呼叫都會經過的執行點有個例子)。檢查模型實際收到了什麼。

再加一個習慣。留一小組固定的情境(「這個指令必須被拒絕」、「這個編輯必須通過」),每次平台更新後都跑一遍。更新會改變你的執行層,而你一行都沒動。

測一下你自己的設定

三個問題:

  1. 如果你的 hook 明天崩潰,下一次工具呼叫會怎樣?你知道,還是在猜?
  2. 如果平台改了一個欄位名稱,你要編輯幾個檔案?
  3. 你能不讀用到它的程式碼,就改一條規則的數字嗎?

今天就能跑的測試。在你 hook 的副本裡加一個故意的 bug(一行會丟出錯誤的程式碼)。執行一個無害的任務。看平台做了什麼,看你的日誌寫了什麼。然後把 bug 修好。

原理

有四个设计选择,能让这一层变得可以修改、可以测试、可以搬走。再加一个决定,和一种测试它的方法。如果只读一部分,就读那个决定:“执行层自己出故障时怎么办”。四个设计选择比小规模的配置需要的结构要多(见下面的坑),不打算自己搭的话,扫一眼就行。

一次调用怎样穿过执行层

先交代几个词。执行层是站在模型和工具之间、负责说“可以”或“不行”的全部东西:hook 和它背后的代码。模块是这些代码里负责一件事的一部分,比如“保护这些文件夹”或者“记录调用”。适配器是在两种格式之间翻译的一小段代码。核心是运行各个模块、并把它们的意见合起来的那部分。

平台 适配器 唯一认得平台的部分 任务 关卡 记录 各模块给各自的意见,彼此不调用 核心 拒绝 > 询问 > 放行 一个答案,用平台要的格式
  1. 平台用自己的格式送来一个事件。适配器是唯一的入口,把它变成一个通用事件。
  2. 关心这个事件的模块各自看一眼。一个查路径和命令,一个做记录,一个管任务。它们彼此不说话。
  3. 核心合并各家意见。只要有一个模块说拒绝,答案就是拒绝;其次是询问;最后才是放行。
  4. 适配器把答案转回平台要的格式。上面任何一步出错,错误会写进日志,这次调用放行。
一次调用穿过执行层。只有适配器认得平台,所以平台改了,只改适配器。

1. 一个入口,一个唯一认得平台的适配器

告诉平台的是一个 hook,不是十个。所有事件都进同一个入口。我这么做有个实际的原因:平台不会替我按工具名过滤,所以十个小 hook 意味着每次调用要启动十个进程,其中大多数无事可做。我预计,一个入口、在里面决定哪些模块关心这次调用,会更省;但我没有计过时。

入口做的第一件事,是把平台的 JSON 交给适配器。适配器读平台的字段名和写法(工具名、大小写、参数在哪里),产出一个通用事件,其余代码都用它。回程时,它做相反的事。

这就是这一层能搬走的原因。平台改了字段,或者你加了第二个平台,只要写或改一个适配器。模块和它们的测试原样不动。平台一变,我先录下它的真实输入,检查适配器能读懂这份录制,然后才动别的。

2. 模块给意见,核心来决定

每个模块看到通用事件,返回下面几种之一:没意见、放行、询问、拒绝,或者“加上这几句话给模型看”。模块只导入共用的基础代码,从不导入别的模块。所以你可以加一个模块,或者关掉一个,不用读其他模块。

核心按固定的顺序合并这些意见:拒绝压过询问,询问压过放行。只要有一个模块说拒绝,答案就是拒绝,不管其他模块怎么想。模块想加的那些话,按顺序拼起来。这和“任何一个成员都能一票否决”的投票是同一个思路,意思是:新加一个模块,只会让这一层更严,绝不会悄悄变松。

抛出错误的模块,按没意见处理。一个坏掉的模块拖不垮其他模块。注意这带来的后果:如果坏掉的是一条拒绝规则,它的拒绝就没了,调用就过去了。这就是下面要讲的“出故障时放行”,一个模块一个模块地生效。

3. 数字放在文件里,不放在代码里

连续拒绝多少次熔断器才跳闸(见保护规则本身的文件)、哪些文件夹要守、一次授予的例外持续多久:这些都是策略文件,是代码去读、而不是代码里自带的普通数据。理由很简单。不会写程序的人也能读懂,也能改一个数。公司可以把自己的值放进一个单独的 override,和标准值并排放着,所以更新标准值不会和本地改动冲突。规则的数字只写在一个地方,文档就不会和代码对不上。

给人看的文字也是同样的思路:每条拒绝理由和每条消息都放在一张表里,每种语言一张表,名字一一对应。哪种语言少了一个名字,测试就会失败。

4. 状态放在文件里,每个字段只有一个写入者

这一层对每个事件都是起一个新进程来运行,两次调用之间没法在内存里留任何东西。所以凡是要记住的(哪个任务是当前的、到目前为止拒绝了几次、人工 override 开着没有),都放进每个会话一个的小文件,加锁读取,再写回去。每个字段只有一个模块有权写。文件里的版本号让旧文件可以升级,而不是直接坏掉。

文件也让这一层好查。出了怪事,打开文件,就能看到这一层当时是怎么认为的。

决定:执行层自己出故障时怎么办

hook 自己的代码坏了 拦下这次调用 代价:所有工作停摆 适用:生产环境、凭证 放行,并把错误记下来 代价:漏掉一条规则 适用:只有代码的项目
两种失败方式。要在事情发生之前,一条规则一条规则地先决定。

现在回到开头的问题。失败有两种方式。

  • 故障放行(fail open):hook 自己的代码坏了,就放行这次调用,并把错误写进日志。
  • 故障拦截(fail closed):它坏了,就拦下这次调用。

在我的配置里,hook 是故障放行。理由是一次成本比较,而且我只对这一类项目这么说。hook 在工具调用之前运行。如果它里面的 bug 把每次调用都拦下,agent 在有人修好 bug 之前就一无用处,人还会对 harness 发火。如果它放过了一次调用,代价是漏掉一次拦截,而错误会在日志里,也会出现在健康检查里(一条检查配置是否健全的命令)。在只有代码、放在版本控制下的项目里,漏掉的拦截通常能被发现并撤销。被拦住的工作,就不那么容易补回来了。

平台还有自己的规则,需要留意。VS Code 的页面把退出码的规则指向 GitHub 的 hook 参考(GitHub hooks reference,2026-10-28 查阅)。对于工具调用之前的命令 hook:退出码 2 是拒绝,任何其他非零的退出码也是拒绝(“hook errored”),所以崩溃或者启动失败都会拒绝这次调用。如果 hook 超过了时间限制,它会被杀掉,调用则按正常的权限流程继续:对每一类事件,都是悄悄放行。在其他事件上,非零退出只会被记录,运行继续。我自己的测量在崩溃和超时这两点上和文档一致。所以“故障放行”不是什么都不做就能得到的。hook 必须自己捕获错误,并有意回答“没意见”,这样一个普通的 bug 才不会变成平台的拒绝。整个程序崩溃是另一种情况,由平台决定。而且“太慢”也是一种故障:我在健康检查里特意把 hook 跑一次,最近最慢的一次调用接近时间限制时就发警告,这样我能赶在平台悄悄丢掉我的规则之前发现。

根据上面的成本比较,一个大致的指引:

你的项目 倾向于
版本控制下的代码,漏掉的拦截能被发现并撤销 故障放行,并留下看得见的日志
碰生产数据或凭证 在一份短清单上故障拦截,或者更好:不要靠 hook(见有些东西根本不给)
很多人写规则,或者你要加第二个平台 加上面的结构,以及下面的故障测试

这个选择不是对什么都适用。漏掉的拦截容易发现、容易补救时,故障放行是对的。漏掉的拦截没法撤销时,它就是错的:碰生产数据的命令、存着凭证的文件。对这些,有一种设计是按规则故障拦截,用一份短清单:hook 坏了,而这次调用碰了清单上的任何东西,就拦下。这个我没有做。但更好的答案在下一章:这些东西根本不要靠 hook(见有些东西根本不给)。

不管选哪个,都要写下来,并且让故障看得见。一个故障放行又一声不吭的执行层是两头都落了坏处:你有一个洞,却不知道。

怎么测试

这一层的输入是数据,所以测试很容易:喂一个事件进去,读它的答案。有三种测试重要。

  • 规则测试。每条规则准备几个必须被拒绝的事件、几个必须通过的事件。用从真实平台录下来的输入,别用你编的。编出来的输入用的是你预期的写法,而平台不一定。
  • 故障测试。故意弄坏一个模块,检查其他模块还能回答。喂一份损坏的配置文件,检查结果是你选的那一种,放行或拦截。平台文档也要求这么做:“测试退出码和超时的规则,别假设每种故障都会挡住工作。”
  • 送达测试。这一层可以是对的,答案却还是在路上丢了(Hook:每次调用都会经过的执行点里有个例子)。检查模型实际收到了什么。

再养成一个习惯。留一小批固定场景(“这条命令必须被拒绝”“这个编辑必须通过”),每次平台更新之后都跑一遍。更新会改变你的执行层,而你一行代码都没动。

测试你自己的配置

三个问题:

  1. 如果明天你的 hook 崩溃了,下一次工具调用会怎样?你是知道,还是在猜?
  2. 如果平台给某个字段改了名,你要改几个文件?
  3. 不读用到某条规则的代码,你能改它的数字吗?

今天就能做的一个测试。在你的 hook 的一份副本里,故意加一个 bug(一行抛错的代码)。跑一个无害的任务。看平台怎么处理,看你的日志里写了什么。然后把 bug 修好。

Costs and traps

This is more structure than the first hook needs. One script of twenty lines is fine for a dozen rules. The structure pays when rules multiply, when more than one person edits them, or when you plan a second platform. I grew into it; I did not start with it.

An adapter hides the differences, not removes them. Platforms differ in what a hook can see and when it runs. A common event is a lowest common denominator, and anything the adapter cannot fill in is missing from every module. I use one platform today, so I have not tested the idea on a second.

Fail open is a bet, and it can be lost. It was cheap in my project. Take care if you copy it: ask what the worst missed stop would be in yours. The person who owns the project should make this choice, not the script's author by accident.

Platform updates change your layer. Someone has to own the layer and run the fixed scenarios after each update. If no one does, the layer drifts without anyone noticing.

Veto power makes a bad module costly. A module that wrongly says deny blocks everything. The tests above, and refusal reasons that say what to do instead, are how I keep it in check.

A record nobody reads is no use. The error log of a layer that fails open is the only sign that it failed. Read it, or have a command that reports it.

代價和陷阱

這比第一個 hook 需要的結構更多。二十行的一個腳本,管十來條規則就夠了。結構在規則變多、不只一個人在改、或你打算接第二個平台時才划算。我是慢慢長成這樣的,不是一開始就這樣。

轉接器是藏起差異,不是去掉差異。平台在 hook 能看到什麼、什麼時候執行上都不同。共通事件是最小公約數,轉接器填不出來的東西,每個模組都看不到。我今天只用一個平台,所以沒有在第二個平台上測過這個想法。

失效放行是一場賭,可能會輸。在我的專案裡它很便宜。要抄的話請小心:問自己,在你的專案裡最糟的一次漏攔會是什麼。這個選擇應該由專案的負責人來做,不該是腳本作者無意中做出的。

平台更新會改變你的執行層。要有人負責這一層,每次更新後跑固定的情境。沒人做的話,這一層會在沒人注意時慢慢漂走。

否決權讓壞模組代價很高。一個錯誤地說拒絕的模組會擋下一切。上面的測試,和說明該改做什麼的拒絕原因,是我管住它的辦法。

沒人讀的紀錄沒有用。失效放行的執行層,它的錯誤日誌是它失敗了的唯一跡象。去讀它,或者弄一個指令來回報它。

代价和坑

这比第一个 hook 需要的结构多。二十行的一个脚本,管十来条规则完全够用。规则增多、不止一个人在改、或者你打算接第二个平台时,这套结构才划算。我是慢慢长到这一步的,不是一开始就这么搭。

适配器是遮住差异,不是消除差异。各平台的 hook 能看到什么、什么时候运行,是不一样的。通用事件只取各平台的交集,适配器填不出来的东西,每个模块都看不到。我现在只用一个平台,所以没有在第二个平台上测过这个想法。

故障放行是一场赌,而且可能输。在我的项目里它很划算。照搬时要小心:问问在你的项目里,最糟的一次漏拦会是什么。这个选择应该由项目负责人来做,而不是由脚本作者无意中做出。

平台更新会改变你的执行层。得有人负责这一层,每次更新后跑固定场景。没人做的话,这一层就会在没人察觉的情况下慢慢漂移。

否决权让一个坏模块代价很高。一个错误地说“拒绝”的模块,会拦下所有东西。上面的测试,以及写明“该怎么做”的拒绝理由,是我用来管住它的办法。

没人读的记录没有用。故障放行的执行层,它的错误日志是它出过故障的唯一迹象。要么去读它,要么有一条命令把它报告出来。

What the industry says Industry practice

The VS Code docs agree on the cautions. They describe a command hook's error on a before-tool event as denying the call, say that a timeout falls through to normal permissions, and tell you to test both (the exact exit codes are in GitHub's reference, above). They also say that hooks and instructions are "not substitutes for enforced permissions, sandboxing, or enterprise controls". (Agent hooks in VS Code) I did not find a published recommendation on fail open versus fail closed for agent hooks, so that part of the chapter is my reasoning, not a standard.

業界怎麼說 業界做法

VS Code 文件在這些警告上是一致的。它們描述指令型 hook 在工具呼叫之前事件上的錯誤會拒絕這次呼叫,說逾時會落到一般的權限,並叫你兩個都測(確切的結束代碼在上面 GitHub 的參考裡)。它們還說 hooks 和指令「不能代替強制的權限、沙箱或企業管控」。(Agent hooks in VS Code)對於 agent hook 該失效放行還是失效關閉,我沒找到公開的建議,所以這一章的那部分是我的推理,不是標準。

业界怎么说 业界做法

VS Code 文档在这些提醒上是一致的。它把命令 hook 在工具调用之前的错误描述为拒绝这次调用,说超时会回落到正常的权限流程,并要求两者都要测试(具体的退出码在上面 GitHub 的参考里)。它还说,hook 和指令“不能替代强制执行的权限、沙箱或企业管控”。(Agent hooks in VS Code)关于 agent hook 应该故障放行还是故障拦截,我没找到公开发表的建议,所以本章这一部分是我自己的推理,不是标准。

When to delete it Industry practice

The adapter is there because platforms differ and change. If the platforms converge on one hook format, the adapter shrinks to nothing. The timing check goes when a timeout is reported and not silent. If the platform one day offers enforced policy of its own (a rule file it checks itself, with a defined failure mode), I would move the hard rules there and keep the hook for records and reminders. The question of what happens when the enforcement fails does not retire: it moves to that policy.

什麼時候可以刪掉 業界做法

轉接器存在,是因為平台各不相同,而且會變。如果各平台收斂到同一種 hook 格式,轉接器就縮到沒有。逾時被明確回報、而不再默默發生的時候,計時檢查就可以去掉。如果平台有一天提供它自己的強制政策(一個它自己檢查、有明確失敗模式的規則檔),我會把硬規則搬過去,hook 留給紀錄和提醒。執行層出錯時會怎樣,這個問題不會退場:它只是搬到那份政策上。

什么时候可以删掉 业界做法

适配器之所以存在,是因为各平台不一样,而且会变。如果各平台收敛到同一种 hook 格式,适配器就会缩到什么都不剩。超时有了明确的报告、不再悄悄发生时,计时检查就可以去掉。如果平台有一天提供了它自己的强制策略(一份由它自己检查的规则文件,故障时的行为有明确定义),我会把硬规则搬过去,hook 只留作记录和提醒。执行失败时会怎样这个问题不会退役:它会转移到那份策略上。

Try it on your own setup

No harness needed. Open your agent in your own repository and paste:

If this project uses hooks or a similar enforcement layer, read it and answer: (1) what happens to the next tool call if a hook crashes or times out, for each hook; (2) where the numbers and patterns of the rules live, in data files or inside the code; (3) which tests or fixed scenarios exist, and whether they use input recorded from the real platform; (4) where errors are logged and whether anyone would see them. If there is no hook, say so and stop. Do not change any files, and do not run the hooks.

在你自己的環境試試

不用裝 harness。在你自己的倉庫裡打開 agent,貼上:

如果這個專案用了 hook 或類似的執行層,讀它並回答:(1) 每個 hook 崩潰或逾時的話,下一次工具呼叫會怎樣;(2) 規則的數字和模式放在哪裡,是資料檔還是程式碼裡;(3) 有哪些測試或固定的情境,它們用的是不是從真實平台錄下來的輸入;(4) 錯誤記錄在哪裡,有沒有人會看到。如果沒有 hook,就說沒有,然後停止。不要改任何檔案,也不要執行這些 hook。

在你自己的环境里试试

不用装 harness。在你自己的仓库里打开 agent,粘贴:

如果这个项目用了 hook 或类似的执行层,读一下它,并回答:(1)对每个 hook,如果它崩溃或超时,下一次工具调用会怎样;(2)规则的数字和匹配模式放在哪里,是在数据文件里,还是在代码里;(3)有哪些测试或固定场景,它们用的是不是从真实平台录下来的输入;(4)错误记在哪里,会不会有人看到。如果没有 hook,就这么说,然后停下。不要修改任何文件,也不要运行这些 hook。

Go deeper

延伸閱讀

延伸阅读

You can stop here: that is the whole idea. The next part shows where it runs, so you can look inside.讀到這裡就夠了,這就是整個想法。下一部分告訴你它在哪裡運行,可以進去看看。读到这里就够了,核心思路就是这些。下一部分告诉你它在哪里跑,可以进去看看。

In my practice (Copilot Harness)實作实战

Copilot Harness is my open-source harness for VS Code Copilot.

Repository: https://github.com/Smars-Bin-Hu/copilot-agentic-harness

Get started: clone it, open it in VS Code, and type /harness-rookie-get-me-ready in Copilot Chat. You need Python 3.9 or later and git.

Copilot Harness 是我開源的 VS Code Copilot harness。

倉庫: https://github.com/Smars-Bin-Hu/copilot-agentic-harness

開始:clone 下來,用 VS Code 打開,在 Copilot Chat 裡輸入 /harness-rookie-get-me-ready。需要 Python 3.9 以上和 git。

Copilot Harness 是我开源的 VS Code Copilot harness。

仓库: https://github.com/Smars-Bin-Hu/copilot-agentic-harness

上手:把仓库 clone 下来,用 VS Code 打开,在 Copilot Chat 里输入 /harness-rookie-get-me-ready。需要 Python 3.9 及以上版本和 git。

Explore it in the harness

The harness has this layer: one hook entry, an adapter for Copilot, modules, a core that merges, policy files, session state files, and a health check that tries the hook. After the setup above, type:

/harness-rookie-wondering I have read the chapter "Build the enforcement layer like software". Teach me how this harness is built inside: the one hook entry, the adapter, the modules and the merge (topic 14), and why the hook lets a call through when it fails itself (topic 15.5). Open the real files with me, and show me what is in the error log.

It teaches one small piece at a time, stops to ask if you are following, and opens the files with you.

在 harness 裡探索

harness 有這一層:一個 hook 入口、一個 Copilot 的轉接器、模組、一個合併的核心、政策檔、會話狀態檔,和一個會試跑 hook 的健康檢查。照上面的說明準備好之後,輸入:

/harness-rookie-wondering 我讀完了「把執行層當軟體來設計」這一章。請教我這個 harness 內部怎麼建的:一個 hook 入口、轉接器、模組和合併(主題 14),以及為什麼 hook 自己出錯時會放行呼叫(主題 15.5)。和我一起打開真實的檔案,讓我看錯誤日誌裡有什麼。

它一次教一小塊,停下來確認你跟得上,然後和你一起打開檔案。

在 harness 里探索

harness 里有这一层:一个 hook 入口、一个 Copilot 适配器、若干模块、一个合并意见的核心、策略文件、会话状态文件,以及一个会试跑 hook 的健康检查。按上面的说明准备好之后,输入:

/harness-rookie-wondering 我读完了“把执行层当软件来设计”这一章。请教我这个 harness 内部是怎么搭的:唯一的 hook 入口、适配器、模块和合并(主题 14),以及为什么 hook 自己出故障时会放行这次调用(主题 15.5)。带我打开真实的文件,并让我看看错误日志里有什么。

它一次只教一小块,停下来确认你跟上了,再和你一起打开文件。