用一个 tool_call 处理器阻止强制推送
使用一个 tool_call 扩展,在破坏性 git 命令运行之前拒绝它们,而普通命令原样通过。
一个 tool_call 处理器在它点名的那个工具之前运行,所以它可以拒绝这次调用。这个页面上的守卫阻止破坏性的 git 命令——强制推送、reset --hard 和 git clean -f——并且在没有人可问(没有 UI)时,它拒绝而不是默默放行。这些情形通过一个 faux provider 在真实会话中运行,所以你看到的是守卫,不是一个真实模型。
运行它
这个守卫就是整个文件,被精确复制于此:
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
const BLOCKED = [
/\bgit\s+push\b[^\n]*(--force|-f)\b/,
/\bgit\s+reset\s+--hard\b/,
/\bgit\s+clean\b[^\n]*-[a-z]*f/,
];
export default function (pi: ExtensionAPI) {
pi.on("tool_call", async (event, ctx) => {
if (event.toolName !== "bash" && event.toolName !== "powershell") return;
const raw = JSON.stringify(event.input);
const hit = BLOCKED.find((re) => re.test(raw));
if (!hit) return;
if (!ctx.hasUI) {
// No way to ask. Refuse rather than allow silently.
return { block: true, reason: `Guard blocked: ${hit.source}` };
}
const ok = await ctx.ui.confirm(
"This command rewrites history or destroys work. Allow?",
raw.slice(0, 200),
);
if (ok) return;
return { block: true, reason: "Blocked by review-guard extension" };
});
}每个模式都测试 JSON.stringify(event.input),所以埋在一条更长命令里的强制推送仍然会匹配。当 ctx.hasUI 为 false 时,处理器立刻阻止;有 UI 时它先确认,而每个 block 都带一个 reason。不同于第 11 章那个守卫——它无条件阻止强制推送,并且只匹配 bash 和 edit——这个守卫覆盖 powershell、reset --hard 和 git clean,并且在有人可问时提问。用 pi --extension ./guard.ts 加载它。
预期结果
这是已观察:guard.test.ts 把每条命令驱动进一个真实会话;其中包含 touch ran.flag,所以"它被拦住了吗?“是一个存在或不存在的文件,而不是一次推断。
| 脚本化的调用 | 结果 |
|---|---|
touch ran.flag && git push --force origin main |
isError: true,文本匹配 /Guard blocked/,并且 ran.flag 永远不会被创建 |
touch ran.flag |
isError: false,并且 ran.flag 存在——普通命令不被触碰 |
git reset --hard HEAD~1 |
isError: true |
touch ran.flag && git push -f origin main via guard-status.ts |
isError: true,理由点明 --force-with-lease,没有文件 |
any command, when a tool_call handler throws |
isError: true,没有文件——它失败时关闭 |
机制与局限
有文档记载: tool_call 在执行之前触发,并接受 { block: true, reason };ctx.hasUI 覆盖交互式和 RPC 对话框,ctx.mode === "tui" 覆盖只限于终端的 UI。它还说明一个 tool_call 处理器的失败会作为一种故障保护而阻止该工具,而一次工具执行的失败会变成一个错误结果。处理器按扩展加载顺序运行,而来自一条助手消息的工具调用可能并行运行。
已观察: guard.test.ts 通过一个带有脚本化 provider 的真实 AgentSession 驱动真实的处理器,并断言上面每一行,包括被阻止的或抛出异常的处理器不会留下任何文件。guard-status.ts 添加一个 /guard-status 命令,它的计数器在 session_start(每个会话一次)里重置,而不是在工厂函数里。
局限: 这是一个启发式,不是一道边界。它匹配一个序列化后的字符串,所以 git push origin +main 会在不匹配的情况下重写一个 ref,而 echo "git push --force" 会在什么也没做的情况下匹配它;它需要一次调用存在,所以一个模型看不见的工具永远不会被拦截(第 17 章);而一个每次调用都抛出的守卫是一次全面停机——要在处理器内部捕获。模型是 faux 的,所以这展示的是模型周围的代码,而不是一个真实模型会遵从。
完整源码与测试 。
Understand this example
Copy this prompt into your AI tool. No code runs here.
Apply this example
Copy this prompt into your AI tool. No code runs here.