refactor: organize agent harness courses

learn-pi-agent/s05_tool_hook_boundary/README.md

@@ -0,0 +1,229 @@
+# s05: Tool Hook Boundary — 执行前后各留一个口子
+
+> *执行是直线，插口在两头。*
+> **Pi 边界**：工具插口边界 —— 执行这个动作被掰成 before / run / after，中间不变，两头可插。
+
+[上一节：s04](../s04_evented_tool_loop/) → `s05` → [下一节：s06](../s06_turn_snapshot/)
+
+---
+
+## 问题
+
+s04 里，provider 一请求工具，core 立刻就执行了——中间没有任何介入的余地。
+
+但真实使用中，执行前后往往要做事：执行前想检查"这个工具现在能不能用""参数合不合规"，执行后想"给结果脱个敏""记一条日志"。如果这些都写死在执行逻辑里，每改一次规则就得动 core，没法按情况调整。
+
+s05 要在执行这个动作的**前后**各留一个插口。
+
+---
+
+## 解决方案
+
+两个插口：
+
+| 插口 | 时机 | 能做什么 |
+| --- | --- | --- |
+| `beforeToolCall` | 执行前 | 放行（allow）或拦下（block，带原因） |
+| `afterToolCall` | 执行后 | 保留结果，或改写后再交出去 |
+
+一个 `executeToolCall` 把执行流程串成三段：
+
+```text
+beforeToolCall  →  registry.run()  →  afterToolCall
+```
+
+中间那段还是 s04 的 `registry.run`，**ToolRegistry 本身不变**——hook 只是套在外面的一层，不改 core 的执行逻辑。
+
+拦下（block）时 handler 根本不会跑；handler 抛错还是按 s04 的规矩被包成一条结果消息，循环继续。
+
+---
+
+## 工作原理
+
+**先定义插口的返回。** 执行前要么放行、要么拦下并给个原因。
+
+```ts
+export type BeforeToolCallResult =
+  | { type: "allow" }
+  | { type: "block"; reason: string };
+
+export type ToolHooks = {
+  beforeToolCall?: (call: ToolCall) => BeforeToolCallResult;
+  afterToolCall?: (call: ToolCall, result: string) => string;
+};
+```
+
+两个插口都可选——不配就相当于全放行、不改写。
+
+**把三段串起来。** `executeToolCall` 就是 before → run → after。block 时直接返回，handler 不执行；handler 抛错在这里收口，不向上传。
+
+```ts
+export function executeToolCall(
+  registry: ToolRegistry,
+  hooks: ToolHooks,
+  call: ToolCall,
+): ToolResultMessage {
+  const before = hooks.beforeToolCall?.(call) ?? { type: "allow" };
+
+  if (before.type === "block") {
+    return { role: "toolResult", toolCallId: call.id, content: `blocked: ${before.reason}` };
+  }
+
+  let result: string;
+  try {
+    result = registry.run(call);
+  } catch (error) {
+    result = `error: ${error instanceof Error ? error.message : String(error)}`;
+  }
+
+  const finalResult = hooks.afterToolCall?.(call, result) ?? result;
+  return { role: "toolResult", toolCallId: call.id, content: finalResult };
+}
+```
+
+**接到循环里。** s04 的 `runEventedToolLoop` 现在 `tool_call` 这一步不再直接调 `registry.run`，而是调 `executeToolCall`。对循环来说，拿到的还是一个 ToolResultMessage，流程没变——只是中间多过了一层插口。
+
+> 这一节真正建立的是**工具插口边界**：执行被掰成 before / run / after 三段，中间那段是 core 的固定逻辑，两头是可以从外面配置的钩子。后面 s11 的权限检查会直接接到 beforeToolCall 上，但"执行本身不动、规则插在两头"这条规矩，从这里立起来。
+
+---
+
+## 试一下
+
+运行（放行路径）：
+
+```sh
+npm run s05
+```
+
+输出类似：
+
+```text
+s05: Tool Hook Boundary
+
+[user]
+复读一下 hi
+
+message_start
+tool_call: echo
+[beforeToolCall]
+allow: echo
+[afterToolCall]
+echo -> hi
+tool_result: checked: hi
+message_end: toolUse
+message_start
+text_delta: 工具结果是：checked: hi
+message_end: stop
+
+[assistant]
+content: 工具结果是：checked: hi
+stopReason: stop
+```
+
+再运行（拦截路径）：
+
+```sh
+npm run s05 -- --case blocked
+```
+
+输出类似：
+
+```text
+message_start
+tool_call: dangerous
+[beforeToolCall]
+block: dangerous
+tool_result: blocked: 这个工具在演示里被禁用
+message_end: toolUse
+message_start
+text_delta: 工具结果是：blocked: 这个工具在演示里被禁用
+message_end: stop
+```
+
+观察重点：放行时 handler 跑了、afterToolCall 把结果改成了 `checked: ...`；拦截时 handler 根本没跑（"不该执行到这里"从未出现），结果直接是 `blocked: ...`。
+
+---
+
+## 接入主线
+
+s05 在 s04 上累积。相对 s04 的变更：
+
+| 组件 | s04 | s05 |
+| --- | --- | --- |
+| 新增类型 | — | `BeforeToolCallResult` / `ToolHooks` |
+| 新增函数 | — | `executeToolCall`（把 s04 内联的 run + 错误捕获收口到这里） |
+| `runEventedToolLoop` | `(state, provider, registry, userInput, output)` | 多一个 `hooks` 参数；`tool_call` 走 `executeToolCall` |
+| `ToolRegistry` | `register / getSpecs / run` | **不变**（R2：hook 是外层装饰） |
+
+**焊接点**：循环内 `tool_call` → `executeToolCall(registry, hooks, call)` → ToolResultMessage 进 messages。registry 未改动，hook 套在执行外面。
+
+---
+
+## 接下来
+
+现在每一轮执行，信息都是现场从各个对象里读的。如果一轮开始后外部又改了工具列表或模型名，这一轮就会变得说不清。
+
+下一节会把一轮开始时用到的信息，先集中拍成一份快照。
+
+进入下一节：[s06](../s06_turn_snapshot/)。
+
+---
+
+<details>
+<summary>Pi 源码溯源：beforeToolCall / afterToolCall 的真实位置</summary>
+
+教学版的 hook 是 `executeToolCall` 里的两个可选函数。Pi 的 hook 长在并发工具执行的 prepare/finalize 两侧，且能拿到比教学版丰富得多的上下文。
+
+### 源码在哪
+
+- `packages/agent/src/types.ts:83` — `BeforeToolCallContext` / `AfterToolCallContext`
+- `packages/agent/src/types.ts:262` — `beforeToolCall` / `afterToolCall` 签名
+- `packages/agent/src/agent-loop.ts:581` — beforeTool 触发点
+- `packages/agent/src/agent-loop.ts:676` — afterTool 触发点
+
+### hook 能拿到什么
+
+教学版的 `beforeToolCall(call)` 只拿到 ToolCall。Pi 的 context（`types.ts:83`）丰富得多：
+
+```ts
+interface BeforeToolCallContext {
+  assistantMessage: AgentMessage;   // 触发这次工具调用的那条 assistant 消息
+  toolCall: AgentToolCall;          // 工具调用本身
+  args: validatedArgs;              // 已经校验过的参数
+  context: AgentContext;            // 本轮的完整快照（s06）
+}
+```
+
+hook 能看到"是哪条 assistant 消息要调这个工具""本轮的完整上下文是什么"——不只是孤立的调用。
+
+### beforeTool 能 block
+
+教学版的 block 返回 `{ block, reason }`。Pi 一致（`agent-loop.ts:581`）：
+
+```ts
+if (config.beforeToolCall) {
+  const beforeResult = await config.beforeToolCall(
+    { assistantMessage, toolCall, args, context }, signal);
+  if (beforeResult?.block) {
+    return { kind: "immediate",
+             result: createErrorToolResult(beforeResult.reason || "blocked"),
+             isError: true };
+  }
+}
+```
+
+block 后工具跳过执行，直接生成一条错误结果发回去——和教学版语义一致，但 Pi 把它包成 `kind: "immediate"`（立即返回），无缝接入 s04 的并发执行框架。
+
+### afterTool 能改写结果
+
+教学版的 `afterToolCall(call, result) => string` 只能改 content。Pi 的 `afterToolCall` 能改更多字段（错误标记、terminate 标志等），是字段级覆盖、非深度合并。
+
+### hook 是异步的，且能被中断
+
+教学版的 hook 是同步函数。Pi 的 hook 是 `async`，且都带 `signal: AbortSignal`——用户中断时 hook 也能及时收手。这呼应 s01 的 AbortController 贯穿到每一层。
+
+### 一句话
+
+教学版的 `executeToolCall = before → run → after` 立的是"执行前后留插口"。Pi 把这两个插口坐实在并发执行的 prepare/finalize 两侧，context 更丰富（assistant 消息 + 本轮快照）、异步且可中断。后面 s11 的权限检查会直接接到 beforeToolCall 上。
+
+</details>