From 66b46fc8f34c5207e0bf262497a57fa379f7144e Mon Sep 17 00:00:00 2001
From: catDforD <3276453835@qq.com>
Date: Sun, 26 Apr 2026 19:55:29 +0800
Subject: [PATCH] docs: finish claude code phase 5 records

---
 docs/claude-code.md                           |   6 +-
 docs/claude-code/claude-code-failure-cases.md | 110 ++++++++++++++++++
 docs/claude-code/claude-code-todo.md          |   2 +-
 reproductions/claude-code/README.md           |   6 +-
 4 files changed, 119 insertions(+), 5 deletions(-)
 create mode 100644 docs/claude-code/claude-code-failure-cases.md

diff --git a/docs/claude-code.md b/docs/claude-code.md
index 4723319..517afa3 100644
--- a/docs/claude-code.md
+++ b/docs/claude-code.md
@@ -12,7 +12,9 @@ Claude Code 的系统化学习材料已整理到专题目录：
 - 如果要自己复现，一个最小可行版本应该先做什么
 
 当前仓库进展截至 `2026-03-28`：
-- 已跑通基于 Responses API 的最小 live 只读 agent 闭环，支持 `read_file`、`search`、`git_status`。
+- 已跑通基于 Responses API 的最小 live agent 闭环，支持 `read_file`、`search`、`git_status`、`edit`、`bash`。
 - 已补齐统一事件流、`CLAUDE.md` / `MEMORY.md` / 用户规则加载，以及“旧工具输出先裁掉、旧会话再摘要”的最小 compaction。
+- 已补齐最小控制层：`edit` / `bash` permission gate、allowlist / denylist 规则模块，以及最近一次 `edit` checkpoint / undo。
+- 已完成 Phase 5 最小闭环验证，并记录了一个 permission denylist 导致 `bash` 在 act 阶段被拦截的失败样例。
 - 已提供一个基础 Web UI 工作台用于查看 session、继续会话和检查 `gather -> act -> verify` 摘要。
-- 仍未完成的核心控制层包括 permission gate、checkpoint，以及 live 模式下的写入型工具开放。
+- 下一阶段重点是 Claude Code 风格增强：plan mode、subagent、hooks，以及 commands / agents / hooks 的文件协议化扩展层。
diff --git a/docs/claude-code/claude-code-failure-cases.md b/docs/claude-code/claude-code-failure-cases.md
new file mode 100644
index 0000000..3fe04b2
--- /dev/null
+++ b/docs/claude-code/claude-code-failure-cases.md
@@ -0,0 +1,110 @@
+# Claude Code Phase 5 失败样例记录
+
+这份记录用于落实 [claude-code-todo.md](./claude-code-todo.md) 里 `Phase 5. 验证最小闭环` 的最后一项：至少保留一个可复现的失败样例，并明确说明问题属于哪一层。
+
+当前先记录一个最稳定、最容易重复验证的样例。它不是“模型没做好”，而是当前 cleanroom 复现故意保留的控制层边界，正好对应《[claude-code-study.md](./claude-code-study.md)》里的 `5.5 Safety / Boundaries` 和 `8. 评测、效果与局限`。
+
+## 样例 1：`bash` 被 denylist 拦截，循环在 act 阶段停住
+
+- 分类：权限
+- 对应学习文档章节：
+  - `4. 核心运行循环`
+  - `5.5 Safety / Boundaries`
+  - `8. 评测、效果与局限`
+- 对应代码链：
+  - CLI 参数
+  - `permission_rules.load_permission_rules`
+  - `permissions.InteractivePermissionGate.confirm_tool_use`
+  - `tools.execute_named_tool`
+  - `tool_result.status=denied`
+  - `runtime.verify`
+
+### 复现目的
+
+这个样例用来证明：当前最小闭环里，一次任务失败不一定是检索错了、上下文丢了，或者工具输出不够；也可能是控制层按设计提前拦截了高风险工具。
+
+### 复现条件
+
+workspace 下存在 `.claude-code/permission-rules.json`，内容如下：
+
+```json
+{
+  "bash": {
+    "denylist": ["printf"]
+  }
+}
+```
+
+然后运行：
+
+```bash
+cd reproductions/claude-code
+CLAUDE_CODE_STATE_DIR=/tmp/cc-phase5-state \
+CLAUDE_CODE_WORKSPACE_ROOT=/tmp/cc-phase5-workspace \
+CLAUDE_CODE_ENV_FILE=/tmp/cc-phase5-state/test.env \
+CLAUDE_CODE_PERMISSION_RULES=/tmp/cc-phase5-workspace/.claude-code/permission-rules.json \
+python -m claude_code --tool-direct bash "printf ready"
+```
+
+### 观察结果
+
+本地复现时，CLI 会进入下面这条链：
+
+```text
+user_message(bash printf ready)
+-> tool_call(bash)
+-> tool_result(status=denied)
+-> model_response(解释为什么没执行)
+-> verify_status=loop-needs-attention
+```
+
+一次实际输出如下：
+
+```text
+executed_tools: bash
+verify_status: loop-needs-attention
+assistant_response:
+工具 `bash` 未执行：denylist matched `printf` for `bash` input `printf ready`。当前最小 control layer 会在这里停止，不继续触发真实写入或命令执行。
+```
+
+对应 session 事件里，`tool_result` 会带上结构化权限信息：
+
+```json
+{
+  "tool_name": "bash",
+  "status": "denied",
+  "tool_output": {
+    "permission": {
+      "status": "denied",
+      "reason": "denylist matched `printf` for `bash` input `printf ready`",
+      "source": "denylist"
+    }
+  }
+}
+```
+
+### 为什么把它归类为“权限问题”
+
+- 不是检索问题：这条链没有走 `search` 或 `read_file`。
+- 不是上下文问题：任务在真正执行命令前就被规则命中，不依赖 prompt packing 或历史摘要。
+- 不是工具反馈不足：相反，这里的工具反馈是足够清晰的，已经把 `denied`、`reason`、`source=denylist` 写回了统一事件流。
+
+所以这个失败样例的根因很明确：控制层主动阻止了命令执行，闭环因此停在 `act -> verify` 之间。
+
+### 当前结论
+
+这个失败样例是“按当前设计预期失败”，不是 bug。它说明当前 cleanroom 复现已经具备最小控制层边界：
+
+- 能在真实执行前拦住受控工具。
+- 能把失败原因结构化写回 session。
+- 能让 `verify` 阶段把这次任务归类成 `loop-needs-attention`，而不是伪装成成功完成。
+
+这也解释了当前 Phase 5 的边界：我们已经能验证“最小闭环通不通”，但还没有实现 Claude Code 更完整的恢复体验，比如 plan mode、自动改计划、hooks 派生处理或更细的 remediation 建议。
+
+### 当前仓库里的对应验证
+
+- 行为验证：
+  - [test_cli.py](../../reproductions/claude-code/tests/test_cli.py)
+  - `CliEntryTest.test_bash_tool_can_auto_deny_via_permission_denylist`
+- 闭环主验证：
+  - [test_phase5_validation.py](../../reproductions/claude-code/tests/test_phase5_validation.py)
diff --git a/docs/claude-code/claude-code-todo.md b/docs/claude-code/claude-code-todo.md
index 05e3a40..9f94090 100644
--- a/docs/claude-code/claude-code-todo.md
+++ b/docs/claude-code/claude-code-todo.md
@@ -36,7 +36,7 @@
 ## Phase 5. 验证最小闭环
 - [x] 用一个“读代码并解释”的任务验证只读闭环。见“4. 核心运行循环”。验证见 `reproductions/claude-code/tests/test_phase5_validation.py::Phase5ReadOnlyValidationTest`。
 - [x] 用一个“修复测试失败并重跑”的任务验证写入闭环。见“4.1 一个最小闭环”。验证见 `reproductions/claude-code/tests/test_phase5_validation.py::Phase5WriteValidationTest`。
-- [ ] 记录至少一个失败样例，说明是检索、上下文、权限还是工具反馈出了问题。见“8. 评测、效果与局限”。
+- [x] 记录至少一个失败样例，说明是检索、上下文、权限还是工具反馈出了问题。见“8. 评测、效果与局限”。记录见 [docs/claude-code/claude-code-failure-cases.md](./claude-code-failure-cases.md)。
 
 ## Phase 6. 增强到 Claude Code 风格
 - [ ] 增加 `plan mode`，先输出计划再等待执行批准。见“5.2 Planning”。
diff --git a/reproductions/claude-code/README.md b/reproductions/claude-code/README.md
index 6943eba..f0cda1b 100644
--- a/reproductions/claude-code/README.md
+++ b/reproductions/claude-code/README.md
@@ -11,17 +11,19 @@
 - 统一 session 事件流，以及 `--continue-last` / `--session-id` 会话续跑。
 - `CLAUDE.md`、用户规则、`MEMORY.md` 前 200 行的统一加载。
 - “旧工具输出优先裁掉，再摘要更老会话”的最小 deterministic compaction。
+- 最小控制层：`edit` / `bash` permission gate、allowlist / denylist 规则模块、最近一次 `edit` checkpoint / undo。
+- Phase 5 最小闭环验证，包括只读闭环、写入闭环和一个权限失败样例记录。
 - 基础 Web UI 工作台，用来查看 session、继续会话和检查本轮 `gather -> act -> verify` 摘要。
 
 当前仍未完成的核心模块：
-- checkpoint / undo
 - plan mode、subagent、hooks、文件协议化扩展层
 
 ## Phase 5 最小闭环验证
 
-当前已经把 `docs/claude-code/claude-code-todo.md` 的 `Phase 5` 前两点固化成可重复验证用例，边界和学习文档保持一致：
+当前已经把 `docs/claude-code/claude-code-todo.md` 的 `Phase 5` 三项收尾，边界和学习文档保持一致：
 - 只读闭环：用“读代码并解释”任务验证 live runtime 是否真的按《claude-code-study.md》的 `4. 核心运行循环` 与 `5.3 Memory / Context` 去做 `gather -> search/read_file -> answer`。
 - 写入闭环：用“修复 failing tests 并重跑”任务验证当前最小写入链是否闭环；这组验证仍然固定走 `tool-direct + continue-last + permission rules` 的 deterministic 路径，对应学习文档 `4.1 一个最小闭环` 和 `5.5 Safety / Boundaries`。
+- 失败样例记录：见 [docs/claude-code/claude-code-failure-cases.md](../../docs/claude-code/claude-code-failure-cases.md)。当前先固定记录一个“permission denylist 让 bash 在 act 阶段被拦住”的样例，用来区分控制层拦截和检索/上下文失效。
 
 推荐直接运行：