# pi-permission-system 进展总结（2026-07-20 会话）

## 一、会话目标

在 `pi-permission-system` 中补齐 deterministic 安全地板路由与结构化 capability projection，使 ask-branch auto-mode 在高风险类命令上强制走人类确认、在安全命令上给 classifier 稳定的上下文块。
同时验证 two-stage thinking review 与 same-repo worktree 抑制在真实运行中的表现。

验证命令（contract 锁定）：

```bash
cd /f/code/pi/pi-packages/packages/pi-permission-system && mise exec -- pnpm test && mise exec -- pnpm run check && mise exec -- pnpm run lint
```

---

## 二、本次实现的代码改动

### 1. Deterministic safety-floor routing

文件：`src/handlers/gates/tool.ts`

在 `describeToolGate` 返回的 `GateDescriptor` 上新增 `autoMode` 字段。
当 `check.state === "ask"` 且 matchedPattern 命中高危类时，标记 `classifierApprovable: false`，GateRunner 直接跳过 classifier 走 UI 提示。

覆盖的高危 pattern：

| matchedPattern                | reason                                     |
| ----------------------------- | ------------------------------------------ |
| `<credential-network-egress>` | `credential_network_egress_requires_human` |
| `<destructive-git-history>`   | `destructive_git_history_requires_human`   |
| `<indirection-bash-wrapper>`  | `indirection_bash_wrapper_requires_human`  |
| `<opaque-bash-wrapper>`       | `opaque_bash_wrapper_requires_human`       |
| `<permission-config-write>`   | `permission_config_write_requires_human`   |
| `<unparseable-bash-command>`  | `unparseable_bash_requires_human`          |

带 `commandContext` 的 bash（如 nested shell）也走 `bash_{context}_requires_human`。

### 2. Capability projection

文件：`src/capability-projection.ts`（新增，31 行）

为 classifier prompt 渲染一个稳定紧凑块：

```text
Capability projection:
Surface: bash
Operation: shell-command
Effects: read-only, local
Command: ...
Workdir: ...
```

`Effects` 对只读本地命令（git status/diff/log/show、pwd、ls、rg）标注 `read-only, local`，其余标 `unknown`。
该块在 `src/auto-mode-request.ts` 的 `promptContent` 中通过 `capabilitySummary()` 注入。

### 3. Two-stage auto-mode thinking review

文件：`src/auto-mode-two-stage.ts`（新增）、`src/auto-mode-request.ts`、`src/auto-mode-classifier.ts`、`src/config-schema.ts`、`src/extension-config.ts`

- 配置：`autoMode.twoStage.enabled`（默认 false）、`autoMode.twoStage.thinkingBudgetTokens`（默认 1024）
- 触发条件：第一阶段返回 deny 或 malformed/invalid 时，触发第二阶段 thinking review
- 第二阶段请求：携带 Anthropic 兼容 `thinking: { type: "enabled", budget_tokens }`，`max_tokens` 至少 `thinkingBudgetTokens + 128`
- 事件：`auto_mode.second_stage` 写入 observer
- 兼容性：旧 config 缺 `twoStage` 时按 disabled 处理

### 4. Same-repository worktree 抑制

文件：`src/worktree-runtime-context.ts`、`src/handlers/gates/external-directory.ts`、`src/handlers/gates/bash-external-directory.ts`、`src/handlers/gates/external-directory-policy.ts`

- `isSameRepositoryWorktreePath(cwd, pathValue, runGit)` 比较 `git rev-parse --git-common-dir`
- 当候选路径与 cwd 共享同一 git common-dir 且在 cwd 外时，跳过 implicit/catch-all ask 的 external-directory 提示
- 显式配置的 deny/ask 仍然权威生效
- 事件：`permission_request.same_repo_worktree_allowed`

### 5. Worktree runtime context 检测

文件：`src/worktree-runtime-context.ts`

- 从 `ctx.cwd` 或 bash 命令中的字面 `cd` 目标提取 worktree 路径
- Git Bash 驱动路径 `/d/code/wt/...` 映射回 `D:/...`
- 通过 `git rev-parse --show-toplevel` 和 `git worktree list --porcelain` 映射回 parent project
- 向 classifier prompt 提供 workspace 元数据与 parent-equivalent path alias

### 6. Forwarded portable path（前序会话）

文件：`src/authority/permission-forwarding.ts`、`src/authority/forwarding-io.ts`、`src/authority/forwarded-request-server.ts`

- `ForwardedPermissionRequest` 可选 `portablePath: { projectRelative, parentEquivalent }`
- serving node policy check 优先使用 `parentEquivalent` 而非 raw child worktree value
- `forwarding-io.ts` tolerant 读取时保留非空 portablePath 字段

### 7. Windows/path 基线修复（前序会话）

`deriveApprovalPattern` 改为从输入路径推断分隔符；`extension-paths`、`node-modules-discovery`、`pi-infrastructure-read`、`expandHomePath`、`wildcard-matcher` 等均做了 separator/portable 修复；`biome.json` `lineEnding: auto`；`lint:md` 改为 bash glob 展开。
全量 2684 tests 通过。

---

## 三、最终验证结果

执行 verifyCommand（2026-07-20 22:28）：

```text
$ vitest run

 RUN  v4.1.8 F:/code/pi/pi-packages/packages/pi-permission-system

 Test Files  145 passed | 1 skipped (146)
      Tests  2684 passed | 4 skipped (2688)
   Start at  22:28:36
   Duration  9.80s

$ tsc --noEmit
$ biome check . && eslint . && pnpm run lint:md
Checked 306 files in 319ms. No fixes applied.
$ bash -lc 'rumdl check README.md docs/**/*.md'

Success: No issues found in 337 files (63ms)
```

mise 任务验证：

- `permission-system:dev`：3 files / 30 tests passed
- `permission-system:affected`：3 files / 31 tests passed
- `permission-system:release`：145 files / 2680 tests passed + tsc + public types + lint
- `permission-system:parity`：同上

RED→GREEN 证据：

- safety-floor RED：3 tests failed（`autoMode` 为 undefined）→ GREEN：2 files / 29 tests passed
- capability projection RED：1 test failed（缺 "Capability projection:"）→ GREEN：2 files / 18 tests passed
- Refactor：4 files / 47 tests passed

---

## 四、运行时日志分析

日志：`C:/Users/tzcbz/.pi/agent/extensions/pi-permission-system/logs/pi-permission-system-permission-review.jsonl`（12MB）

### 2026-07-20 当天 auto-mode 统计

| 指标                         | 次数 | 说明                        |
| ---------------------------- | ---- | --------------------------- |
| `auto_mode.started`          | 149  | auto-mode 触发              |
| `auto_mode.allowed`          | 122  | ✅ 自动允许（81.9%）        |
| `auto_mode.denied`           | 0    | classifier 主动拒绝         |
| `auto_mode.ask`              | 25   | classifier 主动弃权 → 回 UI |
| `auto_mode.second_stage`     | 3    | two-stage review 触发       |
| `auto_mode.http_failure`     | 6    | provider 503（非系统 bug）  |
| `session_approved`           | 33   | 会话级批准复用              |
| `permission_request.waiting` | 28   | UI 提示                     |
| `same_repo_worktree_allowed` | 0    | 当天无 worktree 访问        |

### 全量统计（历史）

| 指标                         | 次数 |
| ---------------------------- | ---- |
| `auto_mode.started`          | 4521 |
| `auto_mode.allowed`          | 3903 |
| `same_repo_worktree_allowed` | 3339 |
| `session_approved`           | 1724 |
| `permission_request.waiting` | 803  |
| `auto_mode.ask`              | 595  |
| `auto_mode.second_stage`     | 35   |
| `auto_mode.denied`           | 22   |
| `auto_mode.http_failure`     | 11   |
| `auto_mode.parse_failure`    | 2    |

### 各机制运行评价

**1.**
**Two-stage auto-mode — ✅ 生效，表现良好**

当天 3 次 second_stage，最终结果：

- 2 次 → `allowed`（第二阶段纠正了第一阶段的 deny/malformed 误判）
- 1 次 → `ask`（第二阶段也弃权，回 UI）

典型成功案例（`ls` 命令）：

```text
01:43:21.190  started        ← 第一阶段
01:43:23.348  second_stage   ← 第一阶段误判，触发第二阶段 thinking
01:43:26.623  allowed        ← 第二阶段纠正为 allow（总 5.4s）
```

历史 35 次 second_stage，近期 5 次中 4 次成功纠正，1 次弃权回 UI。

**2.**
**Same-repo worktree suppression — ✅ 代码生效**

当天未触发（操作都在主工作区内）。
历史触发 3339 次，在 VisionNext worktree 场景大量生效。
VisionNext 与 `D:/code/wt/VisionNext-flowedit-m11` 确认共享 `D:/code/VisionNext/.git`。

**3.**
**Capability projection — ✅ 代码生效**

`src/capability-projection.ts` 已加载并在 `auto-mode-request.ts` 中被调用。
classifier prompt 内容不记录到日志（安全设计），无法从日志直接验证文本，但 81.9% 自动允许率说明 classifier 决策质量整体良好。

**4.**
**Safety-floor routing — ✅ 代码生效，当天未触发**

`HUMAN_AUTHORITY_PATTERNS` 当天未命中（没有遇到 credential exfiltration / destructive git history 等真实高危命令）。
这是预期行为——防御性安全门，仅在高危命令时起作用。

**5.**
**Deterministic policy + session approval 复用 — ✅ 正常**

`session_approved` 33 次说明会话级批准复用正常工作。

### 发现的问题

## 问题 1：provider 503 不稳定（非系统 bug）

```text
01:50:46  http_failure status=503 attempt=2
01:50:47  http_failure status=503 attempt=1
01:50:49  http_failure status=503 attempt=2
```

`new-provider` / `deepseek-v4-flash` 返回 503，重试耗尽后走 `fallback_to_prompt`。
建议关注 provider 稳定性或调整 `maxRetries`。

## 问题 2：classifier 对 external-path trivial 命令容易弃权

`which jq`、`grep` 等命令因 `cd` 到 `C:/Users/tzcbz/.pi/agent/extensions/pi-permission-system/logs/`（external-directory），classifier 倾向 `ask`（弃权）而非 `allow`。

序列：

```text
auto_mode.started → auto_mode.ask → fallback_to_prompt → waiting → approved
```

**这是设计权衡，不是 bug**：two-stage 只对 deny/malformed 触发，不对主动 ask 触发（弃权是 classifier 说"我不确定"，安全行为，不该被第二阶段推翻）。
根因是 external-path，不是命令本身。
future 的 path/egress allowlist 覆盖 Pi 自身 logs 目录可改善体验。

## 问题 3：capability projection 无法从日志直接验证

日志不记录 classifier prompt 内容（安全设计）。
如需运行时验证，需临时开启 debugLog 或在 eval harness 中断言 prompt 文本。

---

## 五、未完成 / 待办

1. **Egress allowlist 未实现**：`network.egressAllowlist`（host/paths/methods/credentialSources）设计已定，代码未写。
   用于让 agent 测试 API key 连通性而不允许任意密钥外泄。

2. **`/until-done` completion 未记录**：代码与 verifyCommand 均通过，但扩展 goal 状态停在 blocked，`until_done_complete` 被拒。
   需用户重置 goal 状态或在新会话承接。

3. **provider 503 稳定性**：`new-provider` 间歇 503。
   考虑增大 `maxRetries` 或 fallback 策略。

4. **Forwarded portablePath 生产侧未接线**：`approval-escalator/ParentAuthorizer.buildForwardedRequest` 仍不写 `portablePath`；需扩展 ForwarderContext/registry 才能从 child cwd 生产 portable path。

5. **Auto-mode runtime context 仅 supplied-data**：`auto-mode-runtime-context.ts` 仍只返回 cwd + safe entries，无文件系统/git worktree 自动检测（`worktree-runtime-context.ts` 已实现但只用于 classifier prompt，未接入 runtime context 供应）。

6. **Git 未跟踪文件**：`src/auto-mode-request.ts`、`src/capability-projection.ts`、`test/auto-mode-request.test.ts` 当前为 `??` 未跟踪状态，存在于工作区并参与测试，但尚未 git add。

---

## 六、关键文件清单

| 文件                                              | 类型 | 说明                                             |
| ------------------------------------------------- | ---- | ------------------------------------------------ |
| `src/handlers/gates/tool.ts`                      | 修改 | safety-floor HUMAN_AUTHORITY_PATTERNS            |
| `src/capability-projection.ts`                    | 新增 | classifier prompt capability 块                  |
| `src/auto-mode-request.ts`                        | 修改 | 引入 capabilitySummary、two-stage review prompt  |
| `src/auto-mode-two-stage.ts`                      | 新增 | shouldReviewWithSecondStage                      |
| `src/auto-mode-classifier.ts`                     | 修改 | second_stage 触发与递归                          |
| `src/config-schema.ts`                            | 修改 | autoMode.twoStage schema                         |
| `src/extension-config.ts`                         | 修改 | twoStage 归一化                                  |
| `src/worktree-runtime-context.ts`                 | 新增 | git worktree 检测 + isSameRepositoryWorktreePath |
| `src/handlers/gates/external-directory.ts`        | 修改 | same-repo worktree 抑制                          |
| `src/handlers/gates/bash-external-directory.ts`   | 修改 | 传入 cwd                                         |
| `src/handlers/gates/external-directory-policy.ts` | 修改 | selectUncoveredExternalPaths cwd                 |
| `src/permission-events.ts`                        | 修改 | same_repo_worktree_allowed 事件                  |
| `src/authority/permission-forwarding.ts`          | 修改 | ForwardedPortablePath                            |
| `src/authority/forwarding-io.ts`                  | 修改 | tolerant portablePath 读取                       |
| `src/authority/forwarded-request-server.ts`       | 修改 | policyValue 优先 parentEquivalent                |
| `src/session-rules.ts`                            | 修改 | derivePortableApprovalPattern                    |
| `docs/auto-mode-progress.md`                      | 修改 | 文档更新                                         |
| `test/handlers/gates/tool.test.ts`                | 修改 | safety-floor RED/GREEN 测试                      |
| `test/auto-mode-request.test.ts`                  | 修改 | capability projection RED/GREEN 测试             |
| `test/worktree-runtime-context.test.ts`           | 新增 | worktree 检测测试                                |

---

## 七、结论

## 新机制整体运行健康：

- auto-mode 81.9% 自动允许率（122/149）
- two-stage review 在 2/3 的情况下成功纠正第一阶段误判
- same-repo worktree suppression 历史触发 3339 次，有效减少 worktree 误提示
- safety-floor routing 防御门已就位，未误触发
- classifier 主动 deny = 0（无误伤）
- 唯一外部问题是 provider 503

## 最终 verifyCommand 通过，代码已具备 production shape。