weichen
476e97c993
IDE postToolUse reports tool_name as MCP:pi_subagent_*; without stripping, guard-pi-dispatch skipped shape checks. Confirmed via live pi_subagent_roles.
43 lines
1.9 KiB
Plaintext
43 lines
1.9 KiB
Plaintext
---
|
||
description: Project Cursor hooks are advisory gates layered on agentctl/PI executor hard checks; scripts exist does not mean Cursor loaded them.
|
||
alwaysApply: true
|
||
---
|
||
|
||
# Cursor hooks（客户端门禁）
|
||
|
||
配置：`.cursor/hooks.json`；脚本：`.cursor/hooks/`。规范登记修订 `cursor-governance-2026-09-24-r1`。
|
||
|
||
## 分层
|
||
|
||
| 层 | 能力 | 说明 |
|
||
|---|---|---|
|
||
| 执行器 / agentctl | **enforced** | `scripts/pi_subagents.py`、租约、pre-commit 等硬拒绝 |
|
||
| hook 脚本行为 | **enforced**（有单元回归） | stdin→stdout 契约可测 |
|
||
| hook ↔ Cursor 接线 | **advisory / manual** | 官方事件字段未完全文档化；待 probe 采样后收紧 |
|
||
|
||
命中策略：与 `guard-git.sh` 一致，一律 `permission: ask`（不静默 deny）。
|
||
|
||
## 事件与脚本
|
||
|
||
- `beforeShellExecution`：`guard-git.sh`（破坏性 git）；`guard-pi-shell.sh`（裸调 `pi_subagents.py run`、`pkill -f`）
|
||
- `beforeMCPExecution`：`guard-pi-dispatch.sh`（`pi_subagent_run` 形状）
|
||
- `postToolUse`：`pi-receipt-context.sh`（注入收据核对提醒）
|
||
- `sessionStart` / `stop`：`audit-session.sh`（审计 + 可选只读盘点；**不注入上下文**）
|
||
|
||
IDE 实测（2026-09-24）：`postToolUse` 的 `tool_name` 形如 `MCP:pi_subagent_roles`；hooks 须剥 `MCP:` 前缀后再匹配角色工具名。
|
||
|
||
## 审计与 probe
|
||
|
||
- 审计：`.cursor/hook-audit.jsonl`（gitignore；勿提交）
|
||
- 盘点：`.cursor/hook-audit/inventory-*.json`
|
||
- 采样：`CURSOR_HOOKS_PROBE=1` → `.cursor/hook-probe.jsonl`
|
||
- 关闭盘点：`CURSOR_HOOKS_NO_INVENTORY=1`
|
||
|
||
异形/未知字段：**fail-open + 审计 `UNRECOGNIZED_INPUT`**，不因契约未知卡死会话。
|
||
|
||
## 红线
|
||
|
||
- 不把 hook 复刻成第二套执行器门禁
|
||
- 脚本存在 ≠ Cursor 已加载；改 hooks 后检查 Hooks 设置页或通道
|
||
- 审计日志不得放进被 git 跟踪的 `.cursor/hooks/` 目录
|