diff --git a/agent-loop-notes.md b/agent-loop-notes.md
new file mode 100644
index 0000000..4e905f8
--- /dev/null
+++ b/agent-loop-notes.md
@@ -0,0 +1,183 @@
+# Agent Loop 范式笔记
+
+## 一、常见 Agent Loop 范式
+
+### 1. ReAct（Reason + Act）
+最经典的范式，每一步：**思考 → 行动 → 观察**，循环直到完成。
+
+```
+Thought: 我需要查一下天气
+Action: search("北京天气")
+Observation: 晴，25°C
+Thought: 已有结果，可以回答了
+Final Answer: ...
+```
+
+### 2. Plan-and-Execute
+先整体规划，再逐步执行。规划与执行分离，适合长任务。
+
+### 3. Reflection / Self-critique
+执行后自我评估，不满意就修正再执行。代表：Reflexion 论文。
+
+### 4. Tool-use Loop
+模型输出 tool call，执行工具，结果追加到上下文，继续推理。Claude Code 本身就是这个范式。
+
+### 5. Multi-agent（Orchestrator + Subagents）
+一个 orchestrator 分解任务，派发给专门的 subagent 并行执行，汇总结果。
+
+### 6. Tree of Thoughts（ToT）
+在每个决策点展开多个分支，用评分函数剪枝，找最优路径。
+
+### 7. LATS
+ToT + Monte Carlo Tree Search，引入 UCB 策略做节点选择。
+
+### 选型参考
+
+| 场景 | 推荐范式 |
+|------|---------|
+| 通用任务、工具调用 | ReAct / Tool-use Loop |
+| 长流程、复杂项目 | Plan-and-Execute |
+| 代码生成/需要验证 | Reflection |
+| 并行子任务 | Multi-agent |
+| 数学/逻辑推理 | Tree of Thoughts |
+
+---
+
+## 二、ReAct 详解
+
+ReAct 是 2022 年 Google 提出的论文（**Re**asoning + **Act**ing），核心思想是让 LLM **交替生成推理链和动作**。
+
+每一轮由三部分组成：
+```
+Thought:     [模型的内部推理，分析当前情况]
+Action:      [调用工具或执行操作]
+Observation: [工具返回的结果，注入回上下文]
+```
+
+**为什么有效：**
+- Thought 让模型显式推理，避免盲目行动
+- Observation 把真实世界的反馈注入推理链，纠正幻觉
+- 两者交织，形成"落地"的推理
+
+| | Chain-of-Thought | ReAct |
+|--|--|--|
+| 推理 | 有 | 有 |
+| 工具调用 | 无 | 有 |
+| 外部信息 | 无 | 实时获取 |
+| 适合场景 | 数学/逻辑 | 信息检索、操作任务 |
+
+---
+
+## 三、典型框架分析
+
+### OpenClaw
+开源通用 agent 平台。核心范式是**以 ReAct 为骨架的 tool-use loop**：
+
+- **主循环**：ReAct / tool-use loop — 见 `agent-loop.md` 里的双重循环（外层 steering/follow-up 续命 + 内层"请求→执行工具→再请求"），这是已对照源码核实的实际形态。
+- **可选叠加**：subagent 委派（Agent/Task 工具）属于按需扩展，不是默认的"多 agent 编排"；prompt 层的 todo/计划相当于轻量 plan 层。
+
+> 不要把它描述成"Gateway 作 orchestrator 调度多个专职 subagent"——Gateway 是单一控制平面,agent 主体仍是单循环。下面是高层组件示意（非严格架构图）：
+
+```
+Channel → Gateway（控制平面）
+              ↓
+       Agent Loop（ReAct 主循环）
+            ↙         ↘
+ Memory & Knowledge   Plugins & Skills
+            ↓
+       LLM Provider
+```
+
+### OpenCode
+SST 团队开源的终端原生编程 agent，bring-your-own-provider（号称 75+ 提供商）。**核心 agent 逻辑用 TypeScript 写，TUI 用 Go（Bubble Tea 风格），TUI 作为本地 agent server 的客户端**——不是"纯 Go 编写"。
+
+- **核心**：Tool-use Loop
+- **特色**：Plan/Build 双模式（Plan-and-Execute 的落地实现）
+
+| 模式 | 权限 | 职责 |
+|------|------|------|
+| Plan Mode | 受限（只读为主） | 分析需求、制定方案 |
+| Build Mode | 完整权限 | 执行：改代码、重构、跑测试 |
+
+### Claude Code
+Anthropic 官方的终端编程 agent，只接 Claude 模型。也是**以 ReAct 为骨架的 tool-use loop**，但把多种范式的扩展点做得最完整——值得作为"骨架 + 按需叠加"工程化形态的参照：
+
+- **主循环（ReAct / tool-use loop）**：模型流式输出 → 检测 tool call → 执行 → 结果回写 transcript → 继续，直到 `end_turn`。
+- **专用工具而非裸 bash**：`Read`/`Edit`/`Bash`/`Grep`/`Glob` 等独立工具，让 harness 能逐工具做**权限闸门、staleness 校验（编辑前文件改过就拒）、自定义渲染、并行调度**——这是"为什么要把动作提升成专用工具"的典型落地。
+- **Plan 层**：Plan Mode（`EnterPlanMode`/`ExitPlanMode`）先只读分析、产出计划交人确认再执行，是 Plan-and-Execute 的轻量门控；TodoList 工具提供更细的任务跟踪。
+- **Multi-agent（orchestrator-worker）**：`Task`/`Agent` 工具派发 subagent（如 Explore、general-purpose、Plan），可给 subagent 配**更便宜的模型**（Explore 用 Haiku）以省 token，并隔离主循环的上下文与 prompt cache。
+- **上下文管理**：compaction（接近上限时服务端摘要）+ context editing（裁剪陈旧 tool 结果/thinking），配合 prompt cache 的确定性排序。
+- **其它扩展**：Hooks（事件钩子）、Skills（按需渐进披露的领域指令）、MCP（外部工具/数据源）、文件式 Memory（`CLAUDE.md` + memory 目录跨会话持久化）、Adaptive thinking。
+
+> 一句话：Claude Code ≈ **ReAct 主循环 + 专用工具闸门 + Plan 门控 + subagent 委派 + 上下文压缩** 的合集，正好把第一节那张"范式叠加"表落到了一个产品里。
+
+### 对比
+
+| | OpenCode | OpenClaw | Claude Code |
+|--|--|--|--|
+| 定位 | 编程专用 coding agent | 通用 agent 平台 | 官方终端编程 agent |
+| 模型 | provider 无关（75+） | 多 provider | 仅 Claude |
+| 核心范式 | Tool-use Loop + Plan/Build 双模式 | 以 ReAct 为骨架的 tool-use loop（subagent 按需叠加） | ReAct 骨架 + Plan 门控 + subagent 委派 |
+| 特色 | provider 无关、LSP 集成、终端原生 | 插件生态、持久记忆、本地运行 | 专用工具闸门、Skills/Hooks/MCP、上下文压缩 |
+
+---
+
+## 四、Tool-use Loop vs ReAct
+
+**ReAct** 是一种**提示范式**，强调把推理（Thought）显式写出来，和行动交织在一起。
+
+**Tool-use Loop** 是一种**执行机制**，描述"调用工具 → 拿到结果 → 继续"这个循环本身，不强调推理是否显式。
+
+```
+Tool-use Loop（大概念）
+    ├── ReAct 实现（Thought 显式输出）
+    └── 隐式推理实现（模型内部思考，直接输出 tool call）
+```
+
+**ReAct 是 Tool-use Loop 的一种实现方式**，区别在于推理是否暴露出来。
+
+现代 LLM 通过 Function Calling API 实现的循环，推理通常在模型内部，对外只暴露 tool call，更接近隐式的 Tool-use Loop。
+
+---
+
+## 五、`<thinking>` 的实现
+
+### 两种不同的东西
+
+**1. 扩展思考（Extended Thinking）— 模型层面**
+
+Anthropic 在训练时赋予模型的原生能力，在给出最终回答前先生成一段草稿推理：
+- 通过 API 的 `thinking` 参数开启
+- thinking block 会出现在 `response.content` 里（与 `text` 块并列）；在多轮 tool use 场景中必须把它回传给模型，并非"不进上下文"
+- 本质是让模型有更多 token 预算来"想清楚再说"
+
+最新 Opus 4.8 / 4.7 只支持 **adaptive thinking**（由模型自行决定何时、想多深），固定 `budget_tokens` 已被移除——发 `{type:"enabled", budget_tokens:N}` 会返回 400。思考深度改用 `effort` 控制：
+
+```python
+response = client.messages.create(
+    model="claude-opus-4-8",
+    thinking={"type": "adaptive"},
+    output_config={"effort": "high"},  # low|medium|high|xhigh|max
+    messages=[...]
+)
+# response.content 里会有 type="thinking" 和 type="text" 两块
+# 注意：4.8/4.7 默认 display="omitted"（thinking 文本为空），
+# 需 thinking={"type":"adaptive","display":"summarized"} 才能看到推理摘要
+```
+
+> 老模型（如 Sonnet 4.5）仍用旧写法 `thinking={"type":"enabled","budget_tokens":N}`（须 < `max_tokens`）。固定 token 预算这一概念整体上已被 adaptive thinking 取代。
+
+**2. ReAct 的 Thought — 提示词层面**
+
+通过 few-shot 示例让模型学会先写推理再写行动，是输出格式的约定，不是模型原生能力。
+
+### 对比
+
+| | Extended Thinking | ReAct Thought |
+|--|--|--|
+| 实现层 | 模型训练 + API 参数 | 提示词格式约定 |
+| 推理深度 | 更深，可自我纠错 | 受限于单次输出 |
+| 对上下文可见性 | 可选暴露给调用方 | 完全可见 |
+| 出现时间 | Claude 3.7+ / o1 | 2022 年论文 |
+
+**本质**：两者都是给模型"打草稿"的空间。Extended Thinking 是把这个能力内化到模型权重里，更自然、更强；ReAct Thought 是用提示词"骗"模型模拟这个行为，是工程 hack。
diff --git a/opencode-plan-mode.md b/opencode-plan-mode.md
new file mode 100644
index 0000000..42802ca
--- /dev/null
+++ b/opencode-plan-mode.md
@@ -0,0 +1,154 @@
+# OpenCode Plan Mode 是怎么实现的
+
+> 基于 sibling 仓库 `../opencode` 源码实读。关键文件:
+> `packages/opencode/src/agent/agent.ts`、`.../permission/index.ts`、
+> `.../session/llm/request.ts`、`.../tool/plan.ts`、`.../tool/edit.ts`。
+
+## 一句话
+
+OpenCode **没有专门的「plan mode」状态机**。Plan Mode 就是一个叫 `plan` 的 **agent**,
+本质是一套 **permission 规则集(Ruleset)**;它复用了 OpenCode 给每次工具调用做权限
+闸门的同一套机制。「进/出 plan」= 切换这一回合归属的 agent。
+
+---
+
+## 1. Mode 即 Agent:plan 是预置 agent 之一
+
+`agent.ts:138` 起定义了四个 native agent,每个就是一个 permission Ruleset:
+
+| agent | mode | 作用 |
+|-------|------|------|
+| `build` | primary | 默认 agent,按配置权限执行(可编辑) |
+| `plan` | primary | Plan mode,禁所有编辑工具 |
+| `general` | subagent | 通用并行子任务 |
+| `explore` | subagent | 只读探索代码库 |
+
+`plan` 的定义(`agent.ts:154`):
+
+```ts
+plan: {
+  description: "Plan mode. Disallows all edit tools.",
+  permission: Permission.merge(
+    defaults,                    // "*": allow;plan_enter/plan_exit/question 默认 deny
+    Permission.fromConfig({
+      question: "allow",
+      plan_exit: "allow",        // 只有 plan agent 能退出
+      task: { general: "deny" }, // 禁止派 general subagent(否则可绕道写文件)
+      edit: {
+        "*": "deny",             // ★ 核心:禁所有编辑
+        [".opencode/plans/*.md"]: "allow",   // 但允许写计划 md
+        [globalPlansDir + "/*.md"]: "allow",
+      },
+    }),
+    user,                        // 用户 config 最后合并,可覆盖
+  ),
+  mode: "primary", native: true,
+}
+```
+
+对照 `build`(`agent.ts:139`):`plan_enter: "allow"` + `question: "allow"`,继承
+`"*": "allow"`,所以能编辑、也能进入 plan。
+
+`defaults`(`agent.ts:117`)是所有 agent 的底:`"*": "allow"`、`doom_loop: "ask"`、
+`question: "deny"`、`plan_enter/plan_exit: "deny"`、`read` 对 `*.env` 类 `ask`、
+外部目录 `ask`。
+
+---
+
+## 2. 规则集怎么被执行:last-match-wins + 两层闸门
+
+### 规则求值
+
+`evaluate()`(`permission/index.ts:39`)在合并后的 ruleset 里 `findLast` 命中
+`{permission, pattern}` 的规则——**后写覆盖先写**(所以 `user` 放在 merge 最后能
+覆盖默认),无命中则默认 `ask`。
+
+### 第一层 · 整工具移除(发请求前)
+
+`resolveTools()`(`session/llm/request.ts:198`)调 `Permission.disabled()`
+(`index.ts:215`):
+
+```ts
+export function disabled(tools, ruleset) {
+  const edits = ["edit", "write", "apply_patch"]
+  return new Set(tools.filter((tool) => {
+    const permission = edits.includes(tool) ? "edit" : tool
+    const rule = ruleset.findLast((r) => Wildcard.match(permission, r.permission))
+    return rule?.pattern === "*" && rule.action === "deny"   // 仅当 "*" 全禁才删
+  }))
+}
+```
+
+一个工具若其**最后命中**规则是 `pattern === "*" && action === "deny"`,就整个从
+模型可见工具表里删掉(`edit/write/apply_patch` 都映射到 `edit` 这个 key)。
+
+### 第二层 · 调用时逐次 ask(运行时)
+
+工具执行时自己调 `ctx.ask(...)`。例如 `tool/edit.ts:102,145`:
+
+```ts
+yield* ctx.ask({ permission: "edit", patterns: [文件路径], ... })
+```
+
+`Permission.ask()`(`index.ts:78`)对每个 pattern 跑 `evaluate`:
+
+- `deny` → 抛 `DeniedError`,该 tool call 被拒,错误回写给模型;
+- `allow` → 静默放行;
+- `ask` → 发 `Asked` 事件、阻塞在 Deferred 上,等用户回 once / always / reject。
+
+### 为什么 plan 能「只读但能写计划文件」
+
+关键细节:plan 给 `.opencode/plans/*.md` 留了 `allow`,所以 `disabled()` 的
+`findLast("edit")` 命中的是那条 **path 级 allow**(`pattern` 不是 `"*"`)——
+于是 **edit 工具不会被整个删掉**,而是保留下来、在运行时按路径逐个判:
+
+- 写普通文件 → 命中 `edit "*": deny` → `DeniedError` 挡掉;
+- 写 `.opencode/plans/foo.md` → 命中 path allow → 放行。
+
+这就是「只读分析、但能把计划落地写进 md」的实现方式。
+
+---
+
+## 3. 进/出 Plan:`plan_enter` / `plan_exit` 是受权限管的伪工具
+
+切换不是 UI flag,而是两个权限动作:
+
+- `build`:`plan_enter: allow`、`plan_exit: deny`(继承)→ 只能进
+- `plan`:`plan_exit: allow`→ 只能出
+
+退出由 `plan_exit` 工具实现(`tool/plan.ts:15`):
+
+1. `question.ask(...)` 弹确认:「计划已完成,要切到 build agent 开始实现吗?」
+   (`plan.ts:30`)
+2. 选 **No** → 抛 `Question.RejectedError`,留在 plan(`plan.ts:46`)。
+3. 选 **Yes** → 注入一条 **synthetic user 消息**,把 `agent: "build"`
+   (`plan.ts:53-61`)+ 合成文本「计划已批准,你现在可以编辑文件,执行计划」
+   (`plan.ts:67`)。这一回合的归属 agent 翻成 `build`,其 ruleset 放开编辑——
+   权限随之解锁。
+
+```
+[plan agent]  edit "*": deny  ──plan_exit(用户确认 Yes)──▶  注入 agent="build" 的 user 消息
+                                                            └─ [build agent] "*": allow,可编辑
+```
+
+---
+
+## 设计要点
+
+OpenCode 把 **plan-mode、只读 explore、各种 subagent、用户自定义 agent 全部统一成
+「命名的 permission ruleset」**。同一套:
+
+- `evaluate`(last-match-wins)
+- `disabled`(整工具删除)
+- `ask`(运行时 deny / allow / 询问)
+
+既做单次工具闸门,也实现了 Plan Mode。「换模式」= 换这一回合归属的 agent,
+经 `plan_enter` / `plan_exit` 且需用户确认。
+
+> 对比 Claude Code:Claude Code 的 Plan Mode 是独立的 `EnterPlanMode`/`ExitPlanMode`
+> 门控;OpenCode 则把它压进通用 permission 体系里,代价更小、可被用户 config 复用同
+> 一套 allow/ask/deny 规则。
+
+> 注:`../opencode/packages/core/src/plugin/agent.ts:117` 有一份 V1 core 等价镜像
+> 定义(`{action:"plan_enter", effect:"deny"}` 等),结构一致;上文以
+> `packages/opencode/src` 下现行实现为准。