add worktree & up task、teammate etc

Author: CrazyBoyM

README-ja.md

@@ -1,4 +1,4 @@
-# Learn Claude Code -- AI Agent をゼロから構築する
+# Learn Claude Code -- 0 から 1 へ構築する nano Claude Code-like agent
 
 [English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)
 
@@ -17,16 +17,16 @@
                     loop back -----------------> messages[]
 
 
-    これだけだ。すべての AI コーディングエージェントはこのループ。
-    他はすべて改良に過ぎない。
+    これは最小ループだ。すべての AI コーディングエージェントに必要な土台になる。
+    本番のエージェントには、ポリシー・権限・ライフサイクル層が追加される。
 ```
 
-**11 の段階的セッション、シンプルなループから完全な自律チームまで。**
+**12 の段階的セッション、シンプルなループから分離された自律実行まで。**
 **各セッションは1つのメカニズムを追加する。各メカニズムには1つのモットーがある。**
 
 > **s01**   *"Bash があれば十分"* — 1つのツール + 1つのループ = エージェント
 >
-> **s02**   *"ループは変わらない"* — ツール追加はハンドラー追加であり、ロジック追加ではない
+> **s02**   *"ループは変わらない"* — ツール追加はハンドラー追加であり、ループの作り直しではない
 >
 > **s03**   *"行動する前に計画せよ"* — 可視化された計画がタスク完了率を向上させる
 >
@@ -45,6 +45,8 @@
 > **s10**   *"同じ request_id、2つのプロトコル"* — 1つの FSM パターンでシャットダウン + プラン承認
 >
 > **s11**   *"ポーリング、クレーム、作業、繰り返し"* — コーディネーター不要、エージェントが自己組織化
+>
+> **s12**   *"ディレクトリで分離し、タスクIDで調整する"* — タスクボード + 必要時の worktree レーン
 
 ---
 
@@ -77,6 +79,19 @@ def agent_loop(messages):
 
 各セッションはこのループの上に1つのメカニズムを重ねる -- ループ自体は変わらない。
 
+## スコープ (重要)
+
+このリポジトリは、nano Claude Code-like agent を 0->1 で構築・学習するための教材プロジェクトです。
+学習を優先するため、以下の本番メカニズムは意図的に簡略化または省略しています。
+
+- 完全なイベント / Hook バス (例: PreToolUse, SessionStart/End, ConfigChange)。  
+  s12 では教材用に最小の追記型ライフサイクルイベントのみ実装している。
+- ルールベースの権限ガバナンスと信頼フロー
+- セッションライフサイクル制御 (resume/fork) と高度な worktree ライフサイクル制御
+- MCP ランタイムの詳細 (transport/OAuth/リソース購読/ポーリング)
+
+このリポジトリの JSONL メールボックス方式は教材用の実装であり、特定の本番内部実装を主張するものではありません。
+
 ## クイックスタート
 
 ```sh
@@ -87,6 +102,7 @@ cp .env.example .env   # .env を編集して ANTHROPIC_API_KEY を入力
 
 python agents/s01_agent_loop.py       # ここから開始
 python agents/s11_autonomous_agents.py  # 完全自律チーム
+python agents/s12_worktree_task_isolation.py  # Task 対応の worktree 分離
 ```
 
 ### Web プラットフォーム
@@ -124,6 +140,9 @@ s08  バックグラウンドタスク   [6]     s10  チームプロトコル
                                           |
                                      s11  自律エージェント        [14]
                                           アイドルサイクル + 自動クレーム
+                                     |
+                                     s12  Worktree 分離           [16]
+                                          タスク調整 + 必要時の分離実行レーン
 
                                      [N] = ツール数
 ```
@@ -133,7 +152,7 @@ s08  バックグラウンドタスク   [6]     s10  チームプロトコル
 ```
 learn-claude-code/
 |
-|-- agents/                        # Python リファレンス実装 (s01-s11 + 完全版)
+|-- agents/                        # Python リファレンス実装 (s01-s12 + 完全版)
 |-- docs/{en,zh,ja}/               # メンタルモデル優先のドキュメント (3言語)
 |-- web/                           # インタラクティブ学習プラットフォーム (Next.js)
 |-- skills/                        # s05 の Skill ファイル
@@ -158,11 +177,12 @@ learn-claude-code/
 | [s09](./docs/ja/s09-agent-teams.md) | エージェントチーム | *追記で送信、排出で読取* |
 | [s10](./docs/ja/s10-team-protocols.md) | チームプロトコル | *同じ request_id、2つのプロトコル* |
 | [s11](./docs/ja/s11-autonomous-agents.md) | 自律エージェント | *ポーリング、クレーム、作業、繰り返し* |
+| [s12](./docs/ja/s12-worktree-task-isolation.md) | Worktree + タスク分離 | *ディレクトリで分離し、タスクIDで調整する* |
 
 ## ライセンス
 
 MIT
 
 ---
 
-**モデルがエージェントだ。私たちの仕事はツールを渡して、邪魔をしないこと。**
+**モデルがエージェントだ。私たちの仕事はツールを与えて邪魔しないこと。**

README-zh.md

@@ -1,4 +1,4 @@
-# Learn Claude Code -- 从零构建 AI Agent
+# Learn Claude Code -- 从 0 到 1 构建 nano Claude Code-like agent
 
 [English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)
 
@@ -17,16 +17,16 @@
                     loop back -----------------> messages[]
 
 
-    就这些。每个 AI 编程 Agent 都是这个循环。
-    其他一切都是优化。
+    这是最小循环。每个 AI 编程 Agent 都需要这个循环。
+    生产级 Agent 还会叠加策略、权限与生命周期层。
 ```
 
-**11 个递进式课程, 从简单循环到完整的自治团队。**
+**12 个递进式课程, 从简单循环到隔离化的自治执行。**
 **每个课程添加一个机制。每个机制有一句格言。**
 
 > **s01**   *"Bash 就够了"* — 一个工具 + 一个循环 = 一个智能体
 >
-> **s02**   *"循环没有变"* — 加工具就是加 handler, 不是加逻辑
+> **s02**   *"循环没有变"* — 加工具就是加 handler, 不是重写循环
 >
 > **s03**   *"先计划再行动"* — 可见的计划提升任务完成率
 >
@@ -45,6 +45,8 @@
 > **s10**   *"同一个 request_id, 两个协议"* — 一个 FSM 模式驱动关机 + 计划审批
 >
 > **s11**   *"轮询, 认领, 工作, 重复"* — 无需协调者, 智能体自组织
+>
+> **s12**   *"目录隔离, 任务 ID 协调"* — 任务板协调 + 按需 worktree 隔离通道
 
 ---
 
@@ -77,6 +79,19 @@ def agent_loop(messages):
 
 每个课程在这个循环之上叠加一个机制 -- 循环本身始终不变。
 
+## 范围说明 (重要)
+
+本仓库是一个 0->1 的学习型项目，用于从零构建 nano Claude Code-like agent。
+为保证学习路径清晰，仓库有意简化或省略了部分生产机制：
+
+- 完整事件 / Hook 总线 (例如 PreToolUse、SessionStart/End、ConfigChange)。  
+  s12 仅提供教学用途的最小 append-only 生命周期事件流。
+- 基于规则的权限治理与信任流程
+- 会话生命周期控制 (resume/fork) 与更完整的 worktree 生命周期控制
+- 完整 MCP 运行时细节 (transport/OAuth/资源订阅/轮询)
+
+仓库中的团队 JSONL 邮箱协议是教学实现，不是对任何特定生产内部实现的声明。
+
 ## 快速开始
 
 ```sh
@@ -87,6 +102,7 @@ cp .env.example .env   # 编辑 .env 填入你的 ANTHROPIC_API_KEY
 
 python agents/s01_agent_loop.py       # 从这里开始
 python agents/s11_autonomous_agents.py  # 完整自治团队
+python agents/s12_worktree_task_isolation.py  # Task 感知的 worktree 隔离
 ```
 
 ### Web 平台
@@ -124,6 +140,9 @@ s08  后台任务                [6]     s10  团队协议               [12]
                                           |
                                      s11  自治智能体             [14]
                                           空闲轮询 + 自动认领
+                                     |
+                                     s12  Worktree 隔离          [16]
+                                          任务协调 + 按需隔离执行通道
 
                                      [N] = 工具数量
 ```
@@ -133,7 +152,7 @@ s08  后台任务                [6]     s10  团队协议               [12]
 ```
 learn-claude-code/
 |
-|-- agents/                        # Python 参考实现 (s01-s11 + 完整版)
+|-- agents/                        # Python 参考实现 (s01-s12 + 完整版)
 |-- docs/{en,zh,ja}/               # 心智模型优先的文档 (3 种语言)
 |-- web/                           # 交互式学习平台 (Next.js)
 |-- skills/                        # s05 的 Skill 文件
@@ -158,11 +177,12 @@ learn-claude-code/
 | [s09](./docs/zh/s09-agent-teams.md) | 智能体团队 | *追加即发送, 排空即读取* |
 | [s10](./docs/zh/s10-team-protocols.md) | 团队协议 | *同一个 request_id, 两个协议* |
 | [s11](./docs/zh/s11-autonomous-agents.md) | 自治智能体 | *轮询, 认领, 工作, 重复* |
+| [s12](./docs/zh/s12-worktree-task-isolation.md) | Worktree + 任务隔离 | *目录隔离, 任务 ID 协调* |
 
 ## 许可证
 
 MIT
 
 ---
 
-**模型就是智能体。我们的工作是给它工具, 然后让开。**
+**模型就是智能体。我们的工作就是给它工具, 然后让开。**

README.md

@@ -1,4 +1,4 @@
-# Learn Claude Code -- Build an AI Agent From Scratch
+# Learn Claude Code -- A nano Claude Code-like agent, built from 0 to 1
 
 [English](./README.md) | [中文](./README-zh.md) | [日本語](./README-ja.md)
 
@@ -17,16 +17,16 @@
                     loop back -----------------> messages[]
 
 
-    That's it. Every AI coding agent is this loop.
-    Everything else is refinement.
+    That's the minimal loop. Every AI coding agent needs this loop.
+    Production agents add policy, permissions, and lifecycle layers.
 ```
 
-**11 progressive sessions, from a simple loop to full autonomous teams.**
+**12 progressive sessions, from a simple loop to isolated autonomous execution.**
 **Each session adds one mechanism. Each mechanism has one motto.**
 
 > **s01**   *"Bash is all you need"* — one tool + one loop = an agent
 >
-> **s02**   *"The loop didn't change"* — adding tools means adding handlers, not logic
+> **s02**   *"The loop didn't change"* — adding tools means adding handlers, not rewriting the loop
 >
 > **s03**   *"Plan before you act"* — visible plans improve task completion
 >
@@ -45,6 +45,8 @@
 > **s10**   *"Same request_id, two protocols"* — one FSM pattern powers shutdown + plan approval
 >
 > **s11**   *"Poll, claim, work, repeat"* — no coordinator needed, agents self-organize
+>
+> **s12**   *"Isolate by directory, coordinate by task ID"* — task board + optional worktree lanes
 
 ---
 
@@ -77,6 +79,19 @@ def agent_loop(messages):
 
 Every session layers one mechanism on top of this loop -- without changing the loop itself.
 
+## Scope (Important)
+
+This repository is a 0->1 learning project for building a nano Claude Code-like agent.
+It intentionally simplifies or omits several production mechanisms:
+
+- Full event/hook buses (for example PreToolUse, SessionStart/End, ConfigChange).  
+  s12 includes only a minimal append-only lifecycle event stream for teaching.
+- Rule-based permission governance and trust workflows
+- Session lifecycle controls (resume/fork) and advanced worktree lifecycle controls
+- Full MCP runtime details (transport/OAuth/resource subscribe/polling)
+
+Treat the team JSONL mailbox protocol in this repo as a teaching implementation, not a claim about any specific production internals.
+
 ## Quick Start
 
 ```sh
@@ -87,6 +102,7 @@ cp .env.example .env   # Edit .env with your ANTHROPIC_API_KEY
 
 python agents/s01_agent_loop.py       # Start here
 python agents/s11_autonomous_agents.py  # Full autonomous team
+python agents/s12_worktree_task_isolation.py  # Task-aware worktree isolation
 ```
 
 ### Web Platform
@@ -124,6 +140,9 @@ s08  Background Tasks        [6]     s10  Team Protocols          [12]
                                           |
                                      s11  Autonomous Agents       [14]
                                           idle cycle + auto-claim
+                                     |
+                                     s12  Worktree Isolation      [16]
+                                          task coordination + optional isolated execution lanes
 
                                      [N] = number of tools
 ```
@@ -133,7 +152,7 @@ s08  Background Tasks        [6]     s10  Team Protocols          [12]
 ```
 learn-claude-code/
 |
-|-- agents/                        # Python reference implementations (s01-s11 + full)
+|-- agents/                        # Python reference implementations (s01-s12 + full)
 |-- docs/{en,zh,ja}/               # Mental-model-first documentation (3 languages)
 |-- web/                           # Interactive learning platform (Next.js)
 |-- skills/                        # Skill files for s05
@@ -158,6 +177,7 @@ Available in [English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/j
 | [s09](./docs/en/s09-agent-teams.md) | Agent Teams | *Append to send, drain to read* |
 | [s10](./docs/en/s10-team-protocols.md) | Team Protocols | *Same request_id, two protocols* |
 | [s11](./docs/en/s11-autonomous-agents.md) | Autonomous Agents | *Poll, claim, work, repeat* |
+| [s12](./docs/en/s12-worktree-task-isolation.md) | Worktree + Task Isolation | *Isolate by directory, coordinate by task ID* |
 
 ## License
 

agents/__init__.py

@@ -1,2 +1,2 @@
-# agents/ - Python teaching agents (s01-s11) + reference agent (s_full)
+# agents/ - Python teaching agents (s01-s12) + reference agent (s_full)
 # Each file is self-contained and runnable: python agents/s01_agent_loop.py

agents/s01_agent_loop.py

@@ -2,7 +2,7 @@
 """
 s01_agent_loop.py - The Agent Loop
 
-The entire secret of coding agents in one pattern:
+The entire secret of an AI coding agent in one pattern:
 
     while stop_reason == "tool_use":
         response = LLM(messages, tools)
@@ -18,8 +18,9 @@
                           +---------------+
                           (loop continues)
 
-That's it. The ENTIRE agent is a while loop that feeds tool
-results back to the model until the model decides to stop.
+This is the core loop: feed tool results back to the model
+until the model decides to stop. Production agents layer
+policy, hooks, and lifecycle controls on top.
 """
 
 import os