diff --git a/CLAW_AGENT_ARCH_ANALYSIS.md b/CLAW_AGENT_ARCH_ANALYSIS.md
deleted file mode 100644
index 9fffe25..0000000
--- a/CLAW_AGENT_ARCH_ANALYSIS.md
+++ /dev/null
@@ -1,933 +0,0 @@
-# Claw Code Agent 架构逆向分析报告
-
-本文基于只读分析仓库源码撰写，目标不是介绍如何使用，而是回答这个项目作为一个 Agent 系统是如何被构造出来的。
-
----
-
-## 1. 总体定位
-
-### 1.1 这个项目本质上是什么
-
-这个项目本质上是一个 **agentic coding runtime**，而不是单纯的 workflow engine，也不只是一个 tool harness。
-
-更准确地说，它处在三者交叉区：
-
-- **最核心身份**：Claude Code / Codex 风格的本地 coding agent runtime
-- **承载方式**：以 Python 实现的 agent loop + tool harness
-- **扩展方式**：外挂了大量 runtime 子系统，例如 search、MCP、plan、task、team、workflow、worktree、plugin、hook policy
-
-因此它不是一个“纯工作流系统”。workflow 在这里是一个被 agent 调用的能力域，而不是系统唯一中心。系统中心仍然是 `LocalCodingAgent` 的多轮模型-工具循环，见 `src/agent_runtime.py:103`、`src/agent_runtime.py:358`。
-
-### 1.2 核心抽象是什么
-
-这个项目有几个关键抽象：
-
-- **Agent**：`LocalCodingAgent`，真正的 orchestrator，负责 prompt 构建、loop、工具调用、budget、session 持久化，见 `src/agent_runtime.py:103`
-- **Session**：`AgentSessionState`，维护系统消息、用户上下文、assistant/tool transcript 以及 mutation lineage，见 `src/agent_session.py:89`
-- **Tool**：`AgentTool` + `ToolExecutionContext`，以 OpenAI function calling 风格对工具进行 schema 化和执行，见 `src/agent_tools.py:44`、`src/agent_tools.py:73`
-- **Prompt Context**：`PromptContext` / `AgentContextSnapshot`，把工作目录、git 状态、CLAUDE.md、各种 runtime 状态拼进模型上下文，见 `src/agent_prompting.py:15`、`src/agent_context.py:40`
-- **StoredAgentSession`**：把完整 transcript、tool_calls、usage、file_history、plugin_state 持久化到 `.port_sessions/agent/*.json`，见 `src/session_store.py:53`
-
-换句话说，它不是围绕“任务节点图”来设计的，而是围绕：
-
-1. 当前 session 里有哪些上下文
-2. 当前模型要不要发起 tool call
-3. tool result 如何再次喂回模型
-4. 何时 compact / stop / persist
-
-### 1.3 与 Claude Code / Codex 的相似点与差异
-
-#### 相似点
-
-- 典型 **LLM-driven tool loop**：模型产出 tool call，runtime 执行工具，再把结果作为 `tool` message 回灌
-- 以 **workspace / repository** 为中心，强依赖文件系统、git 状态、shell、搜索
-- 支持 **系统提示词 + repo memory** 注入，尤其是 `CLAUDE.md`
-- 有 **多轮对话 session**、resume、context compaction、权限 gating
-- 支持 **Agent 子代理 / delegation**
-
-#### 差异点
-
-- 比 Claude Code / Codex 更“runtime platform 化”：这里塞了大量本地 runtime 子系统，如 `task_runtime`、`plan_runtime`、`team_runtime`、`workflow_runtime`、`remote_runtime`、`mcp_runtime`
-- “skills” 实现较轻：当前更像 prompt-template / slash-command bridge，而不是成熟的按需 markdown 技能系统
-- 权限模型相对简化：主要是 CLI 启动时布尔权限 + policy deny，而不是更细粒度的人机交互审批流
-- 可观测性是“有 transcript / event / file_history 基础设施，但 UI 和诊断链条尚未完全产品化”
-
-结论上，这个项目像是：
-
-> 一个以 coding agent loop 为中心、向外扩张成通用本地 agent runtime 平台的 Python 实现。
-
----
-
-## 2. Agent Loop
-
-### 2.1 主循环入口
-
-真实入口是 `LocalCodingAgent.run()`，它生成 `session_id`、scratchpad 目录，然后进入 `_run_prompt()`，见：
-
-- `src/agent_runtime.py:358`
-- `src/agent_runtime.py:413`
-
-恢复会话则走 `resume()`，它把持久化 session 反序列化成 `AgentSessionState`，并补充 file history replay 与 compaction replay，见 `src/agent_runtime.py:376`。
-
-### 2.2 每轮如何观察当前状态
-
-Agent 的“观察”不是通过一个单独的 observe() 函数完成，而是在 loop 外预构建 session，并在每轮前做上下文压力处理：
-
-1. **启动时构建 prompt context**
-   - `build_prompt_context()` -> `build_context_snapshot()`
-   - 汇总 cwd、platform、git status、scratchpad、CLAUDE.md bundle、各 runtime summary
-   - 见 `src/agent_runtime.py:240` 左右、`src/agent_prompting.py:30`、`src/agent_context.py:71`
-
-2. **构建初始 session**
-   - `build_session()` 使用 system prompt parts + user_context/system_context 生成 session
-   - `AgentSessionState.create()` 会插入：
-     - `system` message
-     - `user_context reminder`
-     - 当前用户 prompt
-   - 见 `src/agent_runtime.py:255` 左右、`src/agent_session.py:97`
-
-3. **每轮前的状态整理**
-   - `_microcompact_session_if_needed()`
-   - `_snip_session_if_needed()`
-   - `_compact_session_if_needed()`
-   - `_preflight_prompt_length()`
-   - 见 `src/agent_runtime.py:527-547`
-
-因此，“观察当前状态”既包括文件系统 / git / runtime summary，也包括自身历史 transcript 的压缩后视图。
-
-### 2.3 如何构造上下文
-
-上下文构造分两层：
-
-#### 第一层：环境与 memory 采样
-
-`src/agent_context.py` 负责采样：
-
-- cwd、shell、platform、date
-- git status snapshot，见 `src/agent_context.py:279`
-- scratchpad directory，见 `src/agent_context.py:197`
-- `CLAUDE.md` / `.claude/CLAUDE.md` / `CLAUDE.local.md` / `.claude/rules/*.md` bundle，见 `src/agent_context.py:313-372`
-- plugin / hook policy / MCP / remote / search / account / ask_user / config / LSP / plan / task / team / workflow / worktree 的 runtime summary，见 `src/agent_context.py:205-275`
-
-#### 第二层：系统提示词装配
-
-`build_system_prompt_parts()` 会拼接：
-
-- system instructions
-- doing tasks guidance
-- tool usage guidance
-- agent guidance
-- plugin / MCP / search / account / ask-user / config / LSP / plan / task / team / hook policy guidance
-- session-specific permission guidance
-- simple env info
-
-见 `src/agent_prompting.py:75-119`。
-
-也就是说，这个项目的上下文不是“只把聊天记录喂给模型”，而是：
-
-> transcript + injected local memory + runtime summaries + environment facts + permissions hints
-
-### 2.4 如何决定下一步行动
-
-行动选择主要由模型驱动。
-
-每轮中 runtime 做的事情是：
-
-1. 把 `session.to_openai_messages()` 和 `tool_specs` 发给模型，见 `src/agent_runtime.py:1153-1157`
-2. 从返回中解析：
-   - 普通 assistant content
-   - tool calls
-   - finish_reason
-   - usage
-3. 若无 tool call，则视作模型选择直接回答
-4. 若有 tool call，则 runtime 执行这些工具，再把工具结果回灌到 session
-
-真正的“决策”是模型自己通过 OpenAI tool calling 选择的，而不是 runtime 用规则树规划下一步。
-
-因此 loop 属于：
-
-- **外层固定流程**
-- **内层模型驱动的动态行动选择**
-
-### 2.5 如何调用工具
-
-工具定义为 `AgentTool`，带：
-
-- `name`
-- `description`
-- JSON Schema 参数定义 `parameters`
-- `handler`
-
-见 `src/agent_tools.py:73-111`。
-
-每轮把所有工具变成 OpenAI function spec：
-
-- `tool_specs = [tool.to_openai_tool() for tool in self.tool_registry.values()]`
-- 见 `src/agent_runtime.py:463`
-
-模型返回 tool call 后，主循环在 `src/agent_runtime.py:808-1119` 中执行：
-
-- 创建一个 tool message 占位 `session.start_tool(...)`
-- 记录 `tool_start` event
-- 应用 plugin / hook policy preflight
-- 执行 delegate / Skill / 普通 tool
-- 以 `serialize_tool_result()` 将结果序列化成 JSON 字符串写回 transcript
-
-### 2.6 工具结果如何回到模型上下文
-
-工具结果通过 `session.finalize_tool(...)` 变成一个 `role='tool'` 的 message，内容是：
-
-```json
-{
-  "tool": "...",
-  "ok": true/false,
-  "content": "...",
-  "metadata": {...}
-}
-```
-
-见：
-
-- `src/agent_tools.py:1248`
-- `src/agent_runtime.py:1037-1047`
-
-下一轮模型调用时，`session.to_openai_messages()` 会把这些 tool messages 一并送回模型。因此工具结果不是旁路状态，而是标准 transcript 的一部分。
-
-### 2.7 什么时候停止
-
-停止条件有多类：
-
-- **模型正常回答且无 tool_calls**：结束，见 `src/agent_runtime.py:764-806`
-- **finish_reason = length/max_tokens**：自动注入 continuation prompt，再继续一轮，见 `src/agent_runtime.py:766-783`
-- **budget exceeded**：停止，见 `src/agent_runtime.py:500-525`、`552-581`、`733-762`
-- **prompt too long / preflight fail**：停止或先 compact 再试，见 `src/agent_runtime.py:543-605`
-- **backend error**：停止，见 `src/agent_runtime.py:703-725`
-- **达到 `max_turns`**：停止，见 `src/agent_runtime.py:1121-1146`
-
-### 2.8 loop 是固定流程还是模型驱动
-
-结论：
-
-- **loop 骨架是固定的 runtime state machine**
-- **每轮内的动作内容是模型驱动的**
-
-固定部分是：
-
-1. 整理上下文
-2. 预算检查
-3. 调模型
-4. 若 tool_calls 则执行工具
-5. 把工具结果写回 transcript
-6. 进入下一轮或停止
-
-动态部分是：
-
-- 调什么工具
-- 调多少个工具
-- 是继续观察、修改还是直接回答
-
----
-
-## 3. Context / Memory
-
-### 3.1 是否有短期上下文
-
-有。短期上下文就是当前 `AgentSessionState.messages`。
-
-其中包含：
-
-- system prompt
-- user context reminder
-- user / assistant / tool messages
-- mutation metadata
-
-见 `src/agent_session.py:89-148`。
-
-### 3.2 是否有长期记忆
-
-有，但不是向量数据库式长期记忆，而是 **文件化长期记忆**：
-
-- `~/.claude/CLAUDE.md`
-- 向上目录搜索的 `CLAUDE.md`
-- `.claude/CLAUDE.md`
-- `CLAUDE.local.md`
-- `.claude/rules/*.md`
-
-这些文件会在 session 创建时被 bundle 进 `user_context['claudeMd']`，见 `src/agent_context.py:205-207`、`313-372`。
-
-因此它支持“repo memory / instruction memory”，但不支持自动写回、检索式 memory store 或 embedding memory。
-
-### 3.3 是否有 conversation history
-
-有，而且比较完整：
-
-- 运行时 transcript：`AgentSessionState.messages`
-- 持久化 transcript：`StoredAgentSession.messages`
-- resume 后会恢复完整历史，见 `src/session_store.py:53-115`
-
-工具调用、usage、message metadata 也一起保存。
-
-### 3.4 是否有压缩 / summarize / compaction
-
-有，而且这是一个比较成熟的部分。
-
-机制分三层：
-
-- **microcompact**：时间驱动的小型压缩，清理旧 tool results，见 `src/agent_runtime.py:113-115 import`、`src/agent_runtime.py:527-533`
-- **snip**：把早期消息 tombstone 化为短摘要，见 `src/agent_runtime.py:533-537` 与 `_snip_session_pass`
-- **compact**：调用 `compact_conversation()` 生成更正式的压缩摘要，见 `src/agent_runtime.py:538-547`、`src/agent_runtime.py:1240` 前后逻辑
-
-此外还有：
-
-- prompt too long 时的 **reactive compaction retry**
-- resume 时的 **compaction replay**
-
-见 `src/agent_runtime.py:3042-3142`。
-
-### 3.5 是否有外部文件作为 memory
-
-有，且非常明显：
-
-- `CLAUDE.md` 系列
-- `.claude/rules/*.md`
-- 各类 workspace state 文件：config、plan、task、team、workflow、worktree 等 runtime manifest/state 文件
-
-不过严格说，后者更多是 “runtime state injection”，不是纯 memory。
-
-### 3.6 是否支持类似 CLAUDE.md / AGENTS.md / skills 的持久知识
-
-#### CLAUDE.md
-
-支持，且是当前唯一成熟的一类持久知识注入。
-
-#### AGENTS.md
-
-**不原生支持 `AGENTS.md` 作为 memory bundle**。当前 memory 发现逻辑只搜索 `CLAUDE.md`、`CLAUDE.local.md` 和 `.claude/rules/*.md`，见 `src/agent_context.py:355-372`。
-
-#### skills
-
-只支持“bundled skills”：
-
-- 在 Python 代码里硬编码 skill 元数据和 prompt builder
-- 通过 `Skill` 工具或 `/skills` 暴露
-
-不支持从工作区扫描 markdown skill 文档并按需加载。
-
-### 3.7 当前设计局限
-
-1. **长期记忆是纯文件注入，不是检索式 memory**
-   - 规模大时容易塞满 prompt
-   - 没有 relevance ranking
-
-2. **只识别 CLAUDE.md 家族，不识别 AGENTS.md**
-   - 对多代理协作约束不够统一
-
-3. **resume 依赖 transcript replay，不是真正的 semantic memory**
-   - 历史很多时仍然会发生 compaction 丢失细节
-
-4. **runtime summaries 很多，但上下文管理是“全量摘要注入”**
-   - 不是 query-time selective loading
-
-5. **task / plan / workflow 已有，但未形成强约束的 workspace memory layout**
-   - 更像多个离散 runtime，而不是统一的 task-memory 文件系统
-
----
-
-## 4. Tools / Actions
-
-### 4.1 工具能力概览
-
-核心工具能力包括：
-
-- **文件系统**
-  - `list_dir`
-  - `read_file`
-  - `write_file`
-  - `edit_file`
-  - `notebook_edit`
-- **搜索与代码理解**
-  - `glob_search`
-  - `grep_search`
-  - `LSP`
-  - `tool_search`
-- **Shell**
-  - `bash`
-- **Web / Search**
-  - `web_fetch`
-  - `web_search`
-  - search provider 管理工具
-- **计划 / 任务**
-  - `update_plan`
-  - `plan_get`
-  - task runtime 相关工具
-- **Human gate**
-  - `ask_user_question`
-- **扩展 runtime**
-  - `mcp_*`
-  - `remote_*`
-  - `workflow_*`
-  - `worktree_*`
-  - `account_*`
-  - `config_*`
-- **Agent 特有**
-  - `Agent` / `delegate_agent`
-  - `Skill`
-
-tool registry 定义入口在 `src/agent_tools.py:210`。
-
-### 4.2 工具 schema 怎么定义
-
-每个工具是一个 `AgentTool`：
-
-- `name`
-- `description`
-- `parameters`（JSON Schema）
-- `handler`
-
-见 `src/agent_tools.py:73-111`。
-
-它通过 `to_openai_tool()` 转成 OpenAI-compatible function calling schema，见 `src/agent_tools.py:80-88`。
-
-### 4.3 工具调用怎么执行
-
-模型返回 tool call 后，runtime 会：
-
-1. 解析 tool call，见 `src/openai_compat.py:273-298`
-2. 在 loop 中逐个消费，见 `src/agent_runtime.py:808-1119`
-3. 普通工具走 `execute_tool_streaming()` 或 `tool.execute()`，见 `src/agent_tools.py:181-207`
-4. 特殊工具：
-   - `Agent` / `delegate_agent` 走子代理执行，见 `src/agent_runtime.py:2214`
-   - `Skill` 走 `_execute_skill()`，见 `src/agent_runtime.py:2059`
-
-### 4.4 工具结果如何返回
-
-工具结果统一封装为 `ToolExecutionResult`：
-
-- `name`
-- `ok`
-- `content`
-- `metadata`
-
-然后 `serialize_tool_result()` 把它转成 JSON 字符串，塞入 tool message，见 `src/agent_tools.py:1248-1255`。
-
-这意味着：
-
-- 对模型来说，工具结果是 transcript 中的标准 `tool` message
-- 对 runtime 来说，工具结果又带 `metadata`，可用于 file_history、policy event、plugin hook
-
-### 4.5 是否有安全边界
-
-有，但不是特别细粒度。
-
-#### 文件边界
-
-`_resolve_path()` 会强制路径位于 workspace root 内，防止越界，见 `src/agent_tools.py:1277-1288`。
-
-#### 写权限边界
-
-`write_file` / `edit_file` 受 `allow_file_write` 控制，见 `src/agent_tools.py:1291-1295`。
-
-#### shell 权限边界
-
-`bash` 受两层控制：
-
-- `allow_shell_commands`
-- `allow_destructive_shell_commands`
-
-并有 destructive regex 阻断，比如 `rm`、`git reset --hard`、`git clean -fd` 等，见 `src/agent_tools.py:1298-1324`。
-
-#### policy / hook deny
-
-workspace 可以通过 `.claw-policy.json` / `.codex-policy.json` / `.claw-hooks.json` 配置 deny_tools、deny_tool_prefixes 以及 hook message，见 `src/hook_policy.py:160-256`。
-
-#### CLI 层 deny context
-
-还有一个更轻的 `ToolPermissionContext`，可按名字或前缀过滤工具，见 `src/permissions.py:7-17`。
-
-### 4.6 这一层的架构评价
-
-这个项目的 tools 层已经不是“几个本地 IO 工具”，而是：
-
-> 一个围绕 workspace 资源、外部 runtime 状态和 agent orchestration 展开的统一 action surface。
-
-优点是扩展性强，缺点是工具域越来越大后，模型对何时该用哪个工具会变得更依赖 prompt guidance。
-
----
-
-## 5. Markdown / Workspace
-
-### 5.1 是否支持 workspace-first
-
-是，明显是 workspace-first 设计。
-
-证据：
-
-- `ToolExecutionContext.root` 是工作区根，见 `src/agent_tools.py:45`
-- 所有文件工具都围绕 workspace root 做相对路径解析，见 `src/agent_tools.py:1277-1288`
-- context 注入围绕 cwd、git repo、worktree、scratchpad、additional_working_directories 展开，见 `src/agent_context.py:71-99`
-- 很多 runtime 都是 `from_workspace(cwd)` 初始化的
-
-### 5.2 是否适合让 Agent 维护 `.md` 文件作为任务记忆
-
-适合，而且比很多 agent 框架更适合。
-
-原因：
-
-- 已经原生支持 markdown 记忆文件注入（CLAUDE.md / rules）
-- 文件读写/编辑能力完整
-- 有 plan / task runtime，可作为结构化状态
-- 有 scratchpad directory，可作为会话级临时区
-
-不足是它没有约定一个统一的 task-memory 目录布局。
-
-### 5.3 是否有任务目录 / workspace 概念
-
-有 workspace 概念，但没有强约定的任务目录结构。
-
-已有元素：
-
-- workspace root
-- additional working directories
-- scratchpad root / scratchpad directory
-- `.claude/` 作为本地 agent/runtime 元数据目录
-
-但没有默认的：
-
-- `/tasks/{task_id}/...`
-- `/artifacts/...`
-- `/memory/...`
-
-### 5.4 能否改造成 task directory layout
-
-完全可以，而且改造成本不高。
-
-一个可行布局：
-
-```text
-/tasks/{task_id}/goal.md
-/tasks/{task_id}/memory/open_questions.md
-/tasks/{task_id}/memory/working_notes.md
-/tasks/{task_id}/artifacts/report.md
-/tasks/{task_id}/artifacts/commands.md
-/tasks/{task_id}/artifacts/findings.md
-```
-
-最小改造方式：
-
-1. 在 `task_runtime` 中给 task 增加 `task_root`
-2. 在 `agent_context._load_memory_bundle()` 中把 `/tasks/{active_task}/memory/*.md` 纳入 memory discovery
-3. 在 prompt context 中注入 `active task root`
-4. 给 `update_plan` / task 工具增加 task-root 绑定
-
-这样不需要重写 loop，只是增强 workspace memory layout。
-
----
-
-## 6. Skills
-
-### 6.1 当前是否支持 skill
-
-支持，但属于 **弱 skill 系统**。
-
-当前 skill 机制分两部分：
-
-1. **Bundled skills**
-   - `BundledSkill` 定义 name / description / when_to_use / aliases / allowed_tools / get_prompt
-   - 见 `src/bundled_skills.py:22-32`
-
-2. **Skill tool**
-   - `_execute_skill()` 优先查 bundled skill
-   - 查不到再退回 slash command
-   - 见 `src/agent_runtime.py:2059-2142`
-
-### 6.2 是否有技能发现机制
-
-有，但只对 bundled skill 生效：
-
-- `format_skills_for_system_prompt()` 把 skill 列表渲染进系统提示，帮助模型“知道”有哪些 skill，见 `src/bundled_skills.py:268-289`
-- GUI 也有 `/api/skills` 列表，见 `src/gui/server.py`
-
-但它没有：
-
-- 从工作区扫描 skill 文件
-- 从 skill 文档按需加载正文
-- skill-level semantic retrieval
-
-### 6.3 是否支持 progressive disclosure
-
-**严格说不支持。**
-
-当前 bundled skill 更像：
-
-- 用户 / 模型选中 skill
-- skill 生成一段 prompt
-- prompt 立即进入模型上下文
-
-并不是：
-
-- 先列 metadata
-- 决定是否需要 skill
-- 再按需读取 skill markdown 正文
-- 只展开相关片段
-
-因此它缺乏真正的 progressive disclosure。
-
-### 6.4 如果没有，应该如何扩展
-
-建议做一个最小可行版 workspace skill system，不破坏现有 loop。
-
-#### 最小改造方案
-
-##### 目录结构
-
-```text
-.claude/skills/
-  review/
-    skill.json
-    SKILL.md
-  data-agent/
-    skill.json
-    SKILL.md
-  python-debug/
-    skill.json
-    SKILL.md
-```
-
-##### metadata
-
-`skill.json` 示例：
-
-```json
-{
-  "name": "data-agent",
-  "description": "Analyze datasets and produce structured markdown reports.",
-  "when_to_use": "When the task involves CSV/JSON/table exploration, metric comparison, or report writing.",
-  "aliases": ["data", "analysis"],
-  "allowed_tools": ["read_file", "write_file", "edit_file", "glob_search", "grep_search", "bash"],
-  "entry_markdown": "SKILL.md"
-}
-```
-
-##### loading 时机
-
-建议两阶段：
-
-1. **session 初始化时只加载 metadata**
-   - 像 bundled skill 一样列进 system prompt
-   - 不把 `SKILL.md` 正文直接注入
-
-2. **当模型选择 Skill 工具时再加载正文**
-   - `Skill(skill="data-agent")`
-   - runtime 读取对应 `SKILL.md`
-   - 返回 skill prompt 或 `<system-reminder>` 包装内容
-
-##### Agent 如何决定读取哪个 skill
-
-沿用现有机制，最小改造即可：
-
-- 在 system prompt 里暴露 `name + description + when_to_use`
-- 模型自己决定是否调用 `Skill`
-- `Skill` 工具负责延迟读取 skill 正文
-
-##### 代码落点
-
-最小改造建议：
-
-- 扩展 `src/bundled_skills.py` 为“bundled + discovered skills”
-- 或新建 `workspace_skills.py`
-- 在 `_execute_skill()` 中优先：
-  1. bundled skill
-  2. workspace discovered skill
-  3. slash command fallback
-
-这个改法不会触碰 loop 主干，只是在 skill lookup 阶段增加一个来源。
-
----
-
-## 7. Policy / Human Gate
-
-### 7.1 如何处理权限
-
-当前权限机制主要有三层。
-
-#### 第一层：启动时权限布尔开关
-
-`AgentPermissions`：
-
-- `allow_file_write`
-- `allow_shell_commands`
-- `allow_destructive_shell_commands`
-
-见 `src/agent_types.py:147-150`。
-
-这是最直接的 runtime gate。
-
-#### 第二层：workspace hook / policy
-
-`HookPolicyRuntime` 支持：
-
-- `trusted`
-- `managed_settings`
-- `safe_env_names`
-- `deny_tools`
-- `deny_tool_prefixes`
-- `before_prompt`
-- `after_turn`
-- `before_tool`
-- `after_tool`
-- `budget_overrides`
-
-见 `src/hook_policy.py:10-22`。
-
-#### 第三层：ask_user runtime
-
-并不是所有危险动作都会自动弹确认框。当前“人工确认”更像一个工具能力：
-
-- `ask_user_question`
-
-也就是说，模型可以选择向用户提问，但 runtime 本身不会像桌面 Codex 那样对每个危险动作自动出现审批 UI。
-
-### 7.2 哪些动作会请求用户确认
-
-严格来说，**默认没有统一的自动确认拦截器**。
-
-当前模式更像：
-
-- 文件写：如果没开 `allow_write`，直接拒绝
-- shell：如果没开 `allow_shell`，直接拒绝
-- destructive shell：如果没开 `--unsafe`，直接拒绝
-- policy deny：直接拒绝
-- ask-user：模型显式调用 `ask_user_question` 才会走人工澄清
-
-因此它偏向：
-
-> hard gate / deny-first，而不是 ask-on-demand 审批流。
-
-### 7.3 哪些动作默认允许
-
-默认允许的是安全读类能力，例如：
-
-- read
-- list
-- search
-- tool discovery
-- runtime status inspection
-
-默认不允许的是：
-
-- 写文件
-- shell
-- destructive shell
-
-具体提示也被写进 system prompt，见 `src/agent_prompting.py:388-401`。
-
-### 7.4 是否有 deny / allow / ask 策略
-
-有 `allow` 与 `deny`，但 `ask` 不是系统级统一策略。
-
-- **allow**：CLI flag / runtime permissions
-- **deny**：hook policy deny_tools / deny_tool_prefixes
-- **ask**：只通过 `ask_user_question` 工具实现，非自动策略
-
-### 7.5 是否支持项目级规则
-
-支持。
-
-项目级规则来自：
-
-- `.claw-policy.json`
-- `.codex-policy.json`
-- `.claw-hooks.json`
-
-并且会沿 cwd 向上目录发现，见 `src/hook_policy.py:160-187`。
-
-### 7.6 对数据 Agent 的不足
-
-如果你们要做数据 Agent，这套 human gate 还有几个明显缺口：
-
-1. **缺少按数据源级别的权限模型**
-   - 没有“允许读 CSV 但不允许发网络请求”这种更细粒度策略
-
-2. **没有结构化审批流**
-   - 例如“将执行 SQL / 访问线上表 / 导出结果集”的 ask approval 缺位
-
-3. **没有数据脱敏/泄露策略**
-   - safe_env 只管环境变量，不管输出内容
-
-4. **没有审计级 action classification**
-   - tool 结果有 metadata，但没有“高风险数据出站/高风险变更”的统一标签体系
-
-5. **policy 更偏 workspace engineering，而不是 data governance**
-
-如果面向数据 Agent，建议增加：
-
-- data source allowlist
-- query approval policy
-- outbound redaction hook
-- result size limits
-- table/column sensitivity policy
-
----
-
-## 8. Trace / Observability
-
-### 8.1 是否记录每一轮模型输入输出
-
-有记录，但“模型输入原文”不单独存为一条日志，而是可由 session transcript 和 system/user context 还原。
-
-保存内容包括：
-
-- `messages` transcript
-- `system_prompt_parts`
-- `user_context`
-- `system_context`
-- `usage`
-- `turns`
-- `tool_calls`
-
-见 `src/session_store.py:53-115`、`src/agent_runtime.py:3269-3345`。
-
-模型输出则直接进入 `assistant` messages。
-
-### 8.2 是否记录工具调用
-
-有，而且记录得比较细：
-
-- transcript 中的 assistant tool_calls
-- transcript 中的 tool result message
-- `events` 中的 `tool_start` / `tool_delta` / `tool_result`
-- `file_history` 中的摘要化变更记录
-
-见 `src/agent_runtime.py:852-1119`。
-
-### 8.3 是否记录文件变更
-
-有，`file_history` 是一个重要机制。
-
-resume 时会把 file_history replay 成一个 `<system-reminder>` 给模型，见：
-
-- `src/agent_runtime.py:2914-3040`
-
-持久化时也会一起保存到 session json，见：
-
-- `src/session_store.py:66`
-- `src/agent_runtime.py:3333`
-
-它不是完整 patch log，但已经记录：
-
-- action
-- path / changed_paths
-- snapshot ids
-- before/after preview
-- result preview
-
-### 8.4 是否有 replay/debug 能力
-
-有基础能力：
-
-- `agent-resume`
-- transcript 持久化
-- file_history replay
-- compaction replay
-- GUI 可以展示 transcript 和 tool calls
-
-但没有一个真正成熟的“调试控制台”或统一 trace viewer。
-
-### 8.5 现有 observability 的优点
-
-优点：
-
-- 数据结构已经齐全：transcript、events、file_history、budget_state、plugin_state
-- session 是 JSON 文件，易于离线分析
-- message metadata 里保留了 mutation lineage / revision 信息
-
-这意味着系统已经具备做更强 observability 的底座。
-
-### 8.6 还缺什么
-
-目前还缺：
-
-1. **完整 prompt snapshot**
-   - 现在有 system/user context 和 transcript，但缺“每轮实际发给模型的最终 payload”落盘
-
-2. **turn-level structured trace**
-   - 比如 `turn_03.json`
-   - 包含 prompt size、tool candidates、selected tool calls、latency、errors
-
-3. **统一 replay viewer**
-   - 现在 resume 偏“继续工作”
-   - 不是“回放调试”
-
-4. **tool latency / error taxonomy**
-   - 有 event，但缺统计聚合
-
-5. **compaction provenance**
-   - 已有 replay，但缺图形化 lineage/summary mapping
-
-### 8.7 如果要补，怎么加
-
-最小建议：
-
-#### 建议新增 trace 目录
-
-```text
-.port_sessions/traces/{session_id}/
-  turn_001.request.json
-  turn_001.response.json
-  turn_001.events.json
-  turn_001.tools.json
-```
-
-#### 每轮保存这些内容
-
-- request
-  - rendered messages
-  - tool specs
-  - token budget snapshot
-- response
-  - raw model response
-  - parsed tool calls
-  - finish_reason
-- tools
-  - tool args
-  - tool result
-  - latency
-- events
-  - 当前 turn 的 event list
-
-#### 代码落点
-
-最合适挂点在：
-
-- `_query_model()` 前后
-- tool loop `for tool_call in turn.tool_calls`
-- `_persist_session()`
-
-这样能复用现有 `session_id` 和 `turn_index`。
-
----
-
-## 总结判断
-
-这个项目已经具备一个完整 coding agent runtime 的主要骨架：
-
-- 有明确的 session 与 transcript 模型
-- 有模型驱动的动态工具循环
-- 有 context injection 与 memory bundle
-- 有 compaction / replay / resume
-- 有较丰富的本地工具和 runtime 子系统
-
-但从“下一代 workspace-native agent platform”的角度看，它还有几个明显缺口：
-
-- skills 仍是 prompt-template 级，未形成 markdown-native progressive disclosure
-- policy 偏 deny/allow，不是强审批流
-- memory 已经文件化，但没有统一 task directory layout
-- observability 有底座，缺一层真正可用的 trace 产品化视图
-
-如果目标是把它改造成更强的“任务型数据 Agent / 文档驱动 Agent / workspace-memory-first Agent”，最值得优先补的不是 loop，而是三件事：
-
-1. **workspace skill discovery + on-demand markdown loading**
-2. **任务目录结构与 memory layout 约定**
-3. **turn-level trace 持久化与 replay viewer**
-
-这三项都可以在不重写 `LocalCodingAgent` 主循环的前提下增量演进。
diff --git a/README.md b/README.md
index 97d0c4f..9fffe25 100644
--- a/README.md
+++ b/README.md
@@ -1,845 +1,933 @@
-<p align="center">
-  <img src="images/logo.png" alt="Claw Code Agent logo" width="420" />
-</p>
+# Claw Code Agent 架构逆向分析报告
 
-<h1 align="center">Claw Code Agent</h1>
-
-<p align="center">
-  <em>A Python reimplementation of the Claude Code agent architecture — local models, full control, zero dependencies.</em>
-</p>
-
-<p align="center">
-  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python 3.10+"></a>
-  <a href="https://github.com/HarnessLab/claw-code-agent"><img src="https://img.shields.io/badge/repo-HarnessLab%2Fclaw--code--agent-181717?logo=github" alt="GitHub"></a>
-  <a href="https://docs.vllm.ai/"><img src="https://img.shields.io/badge/backend-vLLM-FF6F00?logo=lightning&logoColor=white" alt="vLLM"></a>
-  <a href="https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct"><img src="https://img.shields.io/badge/model-Qwen3--Coder-FFD21E?logo=huggingface&logoColor=black" alt="Qwen3-Coder"></a>
-  <img src="https://img.shields.io/badge/dependencies-zero-brightgreen" alt="Zero Dependencies">
-  <img src="https://img.shields.io/badge/status-alpha-orange" alt="Alpha">
-  <img src="https://img.shields.io/badge/license-open--source-green" alt="License">
-</p>
+本文基于只读分析仓库源码撰写，目标不是介绍如何使用，而是回答这个项目作为一个 Agent 系统是如何被构造出来的。
 
 ---
 
-## 📢 What's New
+## 1. 总体定位
 
-> **April 2026 — Major Update**
+### 1.1 这个项目本质上是什么
 
-| | Feature | Details |
-|---|---------|---------|
-| 🆕 | **Interactive Chat Mode** | New `agent-chat` command — multi-turn REPL with `/exit` to quit |
-| 🆕 | **Streaming Output** | Token-by-token streaming with `--stream` flag |
-| 🆕 | **Plugin Runtime** | Full manifest-based plugin system — hooks, tool aliases, virtual tools, tool blocking |
-| 🆕 | **Nested Agent Delegation** | Delegate subtasks to child agents with dependency-aware topological batching |
-| 🆕 | **Agent Manager** | Lineage tracking, group membership, batch summaries for nested agents |
-| 🆕 | **Custom Agent Profiles** | Discover local markdown-defined agents from `~/.claude/agents` and `./.claude/agents` and use them through the `Agent` tool |
-| 🆕 | **Cost Tracking & Budgets** | Token budgets, cost budgets, tool-call limits, model-call limits, session-turn limits |
-| 🆕 | **Structured Output** | JSON schema response mode with `--response-schema-file` |
-| 🆕 | **Context Compaction** | Auto-snip, auto-compact, and reactive compaction on prompt-too-long errors |
-| 🆕 | **File History Replay** | Journaling of file edits with snapshot IDs, replay summaries on session resume |
-| 🆕 | **Truncation Continuation** | Automatic continuation when model response is cut off (`finish_reason=length`) |
-| 🆕 | **Ollama Support** | Works out of the box with Ollama's OpenAI-compatible API |
-| 🆕 | **LiteLLM Proxy Support** | Route through LiteLLM Proxy to any provider |
-| 🆕 | **OpenRouter Support** | Cloud API gateway — access OpenAI, Anthropic, Google models via one endpoint |
-| 🆕 | **Query Engine** | Runtime event counters, transcript summaries, orchestration reports |
-| 🆕 | **Remote Runtime** | Manifest-backed local remote profiles, connect/disconnect state, and remote CLI/slash flows |
-| 🆕 | **Hook & Policy Runtime** | Local `.claw-policy.json` / hook manifests with trust reporting, safe env, tool blocking, and budget overrides |
-| 🆕 | **Task & Plan Runtime** | Persistent local tasks and plans with plan-to-task sync and dependency-aware task execution |
-| 🆕 | **MCP Transport** | Real stdio MCP transport for `initialize`, resource listing/reading, and tool listing/calling |
-| 🆕 | **Search Runtime** | Provider-backed `web_search` with local manifests, activation state, and `/search` flows |
-| 🆕 | **Config & Account Runtime** | Local config/settings mutation plus manifest-backed account profiles and login/logout state |
-| 🆕 | **Ask-User Runtime** | Queued or interactive local ask-user flow with history, slash commands, and agent tool support |
-| 🆕 | **Team Runtime** | Persisted local teams and message history with team/message tools and slash/CLI inspection |
-| 🆕 | **Notebook Edit Tool** | Native `.ipynb` cell editing through the real agent tool registry |
-| 🆕 | **Workflow Runtime** | Manifest-backed local workflows with workflow tools, slash commands, and run history |
-| 🆕 | **Remote Trigger Runtime** | Local remote triggers with create/update/run flows similar to the npm remote trigger surface |
-| 🆕 | **Worktree Runtime** | Managed git worktrees with mid-session cwd switching, slash commands, and CLI flows |
-| 🆕 | **Tokenizer-Aware Context** | Cached tokenizer backends with heuristic fallback for `/context`, `/status`, and compaction |
-| 🆕 | **Prompt Budget Preflight** | Preflight prompt-length validation, token-budget reporting, and auto-compact/context collapse before backend failures |
-| 🆕 | **LSP Runtime** | Local LSP-style code intelligence for definitions, references, hover, symbols, call hierarchy, and diagnostics |
-| 🆕 | **Local Web GUI** | Browser-based chat UI via `python -m src.gui` — modern dark theme, slash command palette, session browser, settings panel |
-| 🆕 | **Daemon Commands** | Local `daemon start/ps/logs/attach/kill` wrapper over background agent sessions |
-| 🆕 | **Background Sessions** | Local `agent-bg`, `agent-ps`, `agent-logs`, `agent-attach`, and `agent-kill` flows |
-| 🆕 | **Testing Guide** | Comprehensive [TESTING_GUIDE.md](TESTING_GUIDE.md) with commands for every feature |
-| 🆕 | **Parity Checklist** | Full [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md) tracking implementation status vs npm source |
+这个项目本质上是一个 **agentic coding runtime**，而不是单纯的 workflow engine，也不只是一个 tool harness。
+
+更准确地说，它处在三者交叉区：
+
+- **最核心身份**：Claude Code / Codex 风格的本地 coding agent runtime
+- **承载方式**：以 Python 实现的 agent loop + tool harness
+- **扩展方式**：外挂了大量 runtime 子系统，例如 search、MCP、plan、task、team、workflow、worktree、plugin、hook policy
+
+因此它不是一个“纯工作流系统”。workflow 在这里是一个被 agent 调用的能力域，而不是系统唯一中心。系统中心仍然是 `LocalCodingAgent` 的多轮模型-工具循环，见 `src/agent_runtime.py:103`、`src/agent_runtime.py:358`。
+
+### 1.2 核心抽象是什么
+
+这个项目有几个关键抽象：
+
+- **Agent**：`LocalCodingAgent`，真正的 orchestrator，负责 prompt 构建、loop、工具调用、budget、session 持久化，见 `src/agent_runtime.py:103`
+- **Session**：`AgentSessionState`，维护系统消息、用户上下文、assistant/tool transcript 以及 mutation lineage，见 `src/agent_session.py:89`
+- **Tool**：`AgentTool` + `ToolExecutionContext`，以 OpenAI function calling 风格对工具进行 schema 化和执行，见 `src/agent_tools.py:44`、`src/agent_tools.py:73`
+- **Prompt Context**：`PromptContext` / `AgentContextSnapshot`，把工作目录、git 状态、CLAUDE.md、各种 runtime 状态拼进模型上下文，见 `src/agent_prompting.py:15`、`src/agent_context.py:40`
+- **StoredAgentSession`**：把完整 transcript、tool_calls、usage、file_history、plugin_state 持久化到 `.port_sessions/agent/*.json`，见 `src/session_store.py:53`
+
+换句话说，它不是围绕“任务节点图”来设计的，而是围绕：
+
+1. 当前 session 里有哪些上下文
+2. 当前模型要不要发起 tool call
+3. tool result 如何再次喂回模型
+4. 何时 compact / stop / persist
+
+### 1.3 与 Claude Code / Codex 的相似点与差异
+
+#### 相似点
+
+- 典型 **LLM-driven tool loop**：模型产出 tool call，runtime 执行工具，再把结果作为 `tool` message 回灌
+- 以 **workspace / repository** 为中心，强依赖文件系统、git 状态、shell、搜索
+- 支持 **系统提示词 + repo memory** 注入，尤其是 `CLAUDE.md`
+- 有 **多轮对话 session**、resume、context compaction、权限 gating
+- 支持 **Agent 子代理 / delegation**
+
+#### 差异点
+
+- 比 Claude Code / Codex 更“runtime platform 化”：这里塞了大量本地 runtime 子系统，如 `task_runtime`、`plan_runtime`、`team_runtime`、`workflow_runtime`、`remote_runtime`、`mcp_runtime`
+- “skills” 实现较轻：当前更像 prompt-template / slash-command bridge，而不是成熟的按需 markdown 技能系统
+- 权限模型相对简化：主要是 CLI 启动时布尔权限 + policy deny，而不是更细粒度的人机交互审批流
+- 可观测性是“有 transcript / event / file_history 基础设施，但 UI 和诊断链条尚未完全产品化”
+
+结论上，这个项目像是：
+
+> 一个以 coding agent loop 为中心、向外扩张成通用本地 agent runtime 平台的 Python 实现。
 
 ---
 
-## 📖 About
-
-This repository reimplements the [Claude Code](https://docs.anthropic.com/en/docs/claude-code) npm agent architecture **entirely in Python**, designed to run with **local open-source models** via an OpenAI-compatible API server.
-
-Built on the public porting workspace from [instructkr/claw-code](https://github.com/instructkr/claw-code), the active development lives at [HarnessLab/claw-code-agent](https://github.com/HarnessLab/claw-code-agent).
-
-> **Goal:** Not to ship the original npm source, but to reimplement the full agent flow in Python — prompt assembly, context building, slash commands, tool calling, session persistence, and local model execution.
->
-> **Zero external dependencies** — just Python's standard library.
-
-<p align="center">
-  <img src="images/demo_2.gif" alt="Claw Code Agent demo" width="900" />
-</p>
-
----
-
-## ✨ Key Features
-
-| Feature | Description |
-|---------|-------------|
-| 🤖 **Agent Loop** | Full agentic coding loop with tool calling and iterative reasoning |
-| 💬 **Interactive Chat** | Multi-turn REPL via `agent-chat` with session continuity |
-| 🖥️ **Local Web GUI** | Browser-based chat UI launched with `python -m src.gui` — sessions browser, slash command palette, live settings |
-| 🧰 **Core Tools** | File read / write / edit, glob search, grep search, shell execution |
-| 🔌 **Plugin Runtime** | Manifest-based plugins with hooks, aliases, virtual tools, and tool blocking |
-| 🪆 **Nested Delegation** | Delegate subtasks to child agents with dependency-aware topological batching |
-| 🧩 **Custom Agents** | Load local agent profiles from `~/.claude/agents` and `./.claude/agents`, inspect them via `/agents`, and delegate with `subagent_type` |
-| 📡 **Streaming** | Token-by-token streaming output with `--stream` |
-| 💬 **Slash Commands** | Local commands for context, config, account, search, MCP, remote, tasks, plan, hooks, and model control |
-| 🌐 **Remote Runtime** | Manifest-backed remote profiles with local `remote-mode`, `ssh-mode`, `teleport-mode`, and connect/disconnect state |
-| 🧭 **Task & Plan Runtime** | Persistent tasks and plans with sync, next-task selection, and blocked/unblocked state |
-| 🛰️ **MCP Runtime** | Local MCP manifests plus real stdio MCP transport for resources and tools |
-| 🔎 **Search Runtime** | Provider-backed `web_search` plus provider activation and status reporting |
-| ⚙️ **Config & Account Runtime** | Local config mutation, settings inspection, account profiles, and login/logout state |
-| 🙋 **Ask-User Runtime** | Queued answer or interactive user-question flow with history tracking |
-| 👥 **Team Runtime** | Persisted local teams plus message history, handoff notes, and collaboration metadata |
-| 📓 **Notebook Editing** | Native Jupyter notebook cell editing through `notebook_edit` |
-| 🪵 **Worktree Runtime** | Managed git worktrees with `worktree_enter`, `worktree_exit`, and live cwd switching |
-| 🧭 **Workflow Runtime** | Manifest-backed workflows with slash commands, CLI inspection, and recorded runs |
-| ⏰ **Remote Triggers** | Local remote triggers with create/update/run flows and npm-style trigger actions |
-| 🪝 **Hook & Policy Runtime** | Trust reporting, safe env, managed settings, tool blocking, and budget overrides |
-| 🧠 **LSP Code Intelligence** | Local LSP-style definitions, references, hover, symbols, diagnostics, and call hierarchy |
-| 🧠 **Context Engine** | Automatic context building with CLAUDE.md discovery, compaction, and snipping |
-| 🔢 **Tokenizer-Aware Accounting** | Model-aware token counting with cached tokenizer backends and fallback heuristics |
-| 📏 **Prompt Budgeting** | Soft/hard prompt-window checks, token-budget reports, and preflight context collapse |
-| 🔄 **Session Persistence** | Save and resume agent sessions with file-history replay |
-| 🗂️ **Background Sessions** | `agent-bg` and local daemon wrappers for background runs, logs, attach, and kill |
-| 💰 **Cost & Budget Control** | Token budgets, cost limits, tool-call caps, model-call caps |
-| 📋 **Structured Output** | JSON schema response mode for programmatic use |
-| 🔐 **Permission System** | Granular control: `--allow-write`, `--allow-shell`, `--unsafe` |
-| 🏗️ **OpenAI-Compatible** | Works with vLLM, Ollama, LiteLLM Proxy, OpenRouter — any OpenAI-compatible API |
-| 🐉 **Qwen3-Coder** | First-class support for `Qwen3-Coder-30B-A3B-Instruct` via vLLM |
-| 📦 **Zero Dependencies** | Pure Python standard library — nothing to install |
-
----
-
-## 📋 Roadmap
-
-### 📚 Documentation
-
-| Document | Description |
-|----------|-------------|
-| [TESTING_GUIDE.md](TESTING_GUIDE.md) | Step-by-step commands to verify every feature |
-| [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md) | Full implementation status vs the npm source |
-
-### ✅ Done
-
-- [x] Python CLI agent loop
-- [x] Interactive chat mode (`agent-chat`) with multi-turn REPL
-- [x] OpenAI-compatible local model backend
-- [x] Qwen3-Coder support through vLLM with `qwen3_xml` tool parser
-- [x] Ollama, LiteLLM Proxy, and OpenRouter backends
-- [x] Core tools: `list_dir`, `read_file`, `write_file`, `edit_file`, `glob_search`, `grep_search`, `bash`
-- [x] Context building and `/context`-style usage reporting
-- [x] Slash commands: `/help`, `/context`, `/context-raw`, `/token-budget`, `/prompt`, `/permissions`, `/model`, `/tools`, `/agents`, `/memory`, `/status`, `/clear`
-- [x] Session persistence and `agent-resume` flow
-- [x] Permission system (read-only, write, shell, unsafe tiers)
-- [x] Streaming token-by-token assistant output
-- [x] Truncated-response continuation flow
-- [x] Auto-snip and auto-compact context reduction
-- [x] Reactive compaction retry on prompt-too-long errors
-- [x] Preflight prompt-length validation and token-budget reporting
-- [x] Preflight auto-compact/context collapse before backend prompt-too-long failures
-- [x] Cost tracking and usage budget enforcement
-- [x] Token, tool-call, model-call, and session-turn budgets
-- [x] Structured output / JSON schema response mode
-- [x] File history journaling with snapshot IDs and replay summaries
-- [x] Nested agent delegation with dependency-aware topological batching
-- [x] Agent manager with lineage tracking and group membership
-- [x] Filesystem-backed custom agent profiles with built-in/user/project precedence
-- [x] Local custom-agent create/update/delete flows via CLI and `/agents`
-- [x] Local daemon-style background command family
-- [x] Local background session workflows: `agent-bg`, `agent-ps`, `agent-logs`, `agent-attach`, `agent-kill`
-- [x] Local remote runtime: manifest discovery, profile listing, connect/disconnect persistence, and CLI/slash flows
-- [x] Local hook and policy runtime with trust reporting, safe env, tool blocking, and budget overrides
-- [x] Local config runtime: config discovery, effective settings, source inspection, and config mutation
-- [x] Local LSP runtime: definitions, references, hover, symbols, diagnostics, and call hierarchy
-- [x] Local account runtime: profile discovery, login/logout state, and account CLI/slash flows
-- [x] Local ask-user runtime: queued answers, history, and ask-user CLI/slash flows
-- [x] Local team runtime: persisted teams, team messages, and team CLI/slash flows
-- [x] Local search runtime with provider discovery, activation, and provider-backed `web_search`
-- [x] Local MCP runtime: manifest resources, stdio transport, MCP resources, and MCP tool calls
-- [x] Local task and plan runtimes with plan sync and dependency-aware task execution
-- [x] Notebook edit tool in the real Python tool registry
-- [x] Local workflow runtime with workflow list/get/run tools and CLI/slash flows
-- [x] Local remote trigger runtime with create/update/run flows and CLI/slash inspection
-- [x] Local managed git worktree runtime with live cwd switching and worktree CLI/slash flows
-- [x] Local web GUI (FastAPI + vanilla JS SPA) with chat, sessions browser, slash command palette, and live settings (`python -m src.gui`)
-- [x] Tokenizer-aware context accounting with cached tokenizer backends and heuristic fallback
-- [x] Plugin runtime: manifest discovery, hooks, aliases, virtual tools, tool blocking
-- [x] Plugin lifecycle hooks: resume, persist, delegate phases
-- [x] Plugin session-state persistence and resume restoration
-- [x] Query engine facade driving the real Python runtime
-- [x] Compaction metadata with lineage IDs and revision summaries
-- [x] Extended runtime tools: `web_fetch`, `web_search`, `tool_search`, `sleep`
-- [x] Unit tests for the Python runtime
-- [x] `pyproject.toml` packaging with `setuptools`
-
-### 🔲 In Progress
-
-- [ ] Full MCP parity beyond the current stdio transport and local manifest/resource/tool support
-- [ ] Full slash-command parity with npm runtime
-- [ ] Full interactive REPL / TUI behavior
-- [ ] Full tokenizer/chat-message framing parity beyond the current tokenizer-aware accounting
-- [ ] Hooks system parity
-- [ ] Real remote transport/runtime parity beyond the current local remote-profile runtime
-- [ ] Voice and VIM modes
-- [ ] Editor and platform integrations
-- [ ] Background and team features
-
----
-
-## 🏗️ Architecture
-
-```text
-claw-code/
-├── README.md
-├── TESTING_GUIDE.md              # How to test every feature
-├── PARITY_CHECKLIST.md           # Implementation status vs npm source
-├── pyproject.toml
-├── .gitignore
-├── images/
-│   └── logo.png
-├── src/                          # Python implementation
-│   ├── main.py                   # CLI entry point & argument parsing
-│   ├── agent_runtime.py          # Core agent loop (LocalCodingAgent)
-│   ├── agent_tools.py            # Tool definitions & execution engine
-│   ├── agent_prompting.py        # System prompt assembly
-│   ├── agent_registry.py         # Built-in + filesystem-backed custom agent discovery
-│   ├── agent_context.py          # Context building & CLAUDE.md discovery
-│   ├── agent_context_usage.py    # Context usage estimation & reporting
-│   ├── agent_session.py          # Session state management
-│   ├── agent_slash_commands.py   # Local slash command processing
-│   ├── agent_manager.py          # Nested agent lineage & group tracking
-│   ├── agent_types.py            # Shared dataclasses & type definitions
-│   ├── openai_compat.py          # OpenAI-compatible API client (streaming)
-│   ├── plugin_runtime.py         # Plugin manifest, hooks, aliases, virtual tools
-│   ├── agent_plugin_cache.py     # Plugin discovery & prompt injection cache
-│   ├── session_store.py          # Session serialization & persistence
-│   ├── transcript.py             # Transcript block export & mutation tracking
-│   ├── query_engine.py           # Query engine facade & runtime orchestration
-│   ├── mcp_runtime.py            # Local MCP discovery and stdio MCP transport
-│   ├── search_runtime.py         # Search providers and provider-backed web_search
-│   ├── remote_runtime.py         # Local remote profiles, connect/disconnect state, remote CLI support
-│   ├── background_runtime.py     # Local background sessions and daemon support
-│   ├── account_runtime.py        # Local account profiles, login/logout state, account CLI support
-│   ├── ask_user_runtime.py       # Local ask-user queued answers and interaction history
-│   ├── config_runtime.py         # Local workspace config/settings discovery and mutation
-│   ├── lsp_runtime.py            # Local LSP-style code intelligence and diagnostics
-│   ├── token_budget.py           # Prompt-window budgeting and preflight prompt-length validation
-│   ├── plan_runtime.py           # Persistent plan runtime and plan sync
-│   ├── task_runtime.py           # Persistent task runtime and task execution
-│   ├── task.py                   # Task state model and task dataclasses
-│   ├── team_runtime.py           # Local teams, messages, and collaboration metadata
-│   ├── workflow_runtime.py       # Local workflow manifests and recorded workflow runs
-│   ├── remote_trigger_runtime.py # Local remote trigger manifests and trigger run history
-│   ├── worktree_runtime.py       # Managed git worktree sessions and cwd switching
-│   ├── hook_policy.py            # Hook/policy manifests, trust, and safe env handling
-│   ├── tokenizer_runtime.py      # Tokenizer-aware context accounting backends
-│   ├── permissions.py            # Tool permission filtering
-│   ├── cost_tracker.py           # Cost & budget enforcement
-│   ├── commands.py               # Mirrored command inventory
-│   ├── tools.py                  # Mirrored tool inventory
-│   ├── runtime.py                # Mirrored runtime facade
-│   ├── reference_data/           # Mirrored inventory snapshots
-│   └── gui/                      # Local web GUI (FastAPI + vanilla JS SPA)
-│       ├── __main__.py           # `python -m src.gui` entry point
-│       ├── server.py             # FastAPI app and JSON endpoints
-│       └── static/               # index.html, app.css, app.js
-└── tests/                        # Unit tests
-    ├── test_agent_runtime.py
-    ├── test_agent_context.py
-    ├── test_agent_context_usage.py
-    ├── test_agent_prompting.py
-    ├── test_agent_slash_commands.py
-    ├── test_main.py
-    ├── test_query_engine_runtime.py
-    └── test_porting_workspace.py
-```
-
----
-
-## 📦 Requirements
-
-| Requirement | Details |
-|-------------|---------|
-| 🐍 Python | `3.10` or higher |
-| 📚 Dependencies | **None** — pure Python standard library |
-| 🖥️ Model Server | `vLLM`, `Ollama`, `LiteLLM Proxy`, or `OpenRouter`, with tool calling support |
-| 🧠 Model | [`Qwen/Qwen3-Coder-30B-A3B-Instruct`](https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct) (recommended) |
-
----
-
-## 🚀 Quick Start
-
-### 1. Start vLLM with Qwen3-Coder
-
-vLLM must be started with automatic tool choice enabled. Use the `qwen3_xml` parser for Qwen3-Coder tool calling:
-
-```bash
-python -m vllm.entrypoints.openai.api_server \
-  --model Qwen/Qwen3-Coder-30B-A3B-Instruct \
-  --host 127.0.0.1 \
-  --port 8000 \
-  --enable-auto-tool-choice \
-  --tool-call-parser qwen3_xml
-```
-
-Verify the server is running:
-
-```bash
-curl http://127.0.0.1:8000/v1/models
-```
-
-> 📚 **References:** [vLLM Tool Calling Docs](https://docs.vllm.ai/en/v0.13.0/features/tool_calling/) · [OpenAI-Compatible Server](https://docs.vllm.ai/en/v0.13.0/serving/openai_compatible_server.html)
-
-### Optional: Use Ollama Instead of vLLM
-
-`claw-code-agent` can also work with Ollama because the runtime targets an OpenAI-compatible API. Use a model that supports tool calling well.
-
-Example:
-
-```bash
-ollama serve
-ollama pull qwen3
-```
-
-Then configure:
-
-```bash
-export OPENAI_BASE_URL=http://127.0.0.1:11434/v1
-export OPENAI_API_KEY=ollama
-export OPENAI_MODEL=qwen3
-```
-
-Notes:
-
-- prefer tool-capable models such as `qwen3`
-- plain chat-only models are not enough for full agent behavior
-- Ollama does not use the `vLLM` parser flags shown above
+## 2. Agent Loop
 
-> 📚 **References:** [Ollama OpenAI Compatibility](https://docs.ollama.com/api/openai-compatibility) · [Ollama Tool Calling](https://docs.ollama.com/capabilities/tool-calling)
+### 2.1 主循环入口
 
-### Optional: Use LiteLLM Proxy
+真实入口是 `LocalCodingAgent.run()`，它生成 `session_id`、scratchpad 目录，然后进入 `_run_prompt()`，见：
 
-`claw-code-agent` can also work through LiteLLM Proxy because the runtime targets an OpenAI-compatible chat completions API. The routed model still needs to support tool calling for full agent behavior.
+- `src/agent_runtime.py:358`
+- `src/agent_runtime.py:413`
 
-Quick start example:
+恢复会话则走 `resume()`，它把持久化 session 反序列化成 `AgentSessionState`，并补充 file history replay 与 compaction replay，见 `src/agent_runtime.py:376`。
 
-```bash
-pip install 'litellm[proxy]'
-litellm --model ollama/qwen3
-```
+### 2.2 每轮如何观察当前状态
 
-LiteLLM Proxy runs on port `4000` by default. Then configure:
+Agent 的“观察”不是通过一个单独的 observe() 函数完成，而是在 loop 外预构建 session，并在每轮前做上下文压力处理：
 
-```bash
-export OPENAI_BASE_URL=http://127.0.0.1:4000
-export OPENAI_API_KEY=anything
-export OPENAI_MODEL=ollama/qwen3
-```
+1. **启动时构建 prompt context**
+   - `build_prompt_context()` -> `build_context_snapshot()`
+   - 汇总 cwd、platform、git status、scratchpad、CLAUDE.md bundle、各 runtime summary
+   - 见 `src/agent_runtime.py:240` 左右、`src/agent_prompting.py:30`、`src/agent_context.py:71`
 
-Notes:
+2. **构建初始 session**
+   - `build_session()` 使用 system prompt parts + user_context/system_context 生成 session
+   - `AgentSessionState.create()` 会插入：
+     - `system` message
+     - `user_context reminder`
+     - 当前用户 prompt
+   - 见 `src/agent_runtime.py:255` 左右、`src/agent_session.py:97`
 
-- LiteLLM Proxy gives you an OpenAI-style gateway in front of many providers
-- tool use still depends on the underlying routed model and provider behavior
-- if you configure a LiteLLM master key, use that instead of `anything`
+3. **每轮前的状态整理**
+   - `_microcompact_session_if_needed()`
+   - `_snip_session_if_needed()`
+   - `_compact_session_if_needed()`
+   - `_preflight_prompt_length()`
+   - 见 `src/agent_runtime.py:527-547`
 
-> 📚 **References:** [LiteLLM Docs](https://docs.litellm.ai/) · [LiteLLM Proxy Quick Start](https://docs.litellm.ai/)
+因此，“观察当前状态”既包括文件系统 / git / runtime summary，也包括自身历史 transcript 的压缩后视图。
 
-### Optional: Use OpenRouter
+### 2.3 如何构造上下文
 
-`claw-code-agent` can also work with [OpenRouter](https://openrouter.ai/), a cloud API gateway that provides access to models from OpenAI, Anthropic, Google, Meta, and others through a single OpenAI-compatible endpoint. No local model server required.
+上下文构造分两层：
 
-Configure:
+#### 第一层：环境与 memory 采样
 
-```bash
-export OPENAI_BASE_URL=https://openrouter.ai/api/v1
-export OPENAI_API_KEY=sk-or-v1-your-key-here
-export OPENAI_MODEL=openai/gpt-4o-mini
-```
+`src/agent_context.py` 负责采样：
 
-Notes:
+- cwd、shell、platform、date
+- git status snapshot，见 `src/agent_context.py:279`
+- scratchpad directory，见 `src/agent_context.py:197`
+- `CLAUDE.md` / `.claude/CLAUDE.md` / `CLAUDE.local.md` / `.claude/rules/*.md` bundle，见 `src/agent_context.py:313-372`
+- plugin / hook policy / MCP / remote / search / account / ask_user / config / LSP / plan / task / team / workflow / worktree 的 runtime summary，见 `src/agent_context.py:205-275`
 
-- sign up at [openrouter.ai](https://openrouter.ai/) and create an API key under [Keys](https://openrouter.ai/keys)
-- model names use the `provider/model` format (e.g. `anthropic/claude-sonnet-4`, `openai/gpt-4o`, `google/gemini-2.5-pro`)
-- tool calling support varies by model — check the [model list](https://openrouter.ai/models) for capabilities
-- this sends your conversation (including file contents and shell output) to OpenRouter and the upstream provider — do not use with repos containing secrets or sensitive data
+#### 第二层：系统提示词装配
 
-> 📚 **References:** [OpenRouter Docs](https://openrouter.ai/docs) · [Supported Models](https://openrouter.ai/models) · [API Keys](https://openrouter.ai/keys)
+`build_system_prompt_parts()` 会拼接：
 
-### 2. Configure Environment
+- system instructions
+- doing tasks guidance
+- tool usage guidance
+- agent guidance
+- plugin / MCP / search / account / ask-user / config / LSP / plan / task / team / hook policy guidance
+- session-specific permission guidance
+- simple env info
 
-```bash
-export OPENAI_BASE_URL=http://127.0.0.1:8000/v1
-export OPENAI_API_KEY=local-token
-export OPENAI_MODEL=Qwen/Qwen3-Coder-30B-A3B-Instruct
-```
+见 `src/agent_prompting.py:75-119`。
 
-### Use Another Model With vLLM
+也就是说，这个项目的上下文不是“只把聊天记录喂给模型”，而是：
 
-If you want to try another model, keep the same `vLLM` server setup and change the `--model` value when you launch `vLLM`.
+> transcript + injected local memory + runtime summaries + environment facts + permissions hints
 
-Example:
+### 2.4 如何决定下一步行动
 
-```bash
-python -m vllm.entrypoints.openai.api_server \
-  --model your-model-name \
-  --host 127.0.0.1 \
-  --port 8000 \
-  --enable-auto-tool-choice \
-  --tool-call-parser your_parser
-```
+行动选择主要由模型驱动。
 
-Then update:
+每轮中 runtime 做的事情是：
 
-```bash
-export OPENAI_MODEL=your-model-name
-```
-
-Notes:
-
-- the documented path in this repository is `vLLM`
-- the model must support tool calling well enough for agent use
-- some model families require a different `--tool-call-parser`
-- slash commands such as `/help`, `/context`, and `/tools` are local and do not require the model server
-
-### 3. Run the Agent
-
-```bash
-# Read-only question
-python3 -m src.main agent \
-  "Read src/agent_runtime.py and summarize how the loop works." \
-  --cwd .
-
-# Write-enabled task
-python3 -m src.main agent \
-  "Create TEST_QWEN_AGENT.md with one line: test ok" \
-  --cwd . --allow-write
-
-# Shell-enabled task
-python3 -m src.main agent \
-  "Run pwd and ls src, then summarize the result." \
-  --cwd . --allow-shell
-
-# Interactive chat mode
-python3 -m src.main agent-chat --cwd .
-
-# Streaming output
-python3 -m src.main agent \
-  "Explain the current architecture." \
-  --cwd . --stream
-```
-
----
-
-## 🛠️ Usage
-
-### Agent Commands
-
-| Command | Description |
-|---------|-------------|
-| `agent <prompt>` | Run the agent with a prompt |
-| `agent-chat [prompt]` | Start interactive multi-turn chat mode |
-| `agent-bg <prompt>` | Run the agent in a local background session |
-| `agent-ps` | List local background sessions |
-| `agent-logs <id>` | Show background session logs |
-| `agent-attach <id>` | Show the current background output snapshot |
-| `agent-kill <id>` | Stop a background session |
-| `daemon <subcommand>` | Daemon-style wrapper over local background sessions |
-| `agent-prompt` | Show the assembled system prompt |
-| `agent-context` | Show estimated context usage |
-| `agent-context-raw` | Show the raw context snapshot |
-| `token-budget` | Show prompt-window budget, reserves, and soft/hard input limits |
-| `agents [agent_type]` | List active local agent definitions or show one agent profile |
-| `agents-create <agent_type>` | Create a project or user agent definition markdown file |
-| `agents-update <agent_type>` | Update an existing project or user agent definition |
-| `agents-delete <agent_type>` | Delete an existing project or user agent definition |
-| `agent-resume <id> <prompt>` | Resume a saved session |
-
-### Runtime Utility Commands
-
-| Command | Description |
-|---------|-------------|
-| `search-status` / `search-providers` / `search-activate` / `search` | Inspect and use the local search runtime |
-| `mcp-status` / `mcp-resources` / `mcp-resource` / `mcp-tools` / `mcp-call-tool` | Inspect and use the local MCP runtime |
-| `remote-status` / `remote-profiles` / `remote-disconnect` | Inspect local remote runtime state |
-| `remote-mode` / `ssh-mode` / `teleport-mode` / `direct-connect-mode` / `deep-link-mode` | Activate local remote runtime modes |
-| `config-status` / `config-effective` / `config-source` / `config-get` / `config-set` | Inspect and mutate local config/settings |
-| `account-status` / `account-profiles` / `account-login` / `account-logout` | Inspect and mutate local account state |
-
-### CLI Flags
-
-| Flag | Description |
-|------|-------------|
-| `--cwd <path>` | Set the workspace directory |
-| `--model <name>` | Override the model name |
-| `--base-url <url>` | Override the API base URL |
-| `--allow-write` | Allow the agent to modify files |
-| `--allow-shell` | Allow the agent to execute shell commands |
-| `--unsafe` | Allow destructive shell operations |
-| `--stream` | Enable token-by-token streaming output |
-| `--show-transcript` | Print the full message transcript |
-| `--scratchpad-root <path>` | Override the scratchpad directory |
-| `--system-prompt <text>` | Set a custom system prompt |
-| `--append-system-prompt <text>` | Append to the system prompt |
-| `--override-system-prompt <text>` | Replace the generated system prompt |
-| `--add-dir <path>` | Add extra directories to context |
-
-### Budget & Limit Flags
-
-| Flag | Description |
-|------|-------------|
-| `--max-total-tokens <n>` | Total token budget |
-| `--max-input-tokens <n>` | Input token budget |
-| `--max-output-tokens <n>` | Output token budget |
-| `--max-reasoning-tokens <n>` | Reasoning token budget |
-| `--max-budget-usd <n>` | Maximum cost in USD |
-| `--max-tool-calls <n>` | Maximum tool calls per run |
-| `--max-delegated-tasks <n>` | Maximum delegated subtasks |
-| `--max-model-calls <n>` | Maximum model API calls |
-| `--max-session-turns <n>` | Maximum session turns |
-| `--input-cost-per-million <n>` | Input token pricing |
-| `--output-cost-per-million <n>` | Output token pricing |
-
-### Context Control Flags
-
-| Flag | Description |
-|------|-------------|
-| `--auto-snip-threshold <n>` | Auto-snip older messages at this token count |
-| `--auto-compact-threshold <n>` | Auto-compact at this token count |
-| `--compact-preserve-messages <n>` | Messages to preserve during compaction |
-| `--disable-claude-md` | Disable CLAUDE.md discovery |
-
-### Structured Output Flags
-
-| Flag | Description |
-|------|-------------|
-| `--response-schema-file <path>` | JSON schema file for structured output |
-| `--response-schema-name <name>` | Schema name identifier |
-| `--response-schema-strict` | Enforce strict schema validation |
-
-### Slash Commands
-
-These are handled **locally** before the model loop:
-
-| Command | Aliases | Description |
-|---------|---------|-------------|
-| `/help` | `/commands` | Show built-in slash commands |
-| `/context` | `/usage` | Show estimated session context usage |
-| `/context-raw` | `/env` | Show raw environment & context snapshot |
-| `/token-budget` | `/budget` | Show prompt-window budget, reserves, and soft/hard input limits |
-| `/mcp` | — | Show MCP runtime status, tools, or a single MCP tool |
-| `/resources` | — | List MCP resources |
-| `/resource` | — | Read an MCP resource by URI |
-| `/search` | — | Show search status, providers, activate a provider, or run a search |
-| `/remote` | — | Show local remote status or activate a target |
-| `/remotes` | — | List local remote profiles |
-| `/ssh` | — | Activate an SSH-style remote profile |
-| `/teleport` | — | Activate a teleport-style remote profile |
-| `/direct-connect` | — | Activate a direct-connect remote profile |
-| `/deep-link` | — | Activate a deep-link remote profile |
-| `/disconnect` | `/remote-disconnect` | Disconnect the active remote runtime target |
-| `/account` | — | Show account runtime status or profiles |
-| `/login` | — | Activate a local account profile or identity |
-| `/logout` | — | Clear the active account session |
-| `/config` | `/settings` | Inspect effective config, sources, or a single config value |
-| `/plan` | `/planner` | Show the local plan runtime state |
-| `/tasks` | `/todo` | Show the local task list |
-| `/task` | — | Show a task by id |
-| `/task-next` | `/next-task` | Show the next actionable tasks |
-| `/prompt` | `/system-prompt` | Render the effective system prompt |
-| `/hooks` | `/policy` | Show local hook/policy manifests |
-| `/trust` | — | Show trust mode, managed settings, and safe env values |
-| `/permissions` | — | Show active tool permission mode |
-| `/model` | — | Show or update the active model |
-| `/tools` | — | List registered tools with permission status |
-| `/agents` | — | List, show, create, update, or delete local agent definitions |
-| `/memory` | — | Show loaded CLAUDE.md memory bundle |
-| `/status` | `/session` | Show runtime/session status summary |
-| `/clear` | — | Clear ephemeral runtime state |
-
-```bash
-python3 -m src.main agent "/help"
-python3 -m src.main agent "/context" --cwd .
-python3 -m src.main agent "/token-budget" --cwd .
-python3 -m src.main agent "/tools" --cwd .
-python3 -m src.main agent "/agents" --cwd .
-python3 -m src.main agent "/status" --cwd .
-```
-
-### Custom Agent Definitions
-
-Custom agent profiles can live in either of these directories:
-
-- `./.claude/agents/*.md`
-- `~/.claude/agents/*.md`
-
-Project agents override user agents, and user agents override built-ins when the `agent_type` matches.
-
-Example agent file:
-
-```md
----
-name: reviewer
-description: "Review implementation changes carefully."
-tools: read_file, grep_search
-model: Qwen/Qwen3-Coder-30B-A3B-Instruct
-initialPrompt: Start by identifying the highest-risk files.
----
-
-Inspect code changes and summarize correctness risks, regressions, and missing tests.
-```
-
-Inspect the loaded profiles:
-
-```bash
-python3 -m src.main agents --cwd .
-python3 -m src.main agents reviewer --cwd .
-python3 -m src.main agent "/agents" --cwd .
-python3 -m src.main agent "/agents show reviewer" --cwd .
-```
-
-Create, update, or delete agent files from the CLI:
-
-```bash
-python3 -m src.main agents-create reviewer \
-  --cwd . \
-  --description "Review implementation changes carefully." \
-  --prompt "Inspect code changes and summarize risks." \
-  --tools read_file,grep_search \
-  --model Qwen/Qwen3-Coder-30B-A3B-Instruct
-
-python3 -m src.main agents-update reviewer \
-  --cwd . \
-  --description "Review implementation changes and tests carefully." \
-  --prompt "Focus on regressions, missing tests, and risky diffs."
-
-python3 -m src.main agents-delete reviewer --cwd . --source project
-```
-
-Or use the local slash command management forms:
-
-```bash
-python3 -m src.main agent "/agents create reviewer :: Review implementation changes carefully. :: Inspect code changes and summarize risks." --cwd .
-python3 -m src.main agent "/agents update reviewer Updated review description :: Focus on regressions and missing tests." --cwd .
-python3 -m src.main agent "/agents delete reviewer" --cwd .
-```
-
-### Utility Commands
-
-```bash
-python3 -m src.main summary            # Workspace summary
-python3 -m src.main manifest           # Workspace manifest
-python3 -m src.main commands --limit 10 # Command inventory
-python3 -m src.main tools --limit 10    # Tool inventory
-```
-
----
-
-## 🔧 Built-in Tools
-
-The runtime currently includes core and extended tools:
-
-| Tool | Description | Permission |
-|------|-------------|------------|
-| `list_dir` | List files and directories | 🟢 Always |
-| `read_file` | Read file contents (with line ranges) | 🟢 Always |
-| `write_file` | Write or create files | 🟡 `--allow-write` |
-| `edit_file` | Edit files via exact string matching | 🟡 `--allow-write` |
-| `glob_search` | Find files by glob pattern | 🟢 Always |
-| `grep_search` | Search file contents by regex | 🟢 Always |
-| `bash` | Execute shell commands | 🔴 `--allow-shell` |
-| `web_fetch` | Fetch local or remote text content by URL | 🟢 Always |
-| `search_status` / `search_list_providers` / `search_activate_provider` / `web_search` | Search runtime status and provider-backed web search | 🟢 Always |
-| `tool_search` | Search the current Python tool registry | 🟢 Always |
-| `sleep` | Bounded local wait tool | 🟢 Always |
-| `config_list` / `config_get` / `config_set` | Inspect and mutate local workspace config | `config_set` is 🟡 `--allow-write` |
-| `account_status` / `account_list_profiles` / `account_login` / `account_logout` | Inspect and mutate local account state | 🟢 Always |
-| `remote_status` / `remote_list_profiles` / `remote_connect` / `remote_disconnect` | Inspect and mutate local remote runtime state | 🟢 Always |
-| `mcp_list_resources` / `mcp_read_resource` / `mcp_list_tools` / `mcp_call_tool` | Use local MCP resources and transport-backed MCP tools | 🟢 Always |
-| `plan_get` / `update_plan` / `plan_clear` | Inspect and mutate the local plan runtime | `update_plan` is 🟡 `--allow-write` |
-| `task_next` / `task_list` / `task_get` / `task_create` / `task_update` / `task_start` / `task_complete` / `task_block` / `task_cancel` / `todo_write` | Persistent local task and todo management | write-like task mutations are 🟡 `--allow-write` |
-| `delegate_agent` | Delegate work to nested child agents | 🟢 Always |
-
----
-
-## 🔌 Plugin System
-
-Claw Code Agent supports a **manifest-based plugin runtime**. Drop a `plugin.json` in a `plugins/` subdirectory:
+1. 把 `session.to_openai_messages()` 和 `tool_specs` 发给模型，见 `src/agent_runtime.py:1153-1157`
+2. 从返回中解析：
+   - 普通 assistant content
+   - tool calls
+   - finish_reason
+   - usage
+3. 若无 tool call，则视作模型选择直接回答
+4. 若有 tool call，则 runtime 执行这些工具，再把工具结果回灌到 session
+
+真正的“决策”是模型自己通过 OpenAI tool calling 选择的，而不是 runtime 用规则树规划下一步。
+
+因此 loop 属于：
+
+- **外层固定流程**
+- **内层模型驱动的动态行动选择**
+
+### 2.5 如何调用工具
+
+工具定义为 `AgentTool`，带：
+
+- `name`
+- `description`
+- JSON Schema 参数定义 `parameters`
+- `handler`
+
+见 `src/agent_tools.py:73-111`。
+
+每轮把所有工具变成 OpenAI function spec：
+
+- `tool_specs = [tool.to_openai_tool() for tool in self.tool_registry.values()]`
+- 见 `src/agent_runtime.py:463`
+
+模型返回 tool call 后，主循环在 `src/agent_runtime.py:808-1119` 中执行：
+
+- 创建一个 tool message 占位 `session.start_tool(...)`
+- 记录 `tool_start` event
+- 应用 plugin / hook policy preflight
+- 执行 delegate / Skill / 普通 tool
+- 以 `serialize_tool_result()` 将结果序列化成 JSON 字符串写回 transcript
+
+### 2.6 工具结果如何回到模型上下文
+
+工具结果通过 `session.finalize_tool(...)` 变成一个 `role='tool'` 的 message，内容是：
 
 ```json
 {
-  "name": "my-plugin",
-  "hooks": {
-    "beforePrompt": "Inject guidance into the system prompt.",
-    "afterTurn": "Run after each agent turn.",
-    "onResume": "Reapply state on session resume.",
-    "beforePersist": "Save state before session is saved.",
-    "beforeDelegate": "Inject guidance before child agents.",
-    "afterDelegate": "Process child agent results."
-  },
-  "toolAliases": [
-    { "name": "my_read", "baseTool": "read_file", "description": "Custom read alias." }
-  ],
-  "virtualTools": [
-    { "name": "my_tool", "description": "A virtual tool.", "responseTemplate": "result: {input}" }
-  ]
+  "tool": "...",
+  "ok": true/false,
+  "content": "...",
+  "metadata": {...}
 }
 ```
 
-> See [TESTING_GUIDE.md](TESTING_GUIDE.md) **Section 19** for full plugin testing commands.
+见：
+
+- `src/agent_tools.py:1248`
+- `src/agent_runtime.py:1037-1047`
+
+下一轮模型调用时，`session.to_openai_messages()` 会把这些 tool messages 一并送回模型。因此工具结果不是旁路状态，而是标准 transcript 的一部分。
+
+### 2.7 什么时候停止
+
+停止条件有多类：
+
+- **模型正常回答且无 tool_calls**：结束，见 `src/agent_runtime.py:764-806`
+- **finish_reason = length/max_tokens**：自动注入 continuation prompt，再继续一轮，见 `src/agent_runtime.py:766-783`
+- **budget exceeded**：停止，见 `src/agent_runtime.py:500-525`、`552-581`、`733-762`
+- **prompt too long / preflight fail**：停止或先 compact 再试，见 `src/agent_runtime.py:543-605`
+- **backend error**：停止，见 `src/agent_runtime.py:703-725`
+- **达到 `max_turns`**：停止，见 `src/agent_runtime.py:1121-1146`
+
+### 2.8 loop 是固定流程还是模型驱动
+
+结论：
+
+- **loop 骨架是固定的 runtime state machine**
+- **每轮内的动作内容是模型驱动的**
+
+固定部分是：
+
+1. 整理上下文
+2. 预算检查
+3. 调模型
+4. 若 tool_calls 则执行工具
+5. 把工具结果写回 transcript
+6. 进入下一轮或停止
+
+动态部分是：
+
+- 调什么工具
+- 调多少个工具
+- 是继续观察、修改还是直接回答
 
 ---
 
-## 🪆 Nested Agent Delegation
+## 3. Context / Memory
 
-The agent can delegate subtasks to child agents with full context carryover:
+### 3.1 是否有短期上下文
 
-```bash
-python3 -m src.main agent \
-  "Delegate a subtask to inspect src/agent_runtime.py and return a summary." \
-  --cwd . --show-transcript
-```
+有。短期上下文就是当前 `AgentSessionState.messages`。
 
-Features:
-- Sequential and parallel subtask execution
-- Dependency-aware topological batching
-- Child-session save and resume
-- Agent manager lineage tracking
+其中包含：
 
-> See [TESTING_GUIDE.md](TESTING_GUIDE.md) **Section 20** for delegation testing commands.
+- system prompt
+- user context reminder
+- user / assistant / tool messages
+- mutation metadata
+
+见 `src/agent_session.py:89-148`。
+
+### 3.2 是否有长期记忆
+
+有，但不是向量数据库式长期记忆，而是 **文件化长期记忆**：
+
+- `~/.claude/CLAUDE.md`
+- 向上目录搜索的 `CLAUDE.md`
+- `.claude/CLAUDE.md`
+- `CLAUDE.local.md`
+- `.claude/rules/*.md`
+
+这些文件会在 session 创建时被 bundle 进 `user_context['claudeMd']`，见 `src/agent_context.py:205-207`、`313-372`。
+
+因此它支持“repo memory / instruction memory”，但不支持自动写回、检索式 memory store 或 embedding memory。
+
+### 3.3 是否有 conversation history
+
+有，而且比较完整：
+
+- 运行时 transcript：`AgentSessionState.messages`
+- 持久化 transcript：`StoredAgentSession.messages`
+- resume 后会恢复完整历史，见 `src/session_store.py:53-115`
+
+工具调用、usage、message metadata 也一起保存。
+
+### 3.4 是否有压缩 / summarize / compaction
+
+有，而且这是一个比较成熟的部分。
+
+机制分三层：
+
+- **microcompact**：时间驱动的小型压缩，清理旧 tool results，见 `src/agent_runtime.py:113-115 import`、`src/agent_runtime.py:527-533`
+- **snip**：把早期消息 tombstone 化为短摘要，见 `src/agent_runtime.py:533-537` 与 `_snip_session_pass`
+- **compact**：调用 `compact_conversation()` 生成更正式的压缩摘要，见 `src/agent_runtime.py:538-547`、`src/agent_runtime.py:1240` 前后逻辑
+
+此外还有：
+
+- prompt too long 时的 **reactive compaction retry**
+- resume 时的 **compaction replay**
+
+见 `src/agent_runtime.py:3042-3142`。
+
+### 3.5 是否有外部文件作为 memory
+
+有，且非常明显：
+
+- `CLAUDE.md` 系列
+- `.claude/rules/*.md`
+- 各类 workspace state 文件：config、plan、task、team、workflow、worktree 等 runtime manifest/state 文件
+
+不过严格说，后者更多是 “runtime state injection”，不是纯 memory。
+
+### 3.6 是否支持类似 CLAUDE.md / AGENTS.md / skills 的持久知识
+
+#### CLAUDE.md
+
+支持，且是当前唯一成熟的一类持久知识注入。
+
+#### AGENTS.md
+
+**不原生支持 `AGENTS.md` 作为 memory bundle**。当前 memory 发现逻辑只搜索 `CLAUDE.md`、`CLAUDE.local.md` 和 `.claude/rules/*.md`，见 `src/agent_context.py:355-372`。
+
+#### skills
+
+只支持“bundled skills”：
+
+- 在 Python 代码里硬编码 skill 元数据和 prompt builder
+- 通过 `Skill` 工具或 `/skills` 暴露
+
+不支持从工作区扫描 markdown skill 文档并按需加载。
+
+### 3.7 当前设计局限
+
+1. **长期记忆是纯文件注入，不是检索式 memory**
+   - 规模大时容易塞满 prompt
+   - 没有 relevance ranking
+
+2. **只识别 CLAUDE.md 家族，不识别 AGENTS.md**
+   - 对多代理协作约束不够统一
+
+3. **resume 依赖 transcript replay，不是真正的 semantic memory**
+   - 历史很多时仍然会发生 compaction 丢失细节
+
+4. **runtime summaries 很多，但上下文管理是“全量摘要注入”**
+   - 不是 query-time selective loading
+
+5. **task / plan / workflow 已有，但未形成强约束的 workspace memory layout**
+   - 更像多个离散 runtime，而不是统一的 task-memory 文件系统
 
 ---
 
-## 🖥️ Local Web GUI
+## 4. Tools / Actions
 
-If the terminal isn't your thing, launch the bundled browser GUI:
+### 4.1 工具能力概览
 
-```bash
-python3 -m src.gui --cwd . --allow-write --allow-shell
-```
+核心工具能力包括：
 
-Your default browser opens to `http://127.0.0.1:8765` with a modern dark-themed chat UI.
+- **文件系统**
+  - `list_dir`
+  - `read_file`
+  - `write_file`
+  - `edit_file`
+  - `notebook_edit`
+- **搜索与代码理解**
+  - `glob_search`
+  - `grep_search`
+  - `LSP`
+  - `tool_search`
+- **Shell**
+  - `bash`
+- **Web / Search**
+  - `web_fetch`
+  - `web_search`
+  - search provider 管理工具
+- **计划 / 任务**
+  - `update_plan`
+  - `plan_get`
+  - task runtime 相关工具
+- **Human gate**
+  - `ask_user_question`
+- **扩展 runtime**
+  - `mcp_*`
+  - `remote_*`
+  - `workflow_*`
+  - `worktree_*`
+  - `account_*`
+  - `config_*`
+- **Agent 特有**
+  - `Agent` / `delegate_agent`
+  - `Skill`
 
-| Flag | Description |
-|------|-------------|
-| `--host <addr>` | Bind address (default `127.0.0.1`) |
-| `--port <n>` | Port to listen on (default `8765`) |
-| `--cwd <path>` | Workspace directory the agent operates in |
-| `--model <name>` | Override the model name |
-| `--base-url <url>` | Override the OpenAI-compatible API base URL |
-| `--api-key <key>` | API key for the model server |
-| `--session-dir <path>` | Where saved sessions live |
-| `--allow-write` | Allow file write/edit tools |
-| `--allow-shell` | Allow shell execution |
-| `--no-browser` | Don't auto-open a browser tab |
+tool registry 定义入口在 `src/agent_tools.py:210`。
 
-The GUI surfaces:
+### 4.2 工具 schema 怎么定义
 
-- multi-turn chat with tool-call cards (collapsible JSON args + results)
-- saved sessions sidebar with one-click resume
-- slash command and skill pickers (`/` and `★` buttons, or `Cmd/Ctrl+K`)
-- live settings panel (model, base URL, working dir, permissions)
-- usage / cost meta in the composer footer
+每个工具是一个 `AgentTool`：
 
-> **Note:** The GUI uses [FastAPI](https://fastapi.tiangolo.com/) and [Uvicorn](https://www.uvicorn.org/) under the hood. These get installed automatically if you install the package via `pip install -e .`. The core Python agent runtime itself remains dependency-free.
+- `name`
+- `description`
+- `parameters`（JSON Schema）
+- `handler`
+
+见 `src/agent_tools.py:73-111`。
+
+它通过 `to_openai_tool()` 转成 OpenAI-compatible function calling schema，见 `src/agent_tools.py:80-88`。
+
+### 4.3 工具调用怎么执行
+
+模型返回 tool call 后，runtime 会：
+
+1. 解析 tool call，见 `src/openai_compat.py:273-298`
+2. 在 loop 中逐个消费，见 `src/agent_runtime.py:808-1119`
+3. 普通工具走 `execute_tool_streaming()` 或 `tool.execute()`，见 `src/agent_tools.py:181-207`
+4. 特殊工具：
+   - `Agent` / `delegate_agent` 走子代理执行，见 `src/agent_runtime.py:2214`
+   - `Skill` 走 `_execute_skill()`，见 `src/agent_runtime.py:2059`
+
+### 4.4 工具结果如何返回
+
+工具结果统一封装为 `ToolExecutionResult`：
+
+- `name`
+- `ok`
+- `content`
+- `metadata`
+
+然后 `serialize_tool_result()` 把它转成 JSON 字符串，塞入 tool message，见 `src/agent_tools.py:1248-1255`。
+
+这意味着：
+
+- 对模型来说，工具结果是 transcript 中的标准 `tool` message
+- 对 runtime 来说，工具结果又带 `metadata`，可用于 file_history、policy event、plugin hook
+
+### 4.5 是否有安全边界
+
+有，但不是特别细粒度。
+
+#### 文件边界
+
+`_resolve_path()` 会强制路径位于 workspace root 内，防止越界，见 `src/agent_tools.py:1277-1288`。
+
+#### 写权限边界
+
+`write_file` / `edit_file` 受 `allow_file_write` 控制，见 `src/agent_tools.py:1291-1295`。
+
+#### shell 权限边界
+
+`bash` 受两层控制：
+
+- `allow_shell_commands`
+- `allow_destructive_shell_commands`
+
+并有 destructive regex 阻断，比如 `rm`、`git reset --hard`、`git clean -fd` 等，见 `src/agent_tools.py:1298-1324`。
+
+#### policy / hook deny
+
+workspace 可以通过 `.claw-policy.json` / `.codex-policy.json` / `.claw-hooks.json` 配置 deny_tools、deny_tool_prefixes 以及 hook message，见 `src/hook_policy.py:160-256`。
+
+#### CLI 层 deny context
+
+还有一个更轻的 `ToolPermissionContext`，可按名字或前缀过滤工具，见 `src/permissions.py:7-17`。
+
+### 4.6 这一层的架构评价
+
+这个项目的 tools 层已经不是“几个本地 IO 工具”，而是：
+
+> 一个围绕 workspace 资源、外部 runtime 状态和 agent orchestration 展开的统一 action surface。
+
+优点是扩展性强，缺点是工具域越来越大后，模型对何时该用哪个工具会变得更依赖 prompt guidance。
 
 ---
 
-## 🔄 Session Persistence
+## 5. Markdown / Workspace
 
-Each `agent` run automatically saves a resumable session:
+### 5.1 是否支持 workspace-first
+
+是，明显是 workspace-first 设计。
+
+证据：
+
+- `ToolExecutionContext.root` 是工作区根，见 `src/agent_tools.py:45`
+- 所有文件工具都围绕 workspace root 做相对路径解析，见 `src/agent_tools.py:1277-1288`
+- context 注入围绕 cwd、git repo、worktree、scratchpad、additional_working_directories 展开，见 `src/agent_context.py:71-99`
+- 很多 runtime 都是 `from_workspace(cwd)` 初始化的
+
+### 5.2 是否适合让 Agent 维护 `.md` 文件作为任务记忆
+
+适合，而且比很多 agent 框架更适合。
+
+原因：
+
+- 已经原生支持 markdown 记忆文件注入（CLAUDE.md / rules）
+- 文件读写/编辑能力完整
+- 有 plan / task runtime，可作为结构化状态
+- 有 scratchpad directory，可作为会话级临时区
+
+不足是它没有约定一个统一的 task-memory 目录布局。
+
+### 5.3 是否有任务目录 / workspace 概念
+
+有 workspace 概念，但没有强约定的任务目录结构。
+
+已有元素：
+
+- workspace root
+- additional working directories
+- scratchpad root / scratchpad directory
+- `.claude/` 作为本地 agent/runtime 元数据目录
+
+但没有默认的：
+
+- `/tasks/{task_id}/...`
+- `/artifacts/...`
+- `/memory/...`
+
+### 5.4 能否改造成 task directory layout
+
+完全可以，而且改造成本不高。
+
+一个可行布局：
 
 ```text
-session_id=4f2c8c6f9c0e4d7c9c7b1b2a3d4e5f67
-session_path=.port_sessions/agent/4f2c8c6f...
+/tasks/{task_id}/goal.md
+/tasks/{task_id}/memory/open_questions.md
+/tasks/{task_id}/memory/working_notes.md
+/tasks/{task_id}/artifacts/report.md
+/tasks/{task_id}/artifacts/commands.md
+/tasks/{task_id}/artifacts/findings.md
 ```
 
-Resume a previous session:
+最小改造方式：
 
-```bash
-python3 -m src.main agent-resume \
-  4f2c8c6f9c0e4d7c9c7b1b2a3d4e5f67 \
-  "Continue the previous task and finish the missing parts."
-```
+1. 在 `task_runtime` 中给 task 增加 `task_root`
+2. 在 `agent_context._load_memory_bundle()` 中把 `/tasks/{active_task}/memory/*.md` 纳入 memory discovery
+3. 在 prompt context 中注入 `active task root`
+4. 给 `update_plan` / task 工具增加 task-root 绑定
 
-Resume directly into interactive chat:
-
-```bash
-python3 -m src.main agent-chat \
-  --resume-session-id <session-id> \
-  --cwd .
-```
-
-Inspect saved sessions:
-
-```bash
-ls -lt .port_sessions/agent
-```
-
-> **Note:** Run `agent-resume` from the same `claw-code/` directory where the session was created. A resumed session continues from the saved transcript, not from scratch.
+这样不需要重写 loop，只是增强 workspace memory layout。
 
 ---
 
-## 🧪 Testing
+## 6. Skills
 
-Run the full test suite:
+### 6.1 当前是否支持 skill
 
-```bash
-python3 -m unittest discover -s tests -v
+支持，但属于 **弱 skill 系统**。
+
+当前 skill 机制分两部分：
+
+1. **Bundled skills**
+   - `BundledSkill` 定义 name / description / when_to_use / aliases / allowed_tools / get_prompt
+   - 见 `src/bundled_skills.py:22-32`
+
+2. **Skill tool**
+   - `_execute_skill()` 优先查 bundled skill
+   - 查不到再退回 slash command
+   - 见 `src/agent_runtime.py:2059-2142`
+
+### 6.2 是否有技能发现机制
+
+有，但只对 bundled skill 生效：
+
+- `format_skills_for_system_prompt()` 把 skill 列表渲染进系统提示，帮助模型“知道”有哪些 skill，见 `src/bundled_skills.py:268-289`
+- GUI 也有 `/api/skills` 列表，见 `src/gui/server.py`
+
+但它没有：
+
+- 从工作区扫描 skill 文件
+- 从 skill 文档按需加载正文
+- skill-level semantic retrieval
+
+### 6.3 是否支持 progressive disclosure
+
+**严格说不支持。**
+
+当前 bundled skill 更像：
+
+- 用户 / 模型选中 skill
+- skill 生成一段 prompt
+- prompt 立即进入模型上下文
+
+并不是：
+
+- 先列 metadata
+- 决定是否需要 skill
+- 再按需读取 skill markdown 正文
+- 只展开相关片段
+
+因此它缺乏真正的 progressive disclosure。
+
+### 6.4 如果没有，应该如何扩展
+
+建议做一个最小可行版 workspace skill system，不破坏现有 loop。
+
+#### 最小改造方案
+
+##### 目录结构
+
+```text
+.claude/skills/
+  review/
+    skill.json
+    SKILL.md
+  data-agent/
+    skill.json
+    SKILL.md
+  python-debug/
+    skill.json
+    SKILL.md
 ```
 
-Smoke tests:
+##### metadata
 
-```bash
-python3 -m src.main agent "/help"
-python3 -m src.main agent-context --cwd .
-python3 -m src.main agent \
-  "Read src/agent_session.py and summarize the message flow." \
-  --cwd .
+`skill.json` 示例：
+
+```json
+{
+  "name": "data-agent",
+  "description": "Analyze datasets and produce structured markdown reports.",
+  "when_to_use": "When the task involves CSV/JSON/table exploration, metric comparison, or report writing.",
+  "aliases": ["data", "analysis"],
+  "allowed_tools": ["read_file", "write_file", "edit_file", "glob_search", "grep_search", "bash"],
+  "entry_markdown": "SKILL.md"
+}
 ```
 
-> 📚 **Full testing guide:** See [TESTING_GUIDE.md](TESTING_GUIDE.md) for step-by-step commands covering the full implemented runtime surface.
+##### loading 时机
+
+建议两阶段：
+
+1. **session 初始化时只加载 metadata**
+   - 像 bundled skill 一样列进 system prompt
+   - 不把 `SKILL.md` 正文直接注入
+
+2. **当模型选择 Skill 工具时再加载正文**
+   - `Skill(skill="data-agent")`
+   - runtime 读取对应 `SKILL.md`
+   - 返回 skill prompt 或 `<system-reminder>` 包装内容
+
+##### Agent 如何决定读取哪个 skill
+
+沿用现有机制，最小改造即可：
+
+- 在 system prompt 里暴露 `name + description + when_to_use`
+- 模型自己决定是否调用 `Skill`
+- `Skill` 工具负责延迟读取 skill 正文
+
+##### 代码落点
+
+最小改造建议：
+
+- 扩展 `src/bundled_skills.py` 为“bundled + discovered skills”
+- 或新建 `workspace_skills.py`
+- 在 `_execute_skill()` 中优先：
+  1. bundled skill
+  2. workspace discovered skill
+  3. slash command fallback
+
+这个改法不会触碰 loop 主干，只是在 skill lookup 阶段增加一个来源。
 
 ---
 
-## 🔐 Permission Model
+## 7. Policy / Human Gate
 
-Claw Code Agent uses a **tiered permission system** to keep the agent safe by default:
+### 7.1 如何处理权限
 
-| Tier | Capability | Flag Required |
-|------|-----------|---------------|
-| **Read-only** | List, read, glob, grep | None (default) |
-| **Write** | + file creation and editing | `--allow-write` |
-| **Shell** | + shell command execution | `--allow-shell` |
-| **Unsafe** | + destructive shell operations | `--unsafe` |
+当前权限机制主要有三层。
+
+#### 第一层：启动时权限布尔开关
+
+`AgentPermissions`：
+
+- `allow_file_write`
+- `allow_shell_commands`
+- `allow_destructive_shell_commands`
+
+见 `src/agent_types.py:147-150`。
+
+这是最直接的 runtime gate。
+
+#### 第二层：workspace hook / policy
+
+`HookPolicyRuntime` 支持：
+
+- `trusted`
+- `managed_settings`
+- `safe_env_names`
+- `deny_tools`
+- `deny_tool_prefixes`
+- `before_prompt`
+- `after_turn`
+- `before_tool`
+- `after_tool`
+- `budget_overrides`
+
+见 `src/hook_policy.py:10-22`。
+
+#### 第三层：ask_user runtime
+
+并不是所有危险动作都会自动弹确认框。当前“人工确认”更像一个工具能力：
+
+- `ask_user_question`
+
+也就是说，模型可以选择向用户提问，但 runtime 本身不会像桌面 Codex 那样对每个危险动作自动出现审批 UI。
+
+### 7.2 哪些动作会请求用户确认
+
+严格来说，**默认没有统一的自动确认拦截器**。
+
+当前模式更像：
+
+- 文件写：如果没开 `allow_write`，直接拒绝
+- shell：如果没开 `allow_shell`，直接拒绝
+- destructive shell：如果没开 `--unsafe`，直接拒绝
+- policy deny：直接拒绝
+- ask-user：模型显式调用 `ask_user_question` 才会走人工澄清
+
+因此它偏向：
+
+> hard gate / deny-first，而不是 ask-on-demand 审批流。
+
+### 7.3 哪些动作默认允许
+
+默认允许的是安全读类能力，例如：
+
+- read
+- list
+- search
+- tool discovery
+- runtime status inspection
+
+默认不允许的是：
+
+- 写文件
+- shell
+- destructive shell
+
+具体提示也被写进 system prompt，见 `src/agent_prompting.py:388-401`。
+
+### 7.4 是否有 deny / allow / ask 策略
+
+有 `allow` 与 `deny`，但 `ask` 不是系统级统一策略。
+
+- **allow**：CLI flag / runtime permissions
+- **deny**：hook policy deny_tools / deny_tool_prefixes
+- **ask**：只通过 `ask_user_question` 工具实现，非自动策略
+
+### 7.5 是否支持项目级规则
+
+支持。
+
+项目级规则来自：
+
+- `.claw-policy.json`
+- `.codex-policy.json`
+- `.claw-hooks.json`
+
+并且会沿 cwd 向上目录发现，见 `src/hook_policy.py:160-187`。
+
+### 7.6 对数据 Agent 的不足
+
+如果你们要做数据 Agent，这套 human gate 还有几个明显缺口：
+
+1. **缺少按数据源级别的权限模型**
+   - 没有“允许读 CSV 但不允许发网络请求”这种更细粒度策略
+
+2. **没有结构化审批流**
+   - 例如“将执行 SQL / 访问线上表 / 导出结果集”的 ask approval 缺位
+
+3. **没有数据脱敏/泄露策略**
+   - safe_env 只管环境变量，不管输出内容
+
+4. **没有审计级 action classification**
+   - tool 结果有 metadata，但没有“高风险数据出站/高风险变更”的统一标签体系
+
+5. **policy 更偏 workspace engineering，而不是 data governance**
+
+如果面向数据 Agent，建议增加：
+
+- data source allowlist
+- query approval policy
+- outbound redaction hook
+- result size limits
+- table/column sensitivity policy
 
 ---
 
-## 🔎 Parity Status
+## 8. Trace / Observability
 
-The full implementation checklist tracking parity against the npm `src` lives in [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md).
+### 8.1 是否记录每一轮模型输入输出
 
-It covers: core runtime, CLI modes, prompt assembly, context/memory, slash commands, tools, permissions, plugins, MCP, REPL/TUI, remote features, editor integrations, and internal subsystems.
+有记录，但“模型输入原文”不单独存为一条日志，而是可由 session transcript 和 system/user context 还原。
+
+保存内容包括：
+
+- `messages` transcript
+- `system_prompt_parts`
+- `user_context`
+- `system_context`
+- `usage`
+- `turns`
+- `tool_calls`
+
+见 `src/session_store.py:53-115`、`src/agent_runtime.py:3269-3345`。
+
+模型输出则直接进入 `assistant` messages。
+
+### 8.2 是否记录工具调用
+
+有，而且记录得比较细：
+
+- transcript 中的 assistant tool_calls
+- transcript 中的 tool result message
+- `events` 中的 `tool_start` / `tool_delta` / `tool_result`
+- `file_history` 中的摘要化变更记录
+
+见 `src/agent_runtime.py:852-1119`。
+
+### 8.3 是否记录文件变更
+
+有，`file_history` 是一个重要机制。
+
+resume 时会把 file_history replay 成一个 `<system-reminder>` 给模型，见：
+
+- `src/agent_runtime.py:2914-3040`
+
+持久化时也会一起保存到 session json，见：
+
+- `src/session_store.py:66`
+- `src/agent_runtime.py:3333`
+
+它不是完整 patch log，但已经记录：
+
+- action
+- path / changed_paths
+- snapshot ids
+- before/after preview
+- result preview
+
+### 8.4 是否有 replay/debug 能力
+
+有基础能力：
+
+- `agent-resume`
+- transcript 持久化
+- file_history replay
+- compaction replay
+- GUI 可以展示 transcript 和 tool calls
+
+但没有一个真正成熟的“调试控制台”或统一 trace viewer。
+
+### 8.5 现有 observability 的优点
+
+优点：
+
+- 数据结构已经齐全：transcript、events、file_history、budget_state、plugin_state
+- session 是 JSON 文件，易于离线分析
+- message metadata 里保留了 mutation lineage / revision 信息
+
+这意味着系统已经具备做更强 observability 的底座。
+
+### 8.6 还缺什么
+
+目前还缺：
+
+1. **完整 prompt snapshot**
+   - 现在有 system/user context 和 transcript，但缺“每轮实际发给模型的最终 payload”落盘
+
+2. **turn-level structured trace**
+   - 比如 `turn_03.json`
+   - 包含 prompt size、tool candidates、selected tool calls、latency、errors
+
+3. **统一 replay viewer**
+   - 现在 resume 偏“继续工作”
+   - 不是“回放调试”
+
+4. **tool latency / error taxonomy**
+   - 有 event，但缺统计聚合
+
+5. **compaction provenance**
+   - 已有 replay，但缺图形化 lineage/summary mapping
+
+### 8.7 如果要补，怎么加
+
+最小建议：
+
+#### 建议新增 trace 目录
+
+```text
+.port_sessions/traces/{session_id}/
+  turn_001.request.json
+  turn_001.response.json
+  turn_001.events.json
+  turn_001.tools.json
+```
+
+#### 每轮保存这些内容
+
+- request
+  - rendered messages
+  - tool specs
+  - token budget snapshot
+- response
+  - raw model response
+  - parsed tool calls
+  - finish_reason
+- tools
+  - tool args
+  - tool result
+  - latency
+- events
+  - 当前 turn 的 event list
+
+#### 代码落点
+
+最合适挂点在：
+
+- `_query_model()` 前后
+- tool loop `for tool_call in turn.tool_calls`
+- `_persist_session()`
+
+这样能复用现有 `session_id` 和 `turn_index`。
 
 ---
 
-## ⚠️ Disclaimer
+## 总结判断
 
-- This repository is a **Python reimplementation** inspired by the Claude Code npm architecture.
-- It does **not** ship the original npm source.
-- It is **not** affiliated with or endorsed by Anthropic.
+这个项目已经具备一个完整 coding agent runtime 的主要骨架：
 
----
+- 有明确的 session 与 transcript 模型
+- 有模型驱动的动态工具循环
+- 有 context injection 与 memory bundle
+- 有 compaction / replay / resume
+- 有较丰富的本地工具和 runtime 子系统
 
-<p align="center">
-  <sub>Built with 🐍 Python · Powered by 🐉 HarnessLab Team.</sub>
-</p>
+但从“下一代 workspace-native agent platform”的角度看，它还有几个明显缺口：
+
+- skills 仍是 prompt-template 级，未形成 markdown-native progressive disclosure
+- policy 偏 deny/allow，不是强审批流
+- memory 已经文件化，但没有统一 task directory layout
+- observability 有底座，缺一层真正可用的 trace 产品化视图
+
+如果目标是把它改造成更强的“任务型数据 Agent / 文档驱动 Agent / workspace-memory-first Agent”，最值得优先补的不是 loop，而是三件事：
+
+1. **workspace skill discovery + on-demand markdown loading**
+2. **任务目录结构与 memory layout 约定**
+3. **turn-level trace 持久化与 replay viewer**
+
+这三项都可以在不重写 `LocalCodingAgent` 主循环的前提下增量演进。
diff --git a/claw-code-agent.md b/claw-code-agent.md
new file mode 100644
index 0000000..97d0c4f
--- /dev/null
+++ b/claw-code-agent.md
@@ -0,0 +1,845 @@
+<p align="center">
+  <img src="images/logo.png" alt="Claw Code Agent logo" width="420" />
+</p>
+
+<h1 align="center">Claw Code Agent</h1>
+
+<p align="center">
+  <em>A Python reimplementation of the Claude Code agent architecture — local models, full control, zero dependencies.</em>
+</p>
+
+<p align="center">
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python 3.10+"></a>
+  <a href="https://github.com/HarnessLab/claw-code-agent"><img src="https://img.shields.io/badge/repo-HarnessLab%2Fclaw--code--agent-181717?logo=github" alt="GitHub"></a>
+  <a href="https://docs.vllm.ai/"><img src="https://img.shields.io/badge/backend-vLLM-FF6F00?logo=lightning&logoColor=white" alt="vLLM"></a>
+  <a href="https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct"><img src="https://img.shields.io/badge/model-Qwen3--Coder-FFD21E?logo=huggingface&logoColor=black" alt="Qwen3-Coder"></a>
+  <img src="https://img.shields.io/badge/dependencies-zero-brightgreen" alt="Zero Dependencies">
+  <img src="https://img.shields.io/badge/status-alpha-orange" alt="Alpha">
+  <img src="https://img.shields.io/badge/license-open--source-green" alt="License">
+</p>
+
+---
+
+## 📢 What's New
+
+> **April 2026 — Major Update**
+
+| | Feature | Details |
+|---|---------|---------|
+| 🆕 | **Interactive Chat Mode** | New `agent-chat` command — multi-turn REPL with `/exit` to quit |
+| 🆕 | **Streaming Output** | Token-by-token streaming with `--stream` flag |
+| 🆕 | **Plugin Runtime** | Full manifest-based plugin system — hooks, tool aliases, virtual tools, tool blocking |
+| 🆕 | **Nested Agent Delegation** | Delegate subtasks to child agents with dependency-aware topological batching |
+| 🆕 | **Agent Manager** | Lineage tracking, group membership, batch summaries for nested agents |
+| 🆕 | **Custom Agent Profiles** | Discover local markdown-defined agents from `~/.claude/agents` and `./.claude/agents` and use them through the `Agent` tool |
+| 🆕 | **Cost Tracking & Budgets** | Token budgets, cost budgets, tool-call limits, model-call limits, session-turn limits |
+| 🆕 | **Structured Output** | JSON schema response mode with `--response-schema-file` |
+| 🆕 | **Context Compaction** | Auto-snip, auto-compact, and reactive compaction on prompt-too-long errors |
+| 🆕 | **File History Replay** | Journaling of file edits with snapshot IDs, replay summaries on session resume |
+| 🆕 | **Truncation Continuation** | Automatic continuation when model response is cut off (`finish_reason=length`) |
+| 🆕 | **Ollama Support** | Works out of the box with Ollama's OpenAI-compatible API |
+| 🆕 | **LiteLLM Proxy Support** | Route through LiteLLM Proxy to any provider |
+| 🆕 | **OpenRouter Support** | Cloud API gateway — access OpenAI, Anthropic, Google models via one endpoint |
+| 🆕 | **Query Engine** | Runtime event counters, transcript summaries, orchestration reports |
+| 🆕 | **Remote Runtime** | Manifest-backed local remote profiles, connect/disconnect state, and remote CLI/slash flows |
+| 🆕 | **Hook & Policy Runtime** | Local `.claw-policy.json` / hook manifests with trust reporting, safe env, tool blocking, and budget overrides |
+| 🆕 | **Task & Plan Runtime** | Persistent local tasks and plans with plan-to-task sync and dependency-aware task execution |
+| 🆕 | **MCP Transport** | Real stdio MCP transport for `initialize`, resource listing/reading, and tool listing/calling |
+| 🆕 | **Search Runtime** | Provider-backed `web_search` with local manifests, activation state, and `/search` flows |
+| 🆕 | **Config & Account Runtime** | Local config/settings mutation plus manifest-backed account profiles and login/logout state |
+| 🆕 | **Ask-User Runtime** | Queued or interactive local ask-user flow with history, slash commands, and agent tool support |
+| 🆕 | **Team Runtime** | Persisted local teams and message history with team/message tools and slash/CLI inspection |
+| 🆕 | **Notebook Edit Tool** | Native `.ipynb` cell editing through the real agent tool registry |
+| 🆕 | **Workflow Runtime** | Manifest-backed local workflows with workflow tools, slash commands, and run history |
+| 🆕 | **Remote Trigger Runtime** | Local remote triggers with create/update/run flows similar to the npm remote trigger surface |
+| 🆕 | **Worktree Runtime** | Managed git worktrees with mid-session cwd switching, slash commands, and CLI flows |
+| 🆕 | **Tokenizer-Aware Context** | Cached tokenizer backends with heuristic fallback for `/context`, `/status`, and compaction |
+| 🆕 | **Prompt Budget Preflight** | Preflight prompt-length validation, token-budget reporting, and auto-compact/context collapse before backend failures |
+| 🆕 | **LSP Runtime** | Local LSP-style code intelligence for definitions, references, hover, symbols, call hierarchy, and diagnostics |
+| 🆕 | **Local Web GUI** | Browser-based chat UI via `python -m src.gui` — modern dark theme, slash command palette, session browser, settings panel |
+| 🆕 | **Daemon Commands** | Local `daemon start/ps/logs/attach/kill` wrapper over background agent sessions |
+| 🆕 | **Background Sessions** | Local `agent-bg`, `agent-ps`, `agent-logs`, `agent-attach`, and `agent-kill` flows |
+| 🆕 | **Testing Guide** | Comprehensive [TESTING_GUIDE.md](TESTING_GUIDE.md) with commands for every feature |
+| 🆕 | **Parity Checklist** | Full [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md) tracking implementation status vs npm source |
+
+---
+
+## 📖 About
+
+This repository reimplements the [Claude Code](https://docs.anthropic.com/en/docs/claude-code) npm agent architecture **entirely in Python**, designed to run with **local open-source models** via an OpenAI-compatible API server.
+
+Built on the public porting workspace from [instructkr/claw-code](https://github.com/instructkr/claw-code), the active development lives at [HarnessLab/claw-code-agent](https://github.com/HarnessLab/claw-code-agent).
+
+> **Goal:** Not to ship the original npm source, but to reimplement the full agent flow in Python — prompt assembly, context building, slash commands, tool calling, session persistence, and local model execution.
+>
+> **Zero external dependencies** — just Python's standard library.
+
+<p align="center">
+  <img src="images/demo_2.gif" alt="Claw Code Agent demo" width="900" />
+</p>
+
+---
+
+## ✨ Key Features
+
+| Feature | Description |
+|---------|-------------|
+| 🤖 **Agent Loop** | Full agentic coding loop with tool calling and iterative reasoning |
+| 💬 **Interactive Chat** | Multi-turn REPL via `agent-chat` with session continuity |
+| 🖥️ **Local Web GUI** | Browser-based chat UI launched with `python -m src.gui` — sessions browser, slash command palette, live settings |
+| 🧰 **Core Tools** | File read / write / edit, glob search, grep search, shell execution |
+| 🔌 **Plugin Runtime** | Manifest-based plugins with hooks, aliases, virtual tools, and tool blocking |
+| 🪆 **Nested Delegation** | Delegate subtasks to child agents with dependency-aware topological batching |
+| 🧩 **Custom Agents** | Load local agent profiles from `~/.claude/agents` and `./.claude/agents`, inspect them via `/agents`, and delegate with `subagent_type` |
+| 📡 **Streaming** | Token-by-token streaming output with `--stream` |
+| 💬 **Slash Commands** | Local commands for context, config, account, search, MCP, remote, tasks, plan, hooks, and model control |
+| 🌐 **Remote Runtime** | Manifest-backed remote profiles with local `remote-mode`, `ssh-mode`, `teleport-mode`, and connect/disconnect state |
+| 🧭 **Task & Plan Runtime** | Persistent tasks and plans with sync, next-task selection, and blocked/unblocked state |
+| 🛰️ **MCP Runtime** | Local MCP manifests plus real stdio MCP transport for resources and tools |
+| 🔎 **Search Runtime** | Provider-backed `web_search` plus provider activation and status reporting |
+| ⚙️ **Config & Account Runtime** | Local config mutation, settings inspection, account profiles, and login/logout state |
+| 🙋 **Ask-User Runtime** | Queued answer or interactive user-question flow with history tracking |
+| 👥 **Team Runtime** | Persisted local teams plus message history, handoff notes, and collaboration metadata |
+| 📓 **Notebook Editing** | Native Jupyter notebook cell editing through `notebook_edit` |
+| 🪵 **Worktree Runtime** | Managed git worktrees with `worktree_enter`, `worktree_exit`, and live cwd switching |
+| 🧭 **Workflow Runtime** | Manifest-backed workflows with slash commands, CLI inspection, and recorded runs |
+| ⏰ **Remote Triggers** | Local remote triggers with create/update/run flows and npm-style trigger actions |
+| 🪝 **Hook & Policy Runtime** | Trust reporting, safe env, managed settings, tool blocking, and budget overrides |
+| 🧠 **LSP Code Intelligence** | Local LSP-style definitions, references, hover, symbols, diagnostics, and call hierarchy |
+| 🧠 **Context Engine** | Automatic context building with CLAUDE.md discovery, compaction, and snipping |
+| 🔢 **Tokenizer-Aware Accounting** | Model-aware token counting with cached tokenizer backends and fallback heuristics |
+| 📏 **Prompt Budgeting** | Soft/hard prompt-window checks, token-budget reports, and preflight context collapse |
+| 🔄 **Session Persistence** | Save and resume agent sessions with file-history replay |
+| 🗂️ **Background Sessions** | `agent-bg` and local daemon wrappers for background runs, logs, attach, and kill |
+| 💰 **Cost & Budget Control** | Token budgets, cost limits, tool-call caps, model-call caps |
+| 📋 **Structured Output** | JSON schema response mode for programmatic use |
+| 🔐 **Permission System** | Granular control: `--allow-write`, `--allow-shell`, `--unsafe` |
+| 🏗️ **OpenAI-Compatible** | Works with vLLM, Ollama, LiteLLM Proxy, OpenRouter — any OpenAI-compatible API |
+| 🐉 **Qwen3-Coder** | First-class support for `Qwen3-Coder-30B-A3B-Instruct` via vLLM |
+| 📦 **Zero Dependencies** | Pure Python standard library — nothing to install |
+
+---
+
+## 📋 Roadmap
+
+### 📚 Documentation
+
+| Document | Description |
+|----------|-------------|
+| [TESTING_GUIDE.md](TESTING_GUIDE.md) | Step-by-step commands to verify every feature |
+| [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md) | Full implementation status vs the npm source |
+
+### ✅ Done
+
+- [x] Python CLI agent loop
+- [x] Interactive chat mode (`agent-chat`) with multi-turn REPL
+- [x] OpenAI-compatible local model backend
+- [x] Qwen3-Coder support through vLLM with `qwen3_xml` tool parser
+- [x] Ollama, LiteLLM Proxy, and OpenRouter backends
+- [x] Core tools: `list_dir`, `read_file`, `write_file`, `edit_file`, `glob_search`, `grep_search`, `bash`
+- [x] Context building and `/context`-style usage reporting
+- [x] Slash commands: `/help`, `/context`, `/context-raw`, `/token-budget`, `/prompt`, `/permissions`, `/model`, `/tools`, `/agents`, `/memory`, `/status`, `/clear`
+- [x] Session persistence and `agent-resume` flow
+- [x] Permission system (read-only, write, shell, unsafe tiers)
+- [x] Streaming token-by-token assistant output
+- [x] Truncated-response continuation flow
+- [x] Auto-snip and auto-compact context reduction
+- [x] Reactive compaction retry on prompt-too-long errors
+- [x] Preflight prompt-length validation and token-budget reporting
+- [x] Preflight auto-compact/context collapse before backend prompt-too-long failures
+- [x] Cost tracking and usage budget enforcement
+- [x] Token, tool-call, model-call, and session-turn budgets
+- [x] Structured output / JSON schema response mode
+- [x] File history journaling with snapshot IDs and replay summaries
+- [x] Nested agent delegation with dependency-aware topological batching
+- [x] Agent manager with lineage tracking and group membership
+- [x] Filesystem-backed custom agent profiles with built-in/user/project precedence
+- [x] Local custom-agent create/update/delete flows via CLI and `/agents`
+- [x] Local daemon-style background command family
+- [x] Local background session workflows: `agent-bg`, `agent-ps`, `agent-logs`, `agent-attach`, `agent-kill`
+- [x] Local remote runtime: manifest discovery, profile listing, connect/disconnect persistence, and CLI/slash flows
+- [x] Local hook and policy runtime with trust reporting, safe env, tool blocking, and budget overrides
+- [x] Local config runtime: config discovery, effective settings, source inspection, and config mutation
+- [x] Local LSP runtime: definitions, references, hover, symbols, diagnostics, and call hierarchy
+- [x] Local account runtime: profile discovery, login/logout state, and account CLI/slash flows
+- [x] Local ask-user runtime: queued answers, history, and ask-user CLI/slash flows
+- [x] Local team runtime: persisted teams, team messages, and team CLI/slash flows
+- [x] Local search runtime with provider discovery, activation, and provider-backed `web_search`
+- [x] Local MCP runtime: manifest resources, stdio transport, MCP resources, and MCP tool calls
+- [x] Local task and plan runtimes with plan sync and dependency-aware task execution
+- [x] Notebook edit tool in the real Python tool registry
+- [x] Local workflow runtime with workflow list/get/run tools and CLI/slash flows
+- [x] Local remote trigger runtime with create/update/run flows and CLI/slash inspection
+- [x] Local managed git worktree runtime with live cwd switching and worktree CLI/slash flows
+- [x] Local web GUI (FastAPI + vanilla JS SPA) with chat, sessions browser, slash command palette, and live settings (`python -m src.gui`)
+- [x] Tokenizer-aware context accounting with cached tokenizer backends and heuristic fallback
+- [x] Plugin runtime: manifest discovery, hooks, aliases, virtual tools, tool blocking
+- [x] Plugin lifecycle hooks: resume, persist, delegate phases
+- [x] Plugin session-state persistence and resume restoration
+- [x] Query engine facade driving the real Python runtime
+- [x] Compaction metadata with lineage IDs and revision summaries
+- [x] Extended runtime tools: `web_fetch`, `web_search`, `tool_search`, `sleep`
+- [x] Unit tests for the Python runtime
+- [x] `pyproject.toml` packaging with `setuptools`
+
+### 🔲 In Progress
+
+- [ ] Full MCP parity beyond the current stdio transport and local manifest/resource/tool support
+- [ ] Full slash-command parity with npm runtime
+- [ ] Full interactive REPL / TUI behavior
+- [ ] Full tokenizer/chat-message framing parity beyond the current tokenizer-aware accounting
+- [ ] Hooks system parity
+- [ ] Real remote transport/runtime parity beyond the current local remote-profile runtime
+- [ ] Voice and VIM modes
+- [ ] Editor and platform integrations
+- [ ] Background and team features
+
+---
+
+## 🏗️ Architecture
+
+```text
+claw-code/
+├── README.md
+├── TESTING_GUIDE.md              # How to test every feature
+├── PARITY_CHECKLIST.md           # Implementation status vs npm source
+├── pyproject.toml
+├── .gitignore
+├── images/
+│   └── logo.png
+├── src/                          # Python implementation
+│   ├── main.py                   # CLI entry point & argument parsing
+│   ├── agent_runtime.py          # Core agent loop (LocalCodingAgent)
+│   ├── agent_tools.py            # Tool definitions & execution engine
+│   ├── agent_prompting.py        # System prompt assembly
+│   ├── agent_registry.py         # Built-in + filesystem-backed custom agent discovery
+│   ├── agent_context.py          # Context building & CLAUDE.md discovery
+│   ├── agent_context_usage.py    # Context usage estimation & reporting
+│   ├── agent_session.py          # Session state management
+│   ├── agent_slash_commands.py   # Local slash command processing
+│   ├── agent_manager.py          # Nested agent lineage & group tracking
+│   ├── agent_types.py            # Shared dataclasses & type definitions
+│   ├── openai_compat.py          # OpenAI-compatible API client (streaming)
+│   ├── plugin_runtime.py         # Plugin manifest, hooks, aliases, virtual tools
+│   ├── agent_plugin_cache.py     # Plugin discovery & prompt injection cache
+│   ├── session_store.py          # Session serialization & persistence
+│   ├── transcript.py             # Transcript block export & mutation tracking
+│   ├── query_engine.py           # Query engine facade & runtime orchestration
+│   ├── mcp_runtime.py            # Local MCP discovery and stdio MCP transport
+│   ├── search_runtime.py         # Search providers and provider-backed web_search
+│   ├── remote_runtime.py         # Local remote profiles, connect/disconnect state, remote CLI support
+│   ├── background_runtime.py     # Local background sessions and daemon support
+│   ├── account_runtime.py        # Local account profiles, login/logout state, account CLI support
+│   ├── ask_user_runtime.py       # Local ask-user queued answers and interaction history
+│   ├── config_runtime.py         # Local workspace config/settings discovery and mutation
+│   ├── lsp_runtime.py            # Local LSP-style code intelligence and diagnostics
+│   ├── token_budget.py           # Prompt-window budgeting and preflight prompt-length validation
+│   ├── plan_runtime.py           # Persistent plan runtime and plan sync
+│   ├── task_runtime.py           # Persistent task runtime and task execution
+│   ├── task.py                   # Task state model and task dataclasses
+│   ├── team_runtime.py           # Local teams, messages, and collaboration metadata
+│   ├── workflow_runtime.py       # Local workflow manifests and recorded workflow runs
+│   ├── remote_trigger_runtime.py # Local remote trigger manifests and trigger run history
+│   ├── worktree_runtime.py       # Managed git worktree sessions and cwd switching
+│   ├── hook_policy.py            # Hook/policy manifests, trust, and safe env handling
+│   ├── tokenizer_runtime.py      # Tokenizer-aware context accounting backends
+│   ├── permissions.py            # Tool permission filtering
+│   ├── cost_tracker.py           # Cost & budget enforcement
+│   ├── commands.py               # Mirrored command inventory
+│   ├── tools.py                  # Mirrored tool inventory
+│   ├── runtime.py                # Mirrored runtime facade
+│   ├── reference_data/           # Mirrored inventory snapshots
+│   └── gui/                      # Local web GUI (FastAPI + vanilla JS SPA)
+│       ├── __main__.py           # `python -m src.gui` entry point
+│       ├── server.py             # FastAPI app and JSON endpoints
+│       └── static/               # index.html, app.css, app.js
+└── tests/                        # Unit tests
+    ├── test_agent_runtime.py
+    ├── test_agent_context.py
+    ├── test_agent_context_usage.py
+    ├── test_agent_prompting.py
+    ├── test_agent_slash_commands.py
+    ├── test_main.py
+    ├── test_query_engine_runtime.py
+    └── test_porting_workspace.py
+```
+
+---
+
+## 📦 Requirements
+
+| Requirement | Details |
+|-------------|---------|
+| 🐍 Python | `3.10` or higher |
+| 📚 Dependencies | **None** — pure Python standard library |
+| 🖥️ Model Server | `vLLM`, `Ollama`, `LiteLLM Proxy`, or `OpenRouter`, with tool calling support |
+| 🧠 Model | [`Qwen/Qwen3-Coder-30B-A3B-Instruct`](https://huggingface.co/Qwen/Qwen3-Coder-30B-A3B-Instruct) (recommended) |
+
+---
+
+## 🚀 Quick Start
+
+### 1. Start vLLM with Qwen3-Coder
+
+vLLM must be started with automatic tool choice enabled. Use the `qwen3_xml` parser for Qwen3-Coder tool calling:
+
+```bash
+python -m vllm.entrypoints.openai.api_server \
+  --model Qwen/Qwen3-Coder-30B-A3B-Instruct \
+  --host 127.0.0.1 \
+  --port 8000 \
+  --enable-auto-tool-choice \
+  --tool-call-parser qwen3_xml
+```
+
+Verify the server is running:
+
+```bash
+curl http://127.0.0.1:8000/v1/models
+```
+
+> 📚 **References:** [vLLM Tool Calling Docs](https://docs.vllm.ai/en/v0.13.0/features/tool_calling/) · [OpenAI-Compatible Server](https://docs.vllm.ai/en/v0.13.0/serving/openai_compatible_server.html)
+
+### Optional: Use Ollama Instead of vLLM
+
+`claw-code-agent` can also work with Ollama because the runtime targets an OpenAI-compatible API. Use a model that supports tool calling well.
+
+Example:
+
+```bash
+ollama serve
+ollama pull qwen3
+```
+
+Then configure:
+
+```bash
+export OPENAI_BASE_URL=http://127.0.0.1:11434/v1
+export OPENAI_API_KEY=ollama
+export OPENAI_MODEL=qwen3
+```
+
+Notes:
+
+- prefer tool-capable models such as `qwen3`
+- plain chat-only models are not enough for full agent behavior
+- Ollama does not use the `vLLM` parser flags shown above
+
+> 📚 **References:** [Ollama OpenAI Compatibility](https://docs.ollama.com/api/openai-compatibility) · [Ollama Tool Calling](https://docs.ollama.com/capabilities/tool-calling)
+
+### Optional: Use LiteLLM Proxy
+
+`claw-code-agent` can also work through LiteLLM Proxy because the runtime targets an OpenAI-compatible chat completions API. The routed model still needs to support tool calling for full agent behavior.
+
+Quick start example:
+
+```bash
+pip install 'litellm[proxy]'
+litellm --model ollama/qwen3
+```
+
+LiteLLM Proxy runs on port `4000` by default. Then configure:
+
+```bash
+export OPENAI_BASE_URL=http://127.0.0.1:4000
+export OPENAI_API_KEY=anything
+export OPENAI_MODEL=ollama/qwen3
+```
+
+Notes:
+
+- LiteLLM Proxy gives you an OpenAI-style gateway in front of many providers
+- tool use still depends on the underlying routed model and provider behavior
+- if you configure a LiteLLM master key, use that instead of `anything`
+
+> 📚 **References:** [LiteLLM Docs](https://docs.litellm.ai/) · [LiteLLM Proxy Quick Start](https://docs.litellm.ai/)
+
+### Optional: Use OpenRouter
+
+`claw-code-agent` can also work with [OpenRouter](https://openrouter.ai/), a cloud API gateway that provides access to models from OpenAI, Anthropic, Google, Meta, and others through a single OpenAI-compatible endpoint. No local model server required.
+
+Configure:
+
+```bash
+export OPENAI_BASE_URL=https://openrouter.ai/api/v1
+export OPENAI_API_KEY=sk-or-v1-your-key-here
+export OPENAI_MODEL=openai/gpt-4o-mini
+```
+
+Notes:
+
+- sign up at [openrouter.ai](https://openrouter.ai/) and create an API key under [Keys](https://openrouter.ai/keys)
+- model names use the `provider/model` format (e.g. `anthropic/claude-sonnet-4`, `openai/gpt-4o`, `google/gemini-2.5-pro`)
+- tool calling support varies by model — check the [model list](https://openrouter.ai/models) for capabilities
+- this sends your conversation (including file contents and shell output) to OpenRouter and the upstream provider — do not use with repos containing secrets or sensitive data
+
+> 📚 **References:** [OpenRouter Docs](https://openrouter.ai/docs) · [Supported Models](https://openrouter.ai/models) · [API Keys](https://openrouter.ai/keys)
+
+### 2. Configure Environment
+
+```bash
+export OPENAI_BASE_URL=http://127.0.0.1:8000/v1
+export OPENAI_API_KEY=local-token
+export OPENAI_MODEL=Qwen/Qwen3-Coder-30B-A3B-Instruct
+```
+
+### Use Another Model With vLLM
+
+If you want to try another model, keep the same `vLLM` server setup and change the `--model` value when you launch `vLLM`.
+
+Example:
+
+```bash
+python -m vllm.entrypoints.openai.api_server \
+  --model your-model-name \
+  --host 127.0.0.1 \
+  --port 8000 \
+  --enable-auto-tool-choice \
+  --tool-call-parser your_parser
+```
+
+Then update:
+
+```bash
+export OPENAI_MODEL=your-model-name
+```
+
+Notes:
+
+- the documented path in this repository is `vLLM`
+- the model must support tool calling well enough for agent use
+- some model families require a different `--tool-call-parser`
+- slash commands such as `/help`, `/context`, and `/tools` are local and do not require the model server
+
+### 3. Run the Agent
+
+```bash
+# Read-only question
+python3 -m src.main agent \
+  "Read src/agent_runtime.py and summarize how the loop works." \
+  --cwd .
+
+# Write-enabled task
+python3 -m src.main agent \
+  "Create TEST_QWEN_AGENT.md with one line: test ok" \
+  --cwd . --allow-write
+
+# Shell-enabled task
+python3 -m src.main agent \
+  "Run pwd and ls src, then summarize the result." \
+  --cwd . --allow-shell
+
+# Interactive chat mode
+python3 -m src.main agent-chat --cwd .
+
+# Streaming output
+python3 -m src.main agent \
+  "Explain the current architecture." \
+  --cwd . --stream
+```
+
+---
+
+## 🛠️ Usage
+
+### Agent Commands
+
+| Command | Description |
+|---------|-------------|
+| `agent <prompt>` | Run the agent with a prompt |
+| `agent-chat [prompt]` | Start interactive multi-turn chat mode |
+| `agent-bg <prompt>` | Run the agent in a local background session |
+| `agent-ps` | List local background sessions |
+| `agent-logs <id>` | Show background session logs |
+| `agent-attach <id>` | Show the current background output snapshot |
+| `agent-kill <id>` | Stop a background session |
+| `daemon <subcommand>` | Daemon-style wrapper over local background sessions |
+| `agent-prompt` | Show the assembled system prompt |
+| `agent-context` | Show estimated context usage |
+| `agent-context-raw` | Show the raw context snapshot |
+| `token-budget` | Show prompt-window budget, reserves, and soft/hard input limits |
+| `agents [agent_type]` | List active local agent definitions or show one agent profile |
+| `agents-create <agent_type>` | Create a project or user agent definition markdown file |
+| `agents-update <agent_type>` | Update an existing project or user agent definition |
+| `agents-delete <agent_type>` | Delete an existing project or user agent definition |
+| `agent-resume <id> <prompt>` | Resume a saved session |
+
+### Runtime Utility Commands
+
+| Command | Description |
+|---------|-------------|
+| `search-status` / `search-providers` / `search-activate` / `search` | Inspect and use the local search runtime |
+| `mcp-status` / `mcp-resources` / `mcp-resource` / `mcp-tools` / `mcp-call-tool` | Inspect and use the local MCP runtime |
+| `remote-status` / `remote-profiles` / `remote-disconnect` | Inspect local remote runtime state |
+| `remote-mode` / `ssh-mode` / `teleport-mode` / `direct-connect-mode` / `deep-link-mode` | Activate local remote runtime modes |
+| `config-status` / `config-effective` / `config-source` / `config-get` / `config-set` | Inspect and mutate local config/settings |
+| `account-status` / `account-profiles` / `account-login` / `account-logout` | Inspect and mutate local account state |
+
+### CLI Flags
+
+| Flag | Description |
+|------|-------------|
+| `--cwd <path>` | Set the workspace directory |
+| `--model <name>` | Override the model name |
+| `--base-url <url>` | Override the API base URL |
+| `--allow-write` | Allow the agent to modify files |
+| `--allow-shell` | Allow the agent to execute shell commands |
+| `--unsafe` | Allow destructive shell operations |
+| `--stream` | Enable token-by-token streaming output |
+| `--show-transcript` | Print the full message transcript |
+| `--scratchpad-root <path>` | Override the scratchpad directory |
+| `--system-prompt <text>` | Set a custom system prompt |
+| `--append-system-prompt <text>` | Append to the system prompt |
+| `--override-system-prompt <text>` | Replace the generated system prompt |
+| `--add-dir <path>` | Add extra directories to context |
+
+### Budget & Limit Flags
+
+| Flag | Description |
+|------|-------------|
+| `--max-total-tokens <n>` | Total token budget |
+| `--max-input-tokens <n>` | Input token budget |
+| `--max-output-tokens <n>` | Output token budget |
+| `--max-reasoning-tokens <n>` | Reasoning token budget |
+| `--max-budget-usd <n>` | Maximum cost in USD |
+| `--max-tool-calls <n>` | Maximum tool calls per run |
+| `--max-delegated-tasks <n>` | Maximum delegated subtasks |
+| `--max-model-calls <n>` | Maximum model API calls |
+| `--max-session-turns <n>` | Maximum session turns |
+| `--input-cost-per-million <n>` | Input token pricing |
+| `--output-cost-per-million <n>` | Output token pricing |
+
+### Context Control Flags
+
+| Flag | Description |
+|------|-------------|
+| `--auto-snip-threshold <n>` | Auto-snip older messages at this token count |
+| `--auto-compact-threshold <n>` | Auto-compact at this token count |
+| `--compact-preserve-messages <n>` | Messages to preserve during compaction |
+| `--disable-claude-md` | Disable CLAUDE.md discovery |
+
+### Structured Output Flags
+
+| Flag | Description |
+|------|-------------|
+| `--response-schema-file <path>` | JSON schema file for structured output |
+| `--response-schema-name <name>` | Schema name identifier |
+| `--response-schema-strict` | Enforce strict schema validation |
+
+### Slash Commands
+
+These are handled **locally** before the model loop:
+
+| Command | Aliases | Description |
+|---------|---------|-------------|
+| `/help` | `/commands` | Show built-in slash commands |
+| `/context` | `/usage` | Show estimated session context usage |
+| `/context-raw` | `/env` | Show raw environment & context snapshot |
+| `/token-budget` | `/budget` | Show prompt-window budget, reserves, and soft/hard input limits |
+| `/mcp` | — | Show MCP runtime status, tools, or a single MCP tool |
+| `/resources` | — | List MCP resources |
+| `/resource` | — | Read an MCP resource by URI |
+| `/search` | — | Show search status, providers, activate a provider, or run a search |
+| `/remote` | — | Show local remote status or activate a target |
+| `/remotes` | — | List local remote profiles |
+| `/ssh` | — | Activate an SSH-style remote profile |
+| `/teleport` | — | Activate a teleport-style remote profile |
+| `/direct-connect` | — | Activate a direct-connect remote profile |
+| `/deep-link` | — | Activate a deep-link remote profile |
+| `/disconnect` | `/remote-disconnect` | Disconnect the active remote runtime target |
+| `/account` | — | Show account runtime status or profiles |
+| `/login` | — | Activate a local account profile or identity |
+| `/logout` | — | Clear the active account session |
+| `/config` | `/settings` | Inspect effective config, sources, or a single config value |
+| `/plan` | `/planner` | Show the local plan runtime state |
+| `/tasks` | `/todo` | Show the local task list |
+| `/task` | — | Show a task by id |
+| `/task-next` | `/next-task` | Show the next actionable tasks |
+| `/prompt` | `/system-prompt` | Render the effective system prompt |
+| `/hooks` | `/policy` | Show local hook/policy manifests |
+| `/trust` | — | Show trust mode, managed settings, and safe env values |
+| `/permissions` | — | Show active tool permission mode |
+| `/model` | — | Show or update the active model |
+| `/tools` | — | List registered tools with permission status |
+| `/agents` | — | List, show, create, update, or delete local agent definitions |
+| `/memory` | — | Show loaded CLAUDE.md memory bundle |
+| `/status` | `/session` | Show runtime/session status summary |
+| `/clear` | — | Clear ephemeral runtime state |
+
+```bash
+python3 -m src.main agent "/help"
+python3 -m src.main agent "/context" --cwd .
+python3 -m src.main agent "/token-budget" --cwd .
+python3 -m src.main agent "/tools" --cwd .
+python3 -m src.main agent "/agents" --cwd .
+python3 -m src.main agent "/status" --cwd .
+```
+
+### Custom Agent Definitions
+
+Custom agent profiles can live in either of these directories:
+
+- `./.claude/agents/*.md`
+- `~/.claude/agents/*.md`
+
+Project agents override user agents, and user agents override built-ins when the `agent_type` matches.
+
+Example agent file:
+
+```md
+---
+name: reviewer
+description: "Review implementation changes carefully."
+tools: read_file, grep_search
+model: Qwen/Qwen3-Coder-30B-A3B-Instruct
+initialPrompt: Start by identifying the highest-risk files.
+---
+
+Inspect code changes and summarize correctness risks, regressions, and missing tests.
+```
+
+Inspect the loaded profiles:
+
+```bash
+python3 -m src.main agents --cwd .
+python3 -m src.main agents reviewer --cwd .
+python3 -m src.main agent "/agents" --cwd .
+python3 -m src.main agent "/agents show reviewer" --cwd .
+```
+
+Create, update, or delete agent files from the CLI:
+
+```bash
+python3 -m src.main agents-create reviewer \
+  --cwd . \
+  --description "Review implementation changes carefully." \
+  --prompt "Inspect code changes and summarize risks." \
+  --tools read_file,grep_search \
+  --model Qwen/Qwen3-Coder-30B-A3B-Instruct
+
+python3 -m src.main agents-update reviewer \
+  --cwd . \
+  --description "Review implementation changes and tests carefully." \
+  --prompt "Focus on regressions, missing tests, and risky diffs."
+
+python3 -m src.main agents-delete reviewer --cwd . --source project
+```
+
+Or use the local slash command management forms:
+
+```bash
+python3 -m src.main agent "/agents create reviewer :: Review implementation changes carefully. :: Inspect code changes and summarize risks." --cwd .
+python3 -m src.main agent "/agents update reviewer Updated review description :: Focus on regressions and missing tests." --cwd .
+python3 -m src.main agent "/agents delete reviewer" --cwd .
+```
+
+### Utility Commands
+
+```bash
+python3 -m src.main summary            # Workspace summary
+python3 -m src.main manifest           # Workspace manifest
+python3 -m src.main commands --limit 10 # Command inventory
+python3 -m src.main tools --limit 10    # Tool inventory
+```
+
+---
+
+## 🔧 Built-in Tools
+
+The runtime currently includes core and extended tools:
+
+| Tool | Description | Permission |
+|------|-------------|------------|
+| `list_dir` | List files and directories | 🟢 Always |
+| `read_file` | Read file contents (with line ranges) | 🟢 Always |
+| `write_file` | Write or create files | 🟡 `--allow-write` |
+| `edit_file` | Edit files via exact string matching | 🟡 `--allow-write` |
+| `glob_search` | Find files by glob pattern | 🟢 Always |
+| `grep_search` | Search file contents by regex | 🟢 Always |
+| `bash` | Execute shell commands | 🔴 `--allow-shell` |
+| `web_fetch` | Fetch local or remote text content by URL | 🟢 Always |
+| `search_status` / `search_list_providers` / `search_activate_provider` / `web_search` | Search runtime status and provider-backed web search | 🟢 Always |
+| `tool_search` | Search the current Python tool registry | 🟢 Always |
+| `sleep` | Bounded local wait tool | 🟢 Always |
+| `config_list` / `config_get` / `config_set` | Inspect and mutate local workspace config | `config_set` is 🟡 `--allow-write` |
+| `account_status` / `account_list_profiles` / `account_login` / `account_logout` | Inspect and mutate local account state | 🟢 Always |
+| `remote_status` / `remote_list_profiles` / `remote_connect` / `remote_disconnect` | Inspect and mutate local remote runtime state | 🟢 Always |
+| `mcp_list_resources` / `mcp_read_resource` / `mcp_list_tools` / `mcp_call_tool` | Use local MCP resources and transport-backed MCP tools | 🟢 Always |
+| `plan_get` / `update_plan` / `plan_clear` | Inspect and mutate the local plan runtime | `update_plan` is 🟡 `--allow-write` |
+| `task_next` / `task_list` / `task_get` / `task_create` / `task_update` / `task_start` / `task_complete` / `task_block` / `task_cancel` / `todo_write` | Persistent local task and todo management | write-like task mutations are 🟡 `--allow-write` |
+| `delegate_agent` | Delegate work to nested child agents | 🟢 Always |
+
+---
+
+## 🔌 Plugin System
+
+Claw Code Agent supports a **manifest-based plugin runtime**. Drop a `plugin.json` in a `plugins/` subdirectory:
+
+```json
+{
+  "name": "my-plugin",
+  "hooks": {
+    "beforePrompt": "Inject guidance into the system prompt.",
+    "afterTurn": "Run after each agent turn.",
+    "onResume": "Reapply state on session resume.",
+    "beforePersist": "Save state before session is saved.",
+    "beforeDelegate": "Inject guidance before child agents.",
+    "afterDelegate": "Process child agent results."
+  },
+  "toolAliases": [
+    { "name": "my_read", "baseTool": "read_file", "description": "Custom read alias." }
+  ],
+  "virtualTools": [
+    { "name": "my_tool", "description": "A virtual tool.", "responseTemplate": "result: {input}" }
+  ]
+}
+```
+
+> See [TESTING_GUIDE.md](TESTING_GUIDE.md) **Section 19** for full plugin testing commands.
+
+---
+
+## 🪆 Nested Agent Delegation
+
+The agent can delegate subtasks to child agents with full context carryover:
+
+```bash
+python3 -m src.main agent \
+  "Delegate a subtask to inspect src/agent_runtime.py and return a summary." \
+  --cwd . --show-transcript
+```
+
+Features:
+- Sequential and parallel subtask execution
+- Dependency-aware topological batching
+- Child-session save and resume
+- Agent manager lineage tracking
+
+> See [TESTING_GUIDE.md](TESTING_GUIDE.md) **Section 20** for delegation testing commands.
+
+---
+
+## 🖥️ Local Web GUI
+
+If the terminal isn't your thing, launch the bundled browser GUI:
+
+```bash
+python3 -m src.gui --cwd . --allow-write --allow-shell
+```
+
+Your default browser opens to `http://127.0.0.1:8765` with a modern dark-themed chat UI.
+
+| Flag | Description |
+|------|-------------|
+| `--host <addr>` | Bind address (default `127.0.0.1`) |
+| `--port <n>` | Port to listen on (default `8765`) |
+| `--cwd <path>` | Workspace directory the agent operates in |
+| `--model <name>` | Override the model name |
+| `--base-url <url>` | Override the OpenAI-compatible API base URL |
+| `--api-key <key>` | API key for the model server |
+| `--session-dir <path>` | Where saved sessions live |
+| `--allow-write` | Allow file write/edit tools |
+| `--allow-shell` | Allow shell execution |
+| `--no-browser` | Don't auto-open a browser tab |
+
+The GUI surfaces:
+
+- multi-turn chat with tool-call cards (collapsible JSON args + results)
+- saved sessions sidebar with one-click resume
+- slash command and skill pickers (`/` and `★` buttons, or `Cmd/Ctrl+K`)
+- live settings panel (model, base URL, working dir, permissions)
+- usage / cost meta in the composer footer
+
+> **Note:** The GUI uses [FastAPI](https://fastapi.tiangolo.com/) and [Uvicorn](https://www.uvicorn.org/) under the hood. These get installed automatically if you install the package via `pip install -e .`. The core Python agent runtime itself remains dependency-free.
+
+---
+
+## 🔄 Session Persistence
+
+Each `agent` run automatically saves a resumable session:
+
+```text
+session_id=4f2c8c6f9c0e4d7c9c7b1b2a3d4e5f67
+session_path=.port_sessions/agent/4f2c8c6f...
+```
+
+Resume a previous session:
+
+```bash
+python3 -m src.main agent-resume \
+  4f2c8c6f9c0e4d7c9c7b1b2a3d4e5f67 \
+  "Continue the previous task and finish the missing parts."
+```
+
+Resume directly into interactive chat:
+
+```bash
+python3 -m src.main agent-chat \
+  --resume-session-id <session-id> \
+  --cwd .
+```
+
+Inspect saved sessions:
+
+```bash
+ls -lt .port_sessions/agent
+```
+
+> **Note:** Run `agent-resume` from the same `claw-code/` directory where the session was created. A resumed session continues from the saved transcript, not from scratch.
+
+---
+
+## 🧪 Testing
+
+Run the full test suite:
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+Smoke tests:
+
+```bash
+python3 -m src.main agent "/help"
+python3 -m src.main agent-context --cwd .
+python3 -m src.main agent \
+  "Read src/agent_session.py and summarize the message flow." \
+  --cwd .
+```
+
+> 📚 **Full testing guide:** See [TESTING_GUIDE.md](TESTING_GUIDE.md) for step-by-step commands covering the full implemented runtime surface.
+
+---
+
+## 🔐 Permission Model
+
+Claw Code Agent uses a **tiered permission system** to keep the agent safe by default:
+
+| Tier | Capability | Flag Required |
+|------|-----------|---------------|
+| **Read-only** | List, read, glob, grep | None (default) |
+| **Write** | + file creation and editing | `--allow-write` |
+| **Shell** | + shell command execution | `--allow-shell` |
+| **Unsafe** | + destructive shell operations | `--unsafe` |
+
+---
+
+## 🔎 Parity Status
+
+The full implementation checklist tracking parity against the npm `src` lives in [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md).
+
+It covers: core runtime, CLI modes, prompt assembly, context/memory, slash commands, tools, permissions, plugins, MCP, REPL/TUI, remote features, editor integrations, and internal subsystems.
+
+---
+
+## ⚠️ Disclaimer
+
+- This repository is a **Python reimplementation** inspired by the Claude Code npm architecture.
+- It does **not** ship the original npm source.
+- It is **not** affiliated with or endorsed by Anthropic.
+
+---
+
+<p align="center">
+  <sub>Built with 🐍 Python · Powered by 🐉 HarnessLab Team.</sub>
+</p>
diff --git a/data_agent_v0.md b/data_agent_v0.md
index 3f5fd1e..22b0896 100644
--- a/data_agent_v0.md
+++ b/data_agent_v0.md
@@ -1,149 +1,29 @@
-文档结构
-1. 数据迭代Agent架构
-
-
-
-
-
-- 1-2周MVP方案
-- badcase反馈渠道接入、自动收集分析
-
-- 1-2周MVP方案
-1. 定义一个最小的任务流程，整理流程中AI需要具备的能力
-  - 工具
-  - 记忆
-  - 环境
-  - 技术选型
-
+中控数据Agent构建-汇报
  Badcase 反馈渠道接入与自动收集分析:数据挖掘Agent设计方案
-
-Router Data Agent Workbench 方案文档
-1. 背景
-当前快慢系统路由的数据开发流程，主要围绕以下任务展开：
-  - 分析需求 / badcase
-  - 明确快慢系统边界
-  - 构建评测集
-  - 构建训练集
-  - 挖掘线上样本
-  - 人工标注与复核
-  - 模型训练与回放评估
-  - 根据结果继续补齐数据
-现有流程本质上仍然是 人驱动的数据开发
-  人理解需求
-→ 人拆解边界
-→ 人写 prompt / 规则
-→ 人捞数据
-→ 人筛样本
-→ 人整理评测集
-→ 人分析模型问题
-→ 人沉淀经验
-这个流程可以用 AI 做局部提效，但如果只是把每一步变成一个 LLM 节点，本质上仍然是旧框架。
-本项目希望重构的不是某几个节点，而是整个数据开发范式。
-
----
-1.1 业务尝试：快慢系统评测集构建
-当前路由标签空间包括：
-FAST_DIRECT
-SLOW_FILTER_RANK
-SLOW_DISAMBIGUATE
-SLOW_GOAL_STATE
-SLOW_WORKFLOW
-SLOW_CONTEXT_DEPENDENT
-SLOW_UNCLEAR
-SLOW_ADVANCED_CAPABILITY
-这些标签不是普通分类标签，而是路由系统的 能力边界定义。
-评测集构建的核心目标也不是简单判断 fast / slow，而是判断：
-这个请求为什么复杂？
-complexity reason 是什么？
-例如：
-导航到附近停车场
-→ FAST_DIRECT
-
-导航到附近最大的停车场
-→ SLOW_FILTER_RANK
-真正困难的不是打标签本身，而是持续维护这些边界：
-- 哪些请求快系统可以稳定承接？
-- 哪些请求必须交给慢系统？
-- 哪些 case 是边界混淆？
-- 哪些标签定义不清？
-- 哪些线上 badcase 暴露了新的边界问题？
-- 哪些模型错误值得转成训练集 / 评测集？
-2. 数据迭代Agent架构
-建设一个面向快慢路由系统的数据开发 Agent 环境：Router Data Agent Workbench
-它的目标是：
-让 Agent 能够围绕一个需求 / badcase，自主理解问题、探索数据、发现边界冲突、提出人工裁决问题、生成评测集候选、沉淀长期经验，从而显著提升路由评测 / 训练数据构建效率。
-目标不是做一个固定流程平台，而是做一个 Agent-native 的数据开发工作台。
-
----
-2.1 Agent定位
-- 不做传统 workflow+LLM节点提效
+1. 背景与目标
+- 数据开发是中控核心工作之一，但当前流程仍以人工驱动为主。
+- 需求 / badcase 驱动的评测集构建、样本补充和线上挖掘链路分散，人工介入重、复用性差。
+- 结合近期 AI native 工作方式转变，我们希望基于 Agent 底座先打通最小数据开发闭环。
+当前方式的瓶颈与挑战：
+- 人工驱动重：从需求、badcase 到评测集构建，多个关键环节依赖人工推进。 
+- 流程割裂重：人工构造、线上挖掘、LLM 生成彼此分散，数据格式转换和整理成本高。 
+- 经验复用弱：边界判断和处理经验难以沉淀，导致新问题进入后仍需重复劳动。
+数据开发范式转变：
 [图片]
-2.1.1 不做传统 workflow
-不采用这种模式：
-需求理解节点
-→ 边界分析节点
-→ 样本挖掘节点
-→ 预打标节点
-→ 人工审核节点
-→ 评测集生成节点
-这种方式的问题是：
-- 还是人预先设计流程
-- LLM 只是填充节点
-- Agent 没有真正自主决策
-- 新问题仍然需要人调整流程 / prompt
-- 长期价值有限
-这不是 AI 原生，而是旧流程自动化。
+2. AI Native数据Agent
+不是做一个固定流程平台，而是做一个 Agent-native 的数据开发工作台。
+让 Agent 能够围绕一个需求 / badcase，自主理解问题、探索数据、发现边界冲突、提出人工裁决问题、生成评测集候选、沉淀长期经验，从而显著提升路由评测 / 训练数据构建效率。
 
 ---
-2.1.2  做 Agent-native workbench
-目标模式是：
-给 Agent 一个目标、工作区、资料、工具、经验、权限和评价标准；
-Agent 自己决定下一步做什么；
-系统负责提供环境、边界、记录、校验和人工裁决入口。
-核心区别：
-传统 Workflow
-Agent-native Workbench
-人提前画流程
-Agent 根据任务自主推进
-LLM 填节点
-Agent 自己选择资料、工具和行动
-prompt 是核心
-workspace / skills / memory / tools 是核心
-人负责执行大量步骤
-人只负责关键业务裁决
-每次任务从头开始
-经验持续沉淀，下一次复用
-输出一个结果
-输出结果 + 过程 + 经验 + 可复用资产
+2.1 设计目标与边界
+- 核心目标：基于一个精简、可定制的 Agent 底座，建设一个面向中控数据开发场景的智能体执行底座。
+- 方案形态：不是“流程自动化 + LLM 节点”，而是一个以 Agent 为核心、能够围绕任务自主检索、生成、筛选和整理的数据开发执行底座。
+- 实现方式：基于 code-agent / claw-code-agent 实现，复用 Agent loop、文件读写、工具调用、代码执行、过程记录等通用能力。
+[图片]
 
 ---
-2.2 系统定位
-Router Data Agent Workbench 应该承担以下职责：
-输入：
-- 需求文档
-- badcase
-- 线上 session
-- 当前标签定义
-- 历史评测集
-- 模型预测结果
-- 人工裁决记录
-
-输出：
-- 边界分析
-- open questions
-- 人工裁决问题
-- 候选样本池
-- 标注任务
-- 专项评测集候选
-- 训练集候选
-- 回放评估报告
-- 标签定义修订建议
-- 可复用经验
-它不是一个“评测集生成器”，而是一个 路由数据开发 Agent 工作环境。
-
----
-2.3 核心架构
-Router Data Agent Workbench 由 6 个核心要素组成：
+2.2 核心架构
+- 中控数据Agent应该由 6 个核心要素组成：
   -  Workspace：任务工作区
   - Skills：领域经验包
   - Tools：可执行工具
@@ -152,7 +32,7 @@ Router Data Agent Workbench 由 6 个核心要素组成：
 [图片]
 
 ---
-2.4 Workspace：任务工作区
+2.2.1 Workspace：任务工作区
 每个需求 / badcase 启动后，系统创建一个独立 workspace。
 示例结构：
 [图片]
@@ -163,32 +43,14 @@ Workspace 的作用：
 - 支持人机协作
 - 沉淀可复用经验
 - 保证过程可追溯
-Agent 不是在一个固定流程里跑，而是在 workspace 中像研究员一样工作。
+Agent 不是在一个固定流程里跑，而是在 workspace 按照我们之前的工作流程去工作
 
 ---
-2.5 MD First：以 Markdown 作为 Agent 工作语言
+2.2.2 MD First：以 Markdown 作为 Agent 工作语言
 [图片]
 Agent 工作过程优先使用 Markdown
-适合用 Markdown 的内容：
-需求理解
-边界分析
-open questions
-人工裁决记录
-挖掘策略
-失败尝试
-经验总结
-效果报告
-标签定义说明
-原因：
-- MD 更适合人读
-- MD 更适合 Agent 自然读写
-- MD 更适合沉淀讨论和判断过程
-- MD 更接近真实工作台，而不是状态机
-但不是完全不要结构化。
-原则是：
-MD 是 Agent 的工作语言；
-JSONL / CSV / DB 是数据资产的交换格式。
-也就是：
+- MD 是 Agent 的工作语言；
+- JSONL / CSV / DB 是数据资产的交换格式。
 内容
 推荐格式
 需求理解
@@ -209,22 +71,10 @@ JSONL
 表格 + MD 报告
 工具调用参数
 schema / JSON
-最终原则：
-Agent 工作过程 MD first；
-系统边界 schema when needed。
 
 ---
-2.6 Skills：领域经验包，而不是流程节点
+2.2.3 Skills：固化成熟工作流程
 [图片]
-Skills 不应该被设计成固定节点。
-错误理解：
-Skill 1：需求理解
-Skill 2：边界分析
-Skill 3：数据挖掘
-Skill 4：预打标
-Skill 5：评测生成
-这还是 workflow。
-正确理解：
 Skill 是 Agent 可发现、可按需加载、可组合的领域经验包。
 示例：
 /skills/
@@ -261,33 +111,10 @@ Agent 在运行中根据问题自主选择是否读取某个 skill。
 
 发现模型离线准确率高但线上效果差
 → 读取 active-learning-router skill
-Skill 的价值不是定义流程，而是沉淀经验。
+Skill ：之前工作经验的沉淀
 
 ---
-2.7 Resources：可检索资料
-Resources 是 Agent 可读取的业务上下文。
-包括：
-当前标签定义
-历史标签定义版本
-历史 badcase
-历史人工裁决
-已有评测集
-已有训练集
-线上 session 索引
-topquery 集合
-模型预测结果
-模型误判样本
-历史回放报告
-Agent 不应该一次性把所有资料塞进上下文。
-更合理的方式是：
-Agent 先读任务目标
-→ 判断需要什么资料
-→ 按需检索相关资源
-→ 只把当前需要的内容纳入上下文
-这样可以避免上下文污染，也能让 Agent 更像真实研究员一样探索。
-
----
-2.8 Tools：可执行能力
+2.2.4 Tools：可执行能力
 Tools 是 Agent 可以调用的实际能力。
 示例：
 search_online_sessions()
@@ -314,7 +141,7 @@ Agent 自己决定：
 什么时候请求人工裁决
 
 ---
-2.9 Memory：Agent 外部认知状态
+2.2.5 Memory：Agent 外部认知状态
 Memory 不是简单存几个结构化字段。
 错误理解：
 {
@@ -348,74 +175,39 @@ reusable_lessons.md
 哪些样本适合评测集
 哪些样本只适合训练集
 哪些模型错误模式反复出现
-判断系统是否真正 Agent-native 的关键标准之一：
-下一次遇到类似问题，Agent 是否明显更聪明。
 
 ---
-2.10 Policy：权限与人工裁决边界
+2.2.6 Policy：权限与人工裁决边界
 [图片]
 Agent 可以自主推进任务，但不能无限自由。
 需要明确哪些事情 Agent 可以自动做，哪些必须人类确认。
-暂时无法在小米办公Pro文档外展示此内容
-核心原则：
-Agent 负责探索和建议；
-人负责业务边界裁决。
+动作
+权限
+读取需求文档
+自动
+读取历史标签定义
+自动
+查询脱敏线上 session
+自动
+挖候选样本
+自动
+聚类去重
+自动
+预打标
+自动
+生成边界分析
+自动
+生成标签定义修订建议
+自动
+修改标签边界
+人工确认
+样本入库抽检
+人工确认
+修改历史数据资产
+人工确认
 
 ---
-3. 人的角色
-人不再是流程执行者。
-人不应该做：
-手写 prompt
-手动拼关键词
-手动捞数据
-手动合并 Excel
-大量刷 easy case
-手动维护所有边界记忆
-人应该做：
-裁决业务边界
-确认标签定义变更
-审核 golden set 入库
-处理高分歧样本
-处理高流量低置信样本
-确认模型回放结论
-一句话：
-人是边界裁判，不是数据流水线工人。
-
----
-4. Agent 应该如何向人提问
-Agent 不应该问：
-下一步怎么办？
-而应该提出可裁决问题。
-示例：
-边界裁决问题：
-
-“导航到最近的停车场”应该标为 FAST_DIRECT 还是 SLOW_FILTER_RANK？
-
-候选判断：
-
-A. FAST_DIRECT
-理由：最近可以视为导航系统默认距离排序，快系统可以直接执行。
-
-B. SLOW_FILTER_RANK
-理由：最近也是排序条件，请求涉及候选集合选择。
-
-Agent 建议：A
-
-原因：
-当前快系统导航 POI 默认支持距离优先，因此“最近的停车场”不应等同于“最大的停车场 / 评分最高的停车场”这类优化筛选请求。
-
-请确认：
-1. 接受 A
-2. 改为 B
-3. 补充新的边界规则
-人工裁决后，Agent 写入：
-memory/human_decisions.md
-长期标签边界知识库
-相关 skill 的 known-confusions.md
-以后类似问题直接复用。
-
----
-5. 典型运行方式
+2.3 典型运行方式
 [图片]
 
 用户输入：
@@ -438,116 +230,162 @@ Agent 启动任务 workspace。
 14. 生成候选评测集
 15. 生成回放报告
 16. 沉淀 reusable_lessons.md
-注意：这不是预设流程，而是一个典型任务可能自然形成的行动轨迹。
 
 ---
-6. 关键产物
-第一版系统建议产出以下文件：
-goal.md
-current_understanding.md
-boundary_analysis.md
-open_questions.md
-human_decisions.md
-failed_attempts.md
-reusable_lessons.md
-candidate_pool.csv
-annotation_queue.csv
-eval_set_candidate.jsonl
-label_definition_patch.md
-replay_report.md
-trace.md
-skills_used.md
-这些产物分为三类：
-6.1 Agent / 人类协作产物
-goal.md
-current_understanding.md
-boundary_analysis.md
-open_questions.md
-human_decisions.md
-reusable_lessons.md
-6.2 数据资产产物
-candidate_pool.csv
-annotation_queue.csv
-eval_set_candidate.jsonl
-6.3 审计与复盘产物
-trace.md
-skills_used.md
-failed_attempts.md
-replay_report.md
-
----
-7. MVP 建议
-第一版不要做大而全平台。
-先验证一个最小闭环：
-输入 badcase，Agent 能否自主探索并产出高质量边界问题和候选评测集。
-MVP 输入
-1. 一批 badcase
-2. 当前标签定义
-3. 可查询的线上 session / topquery
-4. 现有评测集
-5. 模型预测结果，可选
-MVP 输出
-1. boundary_analysis.md
-2. open_questions.md
-3. human_decisions.md
-4. candidate_pool.csv
-5. eval_set_candidate.jsonl
-6. replay_report.md
-7. reusable_lessons.md
-MVP 验收标准
-1. Agent 能自己识别涉及的标签边界
-2. Agent 能自己查找相关历史定义 / 样本
-3. Agent 能自己提出挖掘策略
-4. Agent 能找出一批有效候选样本
-5. Agent 能提出高质量人工裁决问题
-6. 人工裁决后，Agent 能继续修正结果
-7. 最终候选评测集可被人工抽检使用
-8. 本次经验能被后续任务复用
-
----
-8. 成功标准
-项目成功不看是否跑通一个固定流程，而看以下能力：
-1. Agent 是否能自主理解新需求 / badcase？
-2. Agent 是否能主动寻找相关历史定义和裁决？
-3. Agent 是否能判断当前问题属于哪些标签边界？
-4. Agent 是否能自主决定挖哪些数据？
-5. Agent 是否能发现标签定义冲突？
-6. Agent 是否能提出高质量人工裁决问题？
-7. Agent 是否能生成可用候选评测集？
-8. Agent 是否能根据人工裁决修正自己的判断？
-9. Agent 是否能沉淀经验？
-10. 下一次遇到类似问题，Agent 是否明显更聪明？
-最重要的是第 10 点。
-如果每次任务都像第一次一样重新开始，那就不是经验驱动。
-
----
-9. 最终结论
+3. 第一阶段目标
+- 基于现有 Agent 底座完成最小运行环境搭建，并优先打通三条主要的数据开发链路：
+  - 需求 / badcase 反馈 → 生成式构建专项评测集 → 数据持久化
+  - 需求 / badcase 反馈 → 挖掘线上问题 → 构建专项评测集 → 数据持久化
+  - badcase 自动收集与分析链路打通
+3.1  第一阶段落地方案
+第一阶段基于现有 claw-code-agent 作为执行底座，在保留其通用 Agent 能力的基础上，补齐面向中控数据开发场景的输入、检索、生成、落盘和 review 能力。
+让 claw-code-agent 从一个通用 code-agent，变成一个能够进入中控数据开发环境并执行真实任务的数据 Agent 底座。
+前两周的目标：
+在一个受控工作区内完成：
+-  读取需求 / badcase 
+-  检索线上样本 
+-  生成或筛选评测集候选 
+-  记录过程和中间判断 
+-  输出可落盘、可 review 的结果 
+在这一底座之上，第一阶段优先验证三条真实链路：
+-  需求 / badcase 反馈 → 生成式构建专项评测集 → 数据持久化 
+-  需求 / badcase 反馈 → 挖掘线上问题 → 构建专项评测集 → 数据持久化 
+-  badcase 自动收集与分析链路打通 
+落地原则：
+底层复用
+claw-code-agent 现有的 loop、tool calling、session persistence、transcript、compaction、markdown memory 注入、policy hook 等能力已经足够成熟，适合作为底层执行引擎直接复用。
+ 因此，第一阶段不重写主循环，不重写工具调用链，不重写 session 基础设施。
+上层收口
+当前 claw-code-agent 的默认形态是 coding-first：prompt 偏代码助手，工具面偏泛代码操作，workspace 也更接近 code workspace。
+ 第一阶段要做的不是扩展更多能力，而是把这些默认形态收口成 data-first：让 Agent 更聚焦于数据检索、样本筛选、评测集构建和结果沉淀。
+具体任务拆解：
+直接复用底层执行内核
+这一部分不作为改造重点，只作为底座能力直接承接：
+-  Agent loop 
+-  session / transcript / file_history 
+-  tool schema + tool execution 
+-  markdown memory 注入基础能力 
+-  hook / policy 基础机制 
+-  compaction / replay 基础设施 
+这些能力已经能支撑“模型驱动循环 + 工具调用 + 过程追踪”，第一阶段不需要投入主要精力。
+需要改造的四个点：
+1）把 code workspace 改成 task workspace @王云浩 
+这是最关键的一步。
+ 当前底座支持 markdown memory，但还没有真正 task-native 的工作区。第一阶段要把任务固定到 /tasks/{task_id}/ 目录下，让输入、记忆、产物和日志都围绕任务目录组织。
+2）把 coding-first prompt 改成 data-first prompt @王云浩 
+当前 system prompt 更强调读代码、改代码、bash、git、验证代码修改。
+ 第一阶段需要改成围绕：
+-  需求理解 
+-  边界分析 
+-  open questions 
+-  样本挖掘 
+-  标注 / 裁决 
+-  eval/train set 构造 
+-  经验沉淀 
+这些数据任务来组织默认口径。
+3）把默认工具集改成最小数据工具集 @武阳 
+当前工具面过宽，对数据 Agent 初版来说不是增强，而是噪音。
+ 第一阶段要做的是裁出一套 default_data_tool_registry()，只保留必要文件工具和少量数据专用工具，让 Agent 的动作空间收敛。
+4）把 coding policy 扩展成数据治理 policy @武阳 
+当前权限语义更像：
+-  allow write 
+-  allow shell 
+-  deny tool 
+-  ask user 
+但数据场景需要更细的治理边界，比如：
+-  是否允许查线上样本 
+-  是否允许导出敏感字段 
+-  是否允许生成标注任务 
+-  哪些问题必须人工裁决 
+-  哪些标签修订必须人工确认 
+这一部分必须在第一阶段明确下来。
+需要重点建设的两层能力：
+1）之前挖掘经验通过SKILL的方式进行注入(需要进行实验和验证)
+第一阶段 skill 不应再只是 prompt 片段，而应沉淀成目录化 markdown 经验包，至少覆盖：
+-  边界判断 
+-  线上挖掘 
+-  评测集构建 
+并采用“元信息先注入，正文按需展开”的方式，避免一次性把全部经验塞进上下文。
+2）artifacts 统一沉淀
+第一阶段所有关键结果都应统一沉淀到 task workspace 下，而不是只停留在 session json 或临时输出里。
+这一步是后续 review、复盘、数据资产化的前提。
+目标的形态
+/tasks/{task_id}/
+  goal.md
+  context/
+    requirement.md
+    badcase.md
+  memory/
+    open_questions.md
+    working_notes.md
+    decisions.md
+  artifacts/
+    eval_candidates.jsonl
+    mining_strategy.md
+    report.md
+  logs/
+    agent_trace.md
+在这个形态下，Agent 能够围绕一个任务完成：
+-  输入读取 
+-  数据检索 
+-  样本筛选或生成 
+-  结果沉淀 
+-  人工 review 触发 
+代码改造清单
+类型
+项目
+第一阶段动作
+说明
+直接复用
+Agent loop
+保留
+不重写主循环
+直接复用
+session / transcript / compaction
+保留
+直接复用过程追踪能力
+直接复用
+tool schema / execution
+保留
+不改调用链
+核心改造
+workspace
+改造
+从 code workspace 收口为 task workspace
+核心改造
+system prompt
+改造
+从 coding-first 改为 data-first
+核心改造
+默认工具集
+改造
+裁出最小数据工具集
+核心改造
+policy / human gate
+改造
+从 coding 权限扩展为数据治理边界
+必须新增
+skill 机制
+新增
+目录化 markdown 经验包，按需加载
+必须新增
+artifacts 沉淀规则
+新增
+所有关键结果统一沉淀到 task 目录
+业务验证
+生成式评测集构建
+打通
+作为第一条真实链路
+业务验证
+线上问题挖掘
+打通
+作为第二条真实链路
+业务验证
+badcase 自动收集分析
+打通
+作为第三条真实链路
 [图片]
-本项目不应该定义为：
-用 Agent 编排快慢系统评测集构建流程
-而应该定义为：
-给路由数据开发建设一个 Agent-native 工作环境。
-最终形态是：
-Router Data Agent Workbench
-它的核心不是流程，而是：
-Workspace
-Skills
-Resources
-Tools
-Memory
-Policy
-它要实现的能力是：
-需求 / badcase
-→ Agent 自主探索
-→ 发现边界问题
-→ 挖掘候选数据
-→ 提出人工裁决
-→ 生成评测 / 训练资产
-→ 回放验证
-→ 沉淀经验
-→ 下次复用
-一句话总结：
-不是让 AI 跑数据流程，而是让 Agent 拥有一个可以自主完成数据开发工作的环境。
+