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

2.2

HooksHooks:每次呼叫都會經過的執行點Hook:每次调用都会经过的执行点

This chapter assumes you have read The agent loop, or know that an agent works by asking for tool calls.

讀這一章,你需要讀過 agent 循環,和你能插手的地方,或者知道 agent 是靠要求工具呼叫來運作的。

读这一章,需要你读过agent 循环,以及你能插手的地方,或者知道 agent 是靠发出工具调用来工作的。

The Knowledge經驗分享经验分享

In one sentence

A hook is code the platform runs at fixed points in every turn, including inside subagents. It is where hard rules live, and it sees calls, not what a command does once it runs.

一句話

hook 是平台在每一輪的固定位置執行的程式碼,子 agent 裡面也一樣。硬規則就放在這裡。它看到的是呼叫,不是指令執行起來會做什麼。

一句话

hook 是平台在每一轮的固定位置运行的代码,子 agent 里也一样。硬性规则就放在这里。它看得到调用,看不到命令运行起来之后做了什么。

For leaders

  • The decision: decide which rules must hold every time, and put those in a hook (code the platform runs on every tool call) instead of in a prompt.
  • The risk: a hook sees the text of a call, not what a command does once it runs. It can also fail quietly. In Copilot as I saw it in October 2026, a hook that times out counts as a pass, and one that cannot start blocks every tool. In one small batch on one machine, about a third of prompts reached the model without the rules a hook was meant to add; read that as "a lot", not as a rate.
  • The cost of doing it right: one small program and one configuration file, kept under code review. Mine normally runs in a few dozen milliseconds.
  • Ask the team: "What happens to our rules when the hook is slow or broken, and how do we know the model actually received them?"

給主管

  • 要做的決定:決定哪些規則必須每次都成立,把它們放進 hook(平台在每次工具呼叫時執行的程式碼),不放在 prompt 裡。
  • 風險:hook 看到的是呼叫的文字,不是指令執行起來會做什麼。它也可能悄悄失效。依我 2026 年 10 月看到的 Copilot,逾時的 hook 算通過,啟動不了的 hook 會擋掉所有工具。在一台機器上的一小批樣本裡,大約三分之一的 prompt 到達模型時,沒有 hook 本來要加上的規則;把它讀成「很多」,不要當成比率。
  • 做對的成本:一個小程式和一個設定檔,放在程式碼審查之下。我的通常在幾十毫秒內執行完。
  • 可以問團隊:「hook 很慢或壞掉的時候,我們的規則會怎樣?我們怎麼知道模型真的收到了它們?」

写给管理者

  • 要拍板的事:决定哪些规则必须每次都成立,把它们放进 hook(平台在每次工具调用时运行的代码),而不是放在 prompt 里。
  • 风险:hook 看到的是调用的文本,看不到命令运行起来之后做了什么。它也可能悄悄失效。按我在 2026 年 10 月看到的 Copilot,超时的 hook 算通过,启动不了的 hook 会挡住所有工具。在一台机器上的一小批 prompt 里,约三分之一送到模型时,没有 hook 本该加上的规则;把它理解为“不少”,不要当成比率。
  • 做对的代价:一个小程序,加一个配置文件,放在代码审查之下。我的通常几十毫秒就跑完。
  • 可以问团队:“hook 慢了或者坏了,我们的规则会怎么样?我们怎么知道模型真的收到了它们?”

The problem

You write a rule: "never edit files in the config folder". The agent follows it nine times. On the tenth, it is deep in a task, the context is long, and the rule is far away. It edits the file. The rule was a sentence the model could weigh against other sentences, and this time it weighed it lower.

What you need is something that does not depend on the model's memory or mood: a piece of code that every tool call must pass, which says yes or no. That is a hook.

A hook is a small program that you write and the platform runs for you at fixed moments. The platform hands it a piece of JSON (a plain text format for data) that says what is happening, such as "the agent wants to run this command". The hook answers, also in JSON. The platform then acts on the answer. The model does not run the hook and cannot skip it.

My first lesson came from a hook that did not work. I used a hook to put the harness's rules in front of the model at the start of each prompt. It ran every time and its output looked right. But when I looked at what the model had actually received, in a small batch of prompts on one machine in October 2026, about a third had no rules in them. I did not keep the exact count, so read "a third" as "a lot", not as a rate. VS Code adds its own reminders to a prompt, and they took the one slot the hook used. The hook returned the right answer and nothing happened. I fixed it by adding a second check at the last point before the text goes to the model, where the whole text is visible, and putting the rules back if they were missing.

The lesson is for every hook: check what the model really received, not what the hook returned. The rest of this chapter is about what a hook can do, how it fails, and what it cannot see.

問題

你寫了一條規則:「絕不要改設定資料夾裡的檔案」。agent 遵守了九次。第十次,它做任務做得很深,上下文很長,規則離得很遠。它改了那個檔案。規則只是一句話,模型可以把它和其他句子放在一起權衡,這一次它把它權衡得比較低。

你需要的是一個不靠模型的記憶或心情的東西:一段每次工具呼叫都必須經過、說「可以」或「不行」的程式碼。這就是 hook。

hook 是你寫、由平台在固定時刻替你執行的小程式。平台交給它一段 JSON(一種表示資料的純文字格式),說明發生了什麼事,例如「agent 想執行這個指令」。hook 也用 JSON 回答。然後平台依照答案行動。模型不執行 hook,也沒辦法跳過它。

我的第一課,來自一個沒有作用的 hook。我用一個 hook,在每個 prompt 開頭,把 harness 的規則放到模型面前。它每次都執行,輸出看起來也對。但我去看模型實際收到什麼時(2026 年 10 月,一台機器上的一小批 prompt),大約三分之一裡面沒有規則。確切的數字我沒有留,所以把「三分之一」讀成「很多」,不要當成比率。VS Code 會在 prompt 裡加上它自己的提醒,它們占掉了 hook 用的那個位置。hook 回傳了對的答案,卻什麼也沒發生。我的修法,是在文字送給模型之前的最後一點,加上第二道檢查,那裡看得到整段文字,規則不在就補回去。

這一課適用於每個 hook:檢查模型真正收到什麼,不是 hook 回傳什麼。這一章其餘的部分,講 hook 能做什麼、怎麼失效,以及它看不到什麼。

问题

你写了一条规则:“永远不要改配置文件夹里的文件”。agent 遵守了九次。第十次,它正深陷一个任务,上下文很长,规则离得很远。它改了那个文件。规则只是一句话,模型可以把它和别的话放在一起掂量,而这一次,它掂量得轻了。

你需要的是不依赖模型记性或心情的东西:一段每次工具调用都必须经过的代码,说行或者不行。这就是 hook。

hook 是你写的一个小程序,平台在固定时机替你运行它。平台交给它一段 JSON(一种表示数据的纯文本格式),说明正在发生什么,比如“agent 想运行这条命令”。hook 同样用 JSON 回答。然后平台按这个回答行事。模型不会运行 hook,也跳不过它。

我的第一个教训,来自一个没起作用的 hook。我用一个 hook,在每个 prompt 开头,把 harness 的规则放到模型面前。它每次都运行,输出看着也对。但是我去看模型实际收到了什么时,在 2026 年 10 月一台机器上的一小批 prompt 里,约有三分之一里没有规则。确切的数我没有记下来,所以把“三分之一”理解为“不少”,不要当成比率。VS Code 会往 prompt 里加它自己的提醒,这些提醒占掉了 hook 用的那个位置。hook 返回了正确的答案,却什么也没发生。我的修法是,在文本送到模型之前的最后一个点上再加第二道检查,那里能看到全部文本,如果规则不在,就把它们补回去。

这个教训适用于每个 hook:检查模型实际收到了什么,而不是 hook 返回了什么。 这一章其余的部分,讲 hook 能做什么、怎么失效、看不到什么。

How it works

The moments

prompt the model tool call the agent stops prompt sent before the call the only place that can refuse after it about to stop The platform runs your code at each of these points, every time.
  1. When you send a prompt, a hook can add words the model will read, such as the rules.
  2. Before a tool runs, a hook sees the tool name and its arguments. It can let the call through, refuse it, or refuse it with a reason.
  3. After the tool ran, a hook can write a record or add a note for the model. It cannot undo what happened.
  4. When the agent is about to stop, a hook can say: not yet. This is how you keep an agent going.
Hooks sit at fixed points of the loop. The platform calls them every time, so the model cannot skip them.

A platform offers a list of moments. These are the ones I use, with the names VS Code gives them in its docs.

Moment What happens What I use it for
A session starts A new chat begins Give the model the session's basic facts
A prompt is sent You press Enter Add the rules; note which task this is
Before a tool call The model asked; nothing has run Refuse a call. Every hard rule is here
After a tool call The tool ran Keep a record; add a note
A subagent starts or stops A helper agent begins or ends Hand it its package; record the end
The agent is about to stop The model wrote an answer Say "not yet", once, if work is open

Only the moment before a tool call can refuse one specific action. It has the one thing a rule needs: the call exists, and has not happened yet. The other moments can watch, record, and add words. (The stop moment can also say "not yet", as described below, but that is not a refusal of an action.) You can see these moments for yourself with the small test at the end of this chapter.

What goes in and what comes out

The hook receives JSON: which event this is, the session, and for a tool call, the tool name and its arguments. Here is a real sample, recorded from VS Code, of what a hook is given after a command has run:

What a hook receives after a terminal command: the event, the tool name, the arguments and the result.
{
  "hook_event_name": "PostToolUse",
  "session_id": "00000000-0000-0000-0000-000000000000",
  "timestamp": "2026-10-02T02:17:08.098Z",
  "cwd": "/Users/user/Developer/DE-agentic-harness",
  "tool_name": "Bash",
  "tool_input": {
    "command": "mkdir -p /Users/user/Developer/DE-agentic-harness/.workspace/sandbox/b5",
    "description": "Create sandbox directory structure"
  },
  "tool_result": {
    "result_type": "success",
    "text_result_for_llm": "\n<shellId: 14 completed with exit code 0>"
  }
}

The hook answers with JSON. There are really only three useful answers:

  • Let it through. (An empty answer counts as no opinion. The platform's normal permission checks still apply.)
  • Refuse, with a reason. The call does not run. The reason is shown to the model and to you.
  • Add a few words for the model to read: a reminder, a status line.

At the stop moment there is a fourth: block the stop, with a reason that is fed back to the model as if it were a new prompt. I allow this once per stop. A hook that blocked every stop would keep the agent running for ever, and you would pay for every turn.

The reason is part of the design. Say why it was refused and what to do instead, or the agent tries the same thing again, or something worse (Asking is not a limit).

Three ways a hook goes wrong

A hook is software. It will fail. What the platform does then decides whether your rule is a fence or a decoration.

What happens What Copilot does (as I observed it in October 2026, and as the VS Code docs say)
The hook runs and refuses The call is stopped, the reason is shown. This works in the default mode and in the modes that skip permission prompts.
The hook cannot start (for example, the language it is written in is not installed) Treated as a refusal: no tool can run, and the screen says little more than "hook errored".
The hook takes too long Treated as a pass, silently. The VS Code docs describe it as falling through to normal permissions.

So the same failure can lock you out or leave the door open, and it depends on how it fails. Which one you want is a design choice. What to choose, and what I chose (let the call through and log the error, and warn when the slowest recent call nears the time limit), is the subject of Enforcement design.

Inside subagents

A subagent is a second agent started for a piece of the work (Use subagents sparingly). It runs in its own session. In Copilot today, its tool calls go through the hooks as well, and the event carries the id of the parent session. So a rule set for the main agent also holds for the helpers it starts. I would not assume this on another platform without testing it. I have not.

What a hook cannot see

This is the part I most want you to remember.

a command hook sees the text of the call the command runs its effect is not seen variable paths, scripts: unseen
  1. A hook sees the call: the tool name and the text of the command. It decides before anything runs.
  2. Once a command is let through, the hook is out of the picture. A script it starts can do things the command line never showed.
  3. The text itself can hide the effect: a path built from variables, or a script written first and run afterwards.
A hook sees calls, not effects. Where the effect matters, limit what the agent can reach.

It sees calls, not effects. For a terminal command, the hook reads the text of the command. It can see "write to this path". It cannot see a path built from variables, or a script that was written a minute ago and is only run now. Once the command is let through, the hook is out of the picture. So a hook on terminal commands stops the common spellings. It does not stop an agent set on getting around it. The VS Code docs say the same: hooks are executable code and not a substitute for enforced permissions or sandboxing. For things that must never be touched, do not rely on the hook alone (Least privilege).

It does not know which agent is calling. In Copilot today, the event does not carry the name of the main agent. So "this agent is allowed to" cannot be a rule: any agent could pass for it. If rights must differ, they have to come from something the agent cannot set, such as a switch the person turns on in a terminal.

It does not run everywhere. In my measurements, the repository's hooks did not run when I used the command-line mode of Copilot (no window). A setting that looks like an off switch did not stop them in the newer sessions. A company policy can turn hooks off for a workspace. And the hook file is read when the window starts, so a change needs a reload. These are the facts as I found them in October 2026; they will change. Look at the platform's current docs, which also say hooks are in Preview today.

It can lose its message. The story at the top: output from a hook may never reach the model. Test the delivery, not only the hook.

Other things that stand in the loop

A hook is not the only thing between the model and the world. A wrapper (a small program you call instead of the raw command), an MCP server (MCP) and a proxy between the platform and the model each see only what is routed through them, and the agent can route around them. The difference: the platform promises to call the hook. For the built-in tools and for subagents, I saw every call pass through it; I have not tested MCP tools.

Test your own setup

Three questions for any rule you care about:

  1. Is it written in a prompt, or in a hook? If it is in a prompt, it is a request.
  2. What does the hook see when the rule is broken? The call text, or the effect?
  3. What happens when the hook itself breaks or is slow?

A test you can run today. Write the smallest hook your platform allows. It only appends the event name and the tool name to a file. Use your agent for a small task, then read the file. You will see every moment in the table above, in order, and how many there are. It is the quickest way to understand the loop. Follow the VS Code hooks docs for the file format.

原理

那些時刻

prompt 模型 工具呼叫 agent 要停了 送出 prompt 呼叫之前 唯一能拒絕的地方 呼叫之後 快要停下 平台在這幾個點,每一次都會執行你的程式。
  1. 你送出 prompt 時,hook 可以加幾句話給模型讀,例如規則。
  2. 工具執行之前,hook 看得到工具名稱和參數。它可以放行、拒絕,或附上理由拒絕。
  3. 工具執行之後,hook 可以寫一筆紀錄,或給模型加一句話。已經發生的事它改不了。
  4. agent 快要停下時,hook 可以說:還不行。想讓 agent 繼續做,就靠這一點。
hook 站在循環裡固定的幾個點上。平台每次都會呼叫它,模型跳不過去。

平台提供一份時刻的清單。下面是我用的,名字是 VS Code 在它的文件裡給的。

時刻 發生什麼 我拿它做什麼
會話開始 新的對話開始 把這個會話的基本事實給模型
送出 prompt 你按了 Enter 加上規則;記下這是哪個任務
工具呼叫之前 模型提出了要求;什麼都還沒執行 拒絕一次呼叫。每條硬規則都在這裡
工具呼叫之後 工具已經執行了 留下紀錄;加一則備註
子 agent 開始或結束 幫手 agent 開始或結束 把它的包裹交給它;記下結束
agent 快要停下來 模型寫出了回答 還有工作沒做完,就說一次「還沒」

只有工具呼叫之前這個時刻,能拒絕某一個具體的動作。它有規則需要的那樣東西:呼叫已經存在,但還沒發生。其他時刻能看、能記錄、能加文字。(停止的時刻也可以說「還沒」,見下面,但那不是拒絕一個動作。)你可以用這一章結尾的小測試,自己看到這些時刻。

什麼進去,什麼出來

hook 收到 JSON:這是哪個事件、哪個會話,如果是工具呼叫,還有工具名稱和它的參數。下面是從 VS Code 記錄下來的真實樣本,是一個指令執行完之後,hook 收到的東西:

hook 在終端機指令之後收到的東西:事件、工具名稱、參數和結果。
{
  "hook_event_name": "PostToolUse",
  "session_id": "00000000-0000-0000-0000-000000000000",
  "timestamp": "2026-10-02T02:17:08.098Z",
  "cwd": "/Users/user/Developer/DE-agentic-harness",
  "tool_name": "Bash",
  "tool_input": {
    "command": "mkdir -p /Users/user/Developer/DE-agentic-harness/.workspace/sandbox/b5",
    "description": "Create sandbox directory structure"
  },
  "tool_result": {
    "result_type": "success",
    "text_result_for_llm": "\n<shellId: 14 completed with exit code 0>"
  }
}

hook 用 JSON 回答。真正有用的答案只有三種:

  • 放行。(空的答案算沒意見。平台正常的權限檢查仍然適用。)
  • 拒絕,附上原因。呼叫不會執行。原因會顯示給模型和你看。
  • 加幾句話給模型讀:一則提醒、一行狀態。

在停止的時刻還有第四種:擋下這次停止,附上一個原因,原因會像新的 prompt 一樣餵回給模型。我每次停止只允許這樣做一次。每次停止都擋的 hook,會讓 agent 永遠跑下去,而你要為每一輪付錢。

原因是設計的一部分。寫清楚為什麼被拒絕、該改做什麼,不然 agent 會再試同一件事,或更糟的事(詢問不是限制)。

hook 出錯的三種方式

hook 是軟體。它會出錯。平台那時怎麼處理,決定了你的規則是圍欄還是裝飾。

發生什麼 Copilot 怎麼做(我在 2026 年 10 月觀察到的,也是 VS Code 文件說的)
hook 執行了並拒絕 呼叫被擋下,原因顯示出來。在預設模式,以及跳過權限提示的模式下都有效。
hook 啟動不了(例如寫它用的語言沒裝) 當成拒絕:沒有任何工具能執行,畫面上也只說「hook errored」之類的話。
hook 花太久 當成通過,而且沒有任何通知。VS Code 文件說,它會落到正常的權限檢查。

所以同一種失敗,可能把你鎖在外面,也可能讓門開著,取決於它怎麼失敗。你想要哪一種,是設計的選擇。該選什麼,以及我選了什麼(放行這次呼叫並記錄錯誤,最近最慢的一次呼叫接近時間上限時發出警告),是 把執行層當軟體來設計 的主題。

在子 agent 裡面

子 agent 是為了一部分工作而啟動的第二個 agent(慎用子 agent)。它在自己的會話裡執行。在今天的 Copilot 裡,它的工具呼叫也會經過 hook,事件裡帶著父會話的 id。所以為主 agent 設的規則,對它啟動的幫手也成立。換成別的平台,我不會在沒測過的情況下假設這點。我沒有測過。

hook 看不到什麼

這是我最希望你記住的部分。

一條終端機指令 hook 看得到呼叫的文字 指令開始執行 它做了什麼,看不到 變數拼的路徑、先寫好的腳本:看不到
  1. hook 看到的是呼叫:工具名稱和指令的文字。它在任何東西執行之前就決定。
  2. 指令一旦放行,hook 就退出畫面了。它啟動的腳本做什麼,指令列上看不出來。
  3. 文字本身可能藏住後果:用變數拼出來的路徑,或先寫好、之後才執行的腳本。
hook 看得到呼叫,看不到後果。後果要緊的地方,就限制 agent 碰得到什麼。

它看到的是呼叫,不是效果。對終端機指令,hook 讀的是指令的文字。它看得到「寫入這個路徑」。它看不到用變數拼出來的路徑,也看不到一分鐘前才寫好、現在才執行的腳本。指令一旦被放行,hook 就不在畫面裡了。所以終端機指令上的 hook,擋得住常見的寫法。它擋不住一個一心要繞過它的 agent。VS Code 文件也這麼說:hook 是可執行的程式碼,不能代替強制的權限或沙箱。對絕不能被碰的東西,不要只靠 hook(有些東西根本不給)。

它不知道是哪個 agent 在呼叫。在今天的 Copilot 裡,事件不帶主 agent 的名字。所以「這個 agent 被允許」不能成為規則:任何 agent 都可以冒充。如果權限必須不同,就得來自 agent 設不了的東西,例如由人在終端機裡打開的開關。

它不是到處都會執行。在我的測量裡,我用 Copilot 的命令列模式(沒有視窗)時,倉庫的 hook 沒有執行。一個看起來像關閉開關的設定,在較新的會話裡也沒能擋住它們。公司的政策可以為一個工作區關掉 hook。而且 hook 檔是在視窗啟動時讀的,所以改了要重新載入。這些是我 2026 年 10 月找到的事實;它們會變。請看平台目前的文件,文件也說 hook 現在是 Preview。

它可能丟掉自己的訊息。開頭的故事:hook 的輸出可能永遠到不了模型。要測的是送達,不只是 hook。

迴圈裡其他站著的東西

hook 不是模型和外面世界之間唯一的東西。包裝器(你呼叫來代替原始指令的小程式)、MCP server(MCP server:插工具的標準接口),以及平台和模型之間的代理,各自只看得到經過它們的東西,而 agent 可以繞過它們。差別在於:平台保證會呼叫 hook。內建工具和子 agent,我看過每次呼叫都經過它;MCP 工具我沒有測過。

測你自己的設定

對你在乎的任何規則,問三個問題:

  1. 它是寫在 prompt 裡,還是 hook 裡?如果在 prompt 裡,它就是請求。
  2. 規則被破壞時,hook 看到什麼?呼叫的文字,還是效果?
  3. hook 自己壞掉或很慢的時候,會怎樣?

今天就能跑的測試。寫出你的平台允許的最小 hook。它只把事件名稱和工具名稱附加到一個檔案裡。用你的 agent 做一件小任務,然後讀這個檔案。你會依序看到上面表格裡的每個時刻,以及有幾個。這是理解迴圈最快的辦法。檔案格式請照 VS Code hooks docs。

原理

那些时机

prompt 模型 工具调用 agent 要停了 发出 prompt 调用之前 唯一能拒绝的地方 调用之后 即将停止 平台在这几个点,每一次都会运行你的代码。
  1. 你发出 prompt 时,hook 可以加几句话给模型读,例如规则。
  2. 工具运行之前,hook 看得到工具名和参数。它可以放行、拒绝,或者附上原因拒绝。
  3. 工具运行之后,hook 可以写一条记录,或者给模型加一句话。已经发生的事它改不了。
  4. agent 即将停止时,hook 可以说:还没完。想让 agent 接着干,就靠这一点。
hook 站在循环里固定的几个点上。平台每次都会调用它,模型跳不过去。

平台提供一张时机的清单。下面是我用到的几个,名字是 VS Code 在它文档里起的。

时机 发生了什么 我拿它做什么
会话开始 一个新对话开始 把这次会话的基本情况告诉模型
发出 prompt 你按下回车 加上规则;记下这是哪个任务
工具调用之前 模型提出了请求;还没有运行任何东西 拒绝一次调用。所有硬性规则都在这里
工具调用之后 工具已经运行 留一份记录;加一条备注
子 agent 启动或停止 一个帮手 agent 开始或结束 把它的材料交给它;记下结束
agent 即将停止 模型写完了一个回答 如果还有活没干完,说一次“还没完”

只有工具调用之前这个时机,能拒绝某一个具体的动作。规则需要的东西它都有:调用已经存在,但还没有发生。其他时机可以观察、记录、添几句话。(停止的时机也能说“还没完”,下面会讲,但那不是对某个动作的拒绝。)你可以用本章末尾的小测试,亲眼看看这些时机。

进去什么,出来什么

hook 收到的是 JSON:这是什么事件、哪个会话,如果是工具调用,还有工具名和它的参数。下面是从 VS Code 录下来的一个真实样本,是一条命令运行完之后,hook 收到的内容:

hook 在一条终端命令运行完之后收到的内容:事件、工具名、参数和结果。
{
  "hook_event_name": "PostToolUse",
  "session_id": "00000000-0000-0000-0000-000000000000",
  "timestamp": "2026-10-02T02:17:08.098Z",
  "cwd": "/Users/user/Developer/DE-agentic-harness",
  "tool_name": "Bash",
  "tool_input": {
    "command": "mkdir -p /Users/user/Developer/DE-agentic-harness/.workspace/sandbox/b5",
    "description": "Create sandbox directory structure"
  },
  "tool_result": {
    "result_type": "success",
    "text_result_for_llm": "\n<shellId: 14 completed with exit code 0>"
  }
}

hook 用 JSON 回答。真正有用的回答其实只有三种:

  • 放行。(空的回答算没有意见。平台正常的权限检查仍然适用。)
  • 拒绝,并附上原因。这次调用不会运行。原因会显示给模型,也显示给你。
  • 加几句话给模型读:一条提醒,一行状态。

在停止的时机,还有第四种:挡住这次停止,并附上一个原因,这个原因会像一个新 prompt 一样喂回给模型。我每次停止只允许挡一次。每次停止都挡的 hook,会让 agent 永远运行下去,而每一轮你都得付钱。

原因是设计的一部分。要说明为什么拒绝、应该改做什么,否则 agent 会再试同样的事,或者更糟的事(询问不是限制)。

hook 出问题的三种方式

hook 是软件,它会出问题。出问题时平台怎么处理,决定了你的规则是围栏,还是摆设。

发生了什么 Copilot 怎么处理(我在 2026 年 10 月观察到的,也是 VS Code 文档里说的)
hook 运行了,并且拒绝 调用被拦住,原因会显示出来。这在默认模式下有效,在跳过权限提示的模式下也有效。
hook 启动不了(比如它所用的语言没有安装) 当作拒绝:没有任何工具能运行,屏幕上除了“hook 出错”,几乎没有别的说明。
hook 花的时间太长 当作通过,不吭声。VS Code 文档的说法是,回落到正常的权限检查。

所以同一种故障,可能把你锁在门外,也可能让大门敞开,取决于它是怎么失败的。你想要哪一种,是一个设计选择。该怎么选,以及我选了什么(放行这次调用并记下错误,最近最慢的一次调用接近时间上限时发出警告),是把执行层当软件来设计的主题。

在子 agent 里

子 agent 是为了某一部分工作而开的第二个 agent(慎用子 agent)。它在自己的会话里运行。在今天的 Copilot 里,它的工具调用也会经过 hook,事件里还带着父会话的 id。所以给主 agent 定的规则,对它开的帮手也成立。换一个平台,我不会不经测试就这样假设。我没有测过。

hook 看不到什么

这是我最想让你记住的部分。

一条终端命令 hook 看得到调用的文本 命令开始运行 它做了什么,看不到 变量拼的路径、先写好的脚本:看不到
  1. hook 看到的是调用:工具名和命令的文本。它在任何东西运行之前就做决定。
  2. 命令一旦放行,hook 就出局了。它启动的脚本做什么,命令行上看不出来。
  3. 文本本身可能藏住效果:用变量拼出来的路径,或先写好、之后才运行的脚本。
hook 看得到调用,看不到效果。效果要紧的地方,就限制 agent 够得着什么。

它看到的是调用,不是效果。对终端命令,hook 读的是命令的文本。它能看到“写入这个路径”。它看不到用变量拼出来的路径,也看不到一个一分钟前才写好、现在才运行的脚本。命令一旦被放行,hook 就出局了。所以,针对终端命令的 hook,能拦住常见的写法。拦不住铁了心要绕过它的 agent。VS Code 文档说的也是这一点:hook 是可执行的代码,不能替代强制执行的权限或沙箱。对那些绝对不能碰的东西,不要只靠 hook(有些东西根本不给)。

它不知道是哪个 agent 在调用。在今天的 Copilot 里,事件里没有主 agent 的名字。所以“这个 agent 被允许”做不成规则:任何 agent 都可以冒充它。如果权限必须不同,就得来自 agent 设置不了的东西,比如由人在终端里打开的开关。

它不是到处都会运行。在我的测量里,我用 Copilot 的命令行模式(没有窗口)时,仓库里的 hook 没有运行。有一个看起来像关闭开关的设置,在较新的会话里并没有让它们停下来。公司策略可以为某个工作区关掉 hook。而且 hook 文件是在窗口启动时读的,所以改了之后要重新加载。这些是我在 2026 年 10 月发现的情况;它们会变。请看平台当前的文档,文档里也说 hook 现在还是 Preview。

它可能丢掉自己的消息。开头那个故事:hook 的输出可能根本没到达模型。要测消息有没有送到,不只是测 hook。

循环里其他站岗的东西

hook 不是模型和外部世界之间唯一的东西。包装器(一个你调用它而不是调用原始命令的小程序)、MCP server(MCP server:接工具的标准接口),以及平台和模型之间的代理,每个都只看得到经过它们的东西,而 agent 可以绕过它们。区别在于:平台承诺会调用 hook。对内置工具和子 agent,我见过每次调用都经过它;MCP 工具我没有测过。

测一测你自己的配置

对任何你在乎的规则,问三个问题:

  1. 它是写在 prompt 里,还是写在 hook 里?如果在 prompt 里,它就是请求。
  2. 规则被违反时,hook 看到的是什么?调用的文本,还是效果?
  3. hook 自己坏了或者慢了,会怎么样?

一个今天就能做的测试。写出你的平台允许的最小的 hook。它只把事件名和工具名追加到一个文件里。用你的 agent 做一个小任务,然后读那个文件。你会按顺序看到上面表格里的每个时机,以及一共有多少个。这是理解循环最快的办法。文件格式请看 VS Code hooks 文档。

Costs and traps

A timeout is a silent pass. Of the three failures above, this is the one that matters most in a team: a rule that is not enforced and nobody is told. Watch the time your hook takes, and read Enforcement design before you choose what happens on failure.

A hook runs on every call. If it is slow, everything is slow. Mine normally takes a few dozen milliseconds. Keep it cheap, and put a limit on what it may do.

A hook is code you must trust. It runs on your machine and reads whatever the agent sends. Never put the agent's text straight into a shell command inside a hook. In a team, treat the hook file like any other code that guards something: change it through review.

A hook is a feature of a platform that is still changing. VS Code labels it Preview. What I wrote in the failure table is what I saw; check it again after each update.

The reason can be too good. A refusal that explains exactly how to get around the rule teaches the model to do that. Say what to do instead, not how to dodge.

代價和陷阱

逾時是無聲的通過。上面三種失敗裡,這是對團隊最重要的一種:規則沒有被執行,卻沒有人被告知。要留意你的 hook 花的時間,並在選擇失敗時怎麼辦之前,先讀 把執行層當軟體來設計。

hook 每次呼叫都會執行。它慢,一切都慢。我的通常幾十毫秒。要讓它便宜,並限制它能做的事。

hook 是你必須信任的程式碼。它在你的機器上執行,讀 agent 送來的任何東西。絕不要在 hook 裡,把 agent 的文字直接放進 shell 指令。在團隊裡,把 hook 檔當成任何其他守著東西的程式碼:改動要經過審查。

hook 是一個仍在變動的平台的功能。VS Code 把它標為 Preview。我在失敗表裡寫的是我看到的;每次更新後都再確認一次。

原因也可能太好。一個把怎麼繞過規則說得清清楚楚的拒絕,會教模型去那樣做。說該改做什麼,不要說怎麼閃躲。

代价和坑

超时就是悄悄放行。上面三种故障里,这一种在团队里最要紧:规则没有强制执行,却没人知道。盯着你的 hook 花多长时间,并在选择失败时怎么处理之前,先读把执行层当软件来设计。

hook 在每次调用上都运行。它如果慢,一切都慢。我的通常几十毫秒。让它保持廉价,并限制它能做什么。

hook 是你必须信任的代码。它在你的机器上运行,读 agent 发来的任何东西。永远不要把 agent 的文本直接放进 hook 里的 shell 命令。在团队里,把 hook 文件当作任何其他守着什么东西的代码:通过审查来改。

hook 是一个仍在变化的平台上的功能。VS Code 把它标为 Preview。我在故障表里写的是我看到的;每次更新之后都再查一遍。

原因可能写得太好。一个把怎么绕过规则解释得清清楚楚的拒绝,等于教模型这么做。说该做什么,不要说怎么躲。

What the industry says Industry practice

VS Code lists the moments I used (session start, prompt submitted, before and after a tool, subagent start and stop, agent stop) and states that a preToolUse hook can return a deny with a reason. It also notes that a timeout falls through to normal permissions and that the feature is in Preview. (Agent hooks in VS Code)

I have not compared this with other platforms' hooks in detail here. Their event names and what they cover differ.

業界怎麼說 業界做法

VS Code 列出了我用的那些時刻(會話開始、送出 prompt、工具前後、子 agent 開始和結束、agent 停止),並說明 preToolUse hook 可以回傳一個附原因的拒絕。它也指出逾時會落到正常的權限檢查,以及這個功能還在 Preview。(Agent hooks in VS Code)

我在這裡沒有詳細比較其他平台的 hook。它們的事件名稱和涵蓋的範圍都不同。

业界怎么说 业界做法

VS Code 列出了我用到的那些时机(会话开始、提交 prompt、工具前后、子 agent 的启动和停止、agent 停止),并说明 preToolUse hook 可以返回带原因的拒绝。它还指出,超时会回落到正常的权限检查,而且这个功能还是 Preview。(Agent hooks in VS Code)

我在这里没有把它和其他平台的 hook 做详细比较。它们的事件名和覆盖的范围都不一样。

When to delete it Industry practice

A hook for a rule stays as long as the platform lets rules in prompts be ignored. The reasoning does not retire. The parts I would delete first are the workarounds: the second check for lost injection goes when the platform delivers hook output reliably, and the timing watch goes when a timeout is reported instead of silently passing. If the platform one day offers a native, enforced policy (a rule file it checks itself), I would move the hard rules there and keep hooks for records and reminders.

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

只要平台還允許 prompt 裡的規則被忽略,規則用的 hook 就會留著。道理不會退役。我最先會刪的,是各種繞路的做法:平台可靠地送達 hook 的輸出時,防止注入遺失的第二道檢查就可以拿掉;逾時改成會被回報、不再無聲通過時,計時的監看也可以拿掉。如果有一天平台提供原生的、強制執行的政策(一個它自己檢查的規則檔),我會把硬規則搬到那裡,hook 留給紀錄和提醒。

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

只要平台还允许 prompt 里的规则被忽略,针对规则的 hook 就要留着。背后的道理不会退役。我最先删的,是那些绕弯的补丁:等平台能可靠地送达 hook 的输出,为丢失注入而加的第二道检查就可以去掉;等超时会被报告,而不是悄悄放行,对耗时的盯防就可以去掉。如果哪天平台提供原生的、强制执行的策略(一个它自己会检查的规则文件),我会把硬性规则搬到那里,hook 留给记录和提醒。

Try it on your own setup

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

Find out whether this project has agent hooks configured (look in the project and editor settings and any hooks folder). If it does, list each one: which moment it runs at, what it checks, what it does when it refuses, and what the reason it shows says. Then say what would happen if the hook program failed to start or ran too slowly, based on the platform docs. If there are no hooks, list the three rules in the instruction files that would be worth turning into one. Do not change any files.

在你自己的環境試試

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

查一下這個專案有沒有設定 agent hook(看專案和編輯器的設定,以及任何 hooks 資料夾)。如果有,列出每一個:它在哪個時刻執行、檢查什麼、拒絕時做什麼,以及它顯示的原因說了什麼。然後依照平台文件,說明 hook 程式啟動不了或執行太慢時會發生什麼。如果沒有 hook,列出指令檔裡三條值得改成 hook 的規則。不要改任何檔案。

在你自己的环境里试试

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

查一下这个项目有没有配置 agent 的 hook(看项目和编辑器的设置,以及所有 hooks 文件夹)。如果有,逐个列出:在哪个时机运行、检查什么、拒绝时做什么、它显示的原因写了什么。然后根据平台文档,说明 hook 程序如果启动不了或者运行太慢,会发生什么。如果没有 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 one hook entry for all moments, a gate that refuses calls, and the logs that show what it did. After the setup above, type:

/harness-rookie-wondering I have read the chapter "Hooks, the point every call passes through". Teach me how this harness uses hooks: which moments it listens to, what the gate refuses and why, and what happens when the hook itself fails. Open the real files with me and show me a refusal and its reason.

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

在 harness 裡探索

harness 的所有時刻共用一個 hook 入口,有一道拒絕呼叫的門,還有顯示它做了什麼的紀錄。照上面的說明準備好之後,輸入:

/harness-rookie-wondering 我讀完了「Hooks:每次呼叫都會經過的執行點」這一章。請教我這個 harness 怎麼用 hook:它聽哪些時刻、門拒絕什麼和為什麼,以及 hook 自己失敗時會怎樣。帶我打開真實的檔案,讓我看一次拒絕和它的原因。

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

在 harness 里探索

harness 对所有时机只有一个 hook 入口,有一道拒绝调用的关卡,还有记录它做了什么的日志。按上面的说明准备好之后,输入:

/harness-rookie-wondering 我读完了“Hook:每次调用都会经过的执行点”这一章。请教我这个 harness 是怎么用 hook 的:它监听哪些时机、关卡拒绝什么以及为什么,还有 hook 自己出问题时会怎么样。带我打开真实的文件,让我看一次拒绝和它的原因。

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