agent-bot
1409e02187
- AGENTS.md/PROJECT.md rewritten to three-layer model (hard/default/advice); remote authority = Gitea native protection, coding flow zero-agentctl - delete .cursor/rules/agentctl-mandatory.mdc; cursor hooks downgraded to advisory - CURRENT/FEATURE-MATRIX become read-only snapshots; task state = Issue/PR - CI: add tracked secrets scan to required go-vet job - closeout record with V19/V20/V23/V26 evidence - local pre-commit/reference-transaction hook files removed from main worktree
44 lines
2.0 KiB
Plaintext
44 lines
2.0 KiB
Plaintext
---
|
||
description: Cursor hooks are client-side advisories only. Remote authority is Gitea native protection (2026-09-29); agentctl gates are retired for coding flow.
|
||
alwaysApply: true
|
||
---
|
||
|
||
# Cursor hooks（客户端门禁）
|
||
|
||
配置：`.cursor/hooks.json`；脚本：`.cursor/hooks/`。规范登记修订 `cursor-governance-2026-09-24-r1`。
|
||
|
||
## 分层
|
||
|
||
| 层 | 能力 | 说明 |
|
||
|---|---|---|
|
||
| Gitea 服务端 | **enforced** | 受保护分支、必需 CI、非作者批准（2026-09-29 起） |
|
||
| 本地 agentctl | 已退役（仅维护场景可选） | 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/` 目录
|