chore: import upstream snapshot with attribution

docs/ja/s01-the-agent-loop.md

@@ -0,0 +1,116 @@
+# s01: The Agent Loop
+
+`[ s01 ] s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
+
+> *"One loop & Bash is all you need"* -- 1つのツール + 1つのループ = エージェント。
+>
+> **Harness 層**: ループ -- モデルと現実世界を繋ぐ最初の接点。
+
+## 問題
+
+言語モデルはコードについて推論できるが、現実世界に触れられない。ファイルを読めず、テストを実行できず、エラーを確認できない。ループがなければ、ツール呼び出しのたびにユーザーが手動で結果をコピーペーストする必要がある。つまりユーザー自身がループになる。
+
+## 解決策
+
+```
++--------+      +-------+      +---------+
+|  User  | ---> |  LLM  | ---> |  Tool   |
+| prompt |      |       |      | execute |
++--------+      +---+---+      +----+----+
+                    ^                |
+                    |   tool_result  |
+                    +----------------+
+                    (loop until stop_reason != "tool_use")
+```
+
+1つの終了条件がフロー全体を制御する。モデルがツール呼び出しを止めるまでループが回り続ける。
+
+## 仕組み
+
+1. ユーザーのプロンプトが最初のメッセージになる。
+
+```python
+messages.append({"role": "user", "content": query})
+```
+
+2. メッセージとツール定義をLLMに送信する。
+
+```python
+response = client.messages.create(
+    model=MODEL, system=SYSTEM, messages=messages,
+    tools=TOOLS, max_tokens=8000,
+)
+```
+
+3. アシスタントのレスポンスを追加し、`stop_reason`を確認する。ツールが呼ばれなければ終了。
+
+```python
+messages.append({"role": "assistant", "content": response.content})
+if response.stop_reason != "tool_use":
+    return
+```
+
+4. 各ツール呼び出しを実行し、結果を収集してuserメッセージとして追加。ステップ2に戻る。
+
+```python
+results = []
+for block in response.content:
+    if block.type == "tool_use":
+        output = run_bash(block.input["command"])
+        results.append({
+            "type": "tool_result",
+            "tool_use_id": block.id,
+            "content": output,
+        })
+messages.append({"role": "user", "content": results})
+```
+
+1つの関数にまとめると:
+
+```python
+def agent_loop(query):
+    messages = [{"role": "user", "content": query}]
+    while True:
+        response = client.messages.create(
+            model=MODEL, system=SYSTEM, messages=messages,
+            tools=TOOLS, max_tokens=8000,
+        )
+        messages.append({"role": "assistant", "content": response.content})
+
+        if response.stop_reason != "tool_use":
+            return
+
+        results = []
+        for block in response.content:
+            if block.type == "tool_use":
+                output = run_bash(block.input["command"])
+                results.append({
+                    "type": "tool_result",
+                    "tool_use_id": block.id,
+                    "content": output,
+                })
+        messages.append({"role": "user", "content": results})
+```
+
+これでエージェント全体が30行未満に収まる。本コースの残りはすべてこのループの上に積み重なる -- ループ自体は変わらない。
+
+## 変更点
+
+| Component     | Before     | After                          |
+|---------------|------------|--------------------------------|
+| Agent loop    | (none)     | `while True` + stop_reason     |
+| Tools         | (none)     | `bash` (one tool)              |
+| Messages      | (none)     | Accumulating list              |
+| Control flow  | (none)     | `stop_reason != "tool_use"`    |
+
+## 試してみる
+
+```sh
+cd learn-claude-code
+python agents/s01_agent_loop.py
+```
+
+1. `Create a file called hello.py that prints "Hello, World!"`
+2. `List all Python files in this directory`
+3. `What is the current git branch?`
+4. `Create a directory called test_output and write 3 files in it`

docs/ja/s02-tool-use.md

@@ -0,0 +1,99 @@
+# s02: Tool Use
+
+`s01 > [ s02 ] s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
+
+> *"ツールを足すなら、ハンドラーを1つ足すだけ"* -- ループは変わらない。新ツールは dispatch map に登録するだけ。
+>
+> **Harness 層**: ツール分配 -- モデルが届く範囲を広げる。
+
+## 問題
+
+`bash`だけでは、エージェントは何でもシェル経由で行う。`cat`は予測不能に切り詰め、`sed`は特殊文字で壊れ、すべてのbash呼び出しが制約のないセキュリティ面になる。`read_file`や`write_file`のような専用ツールなら、ツールレベルでパスのサンドボックス化を強制できる。
+
+重要な点: ツールを追加してもループの変更は不要。
+
+## 解決策
+
+```
++--------+      +-------+      +------------------+
+|  User  | ---> |  LLM  | ---> | Tool Dispatch    |
+| prompt |      |       |      | {                |
++--------+      +---+---+      |   bash: run_bash |
+                    ^           |   read: run_read |
+                    |           |   write: run_wr  |
+                    +-----------+   edit: run_edit |
+                    tool_result | }                |
+                                +------------------+
+
+The dispatch map is a dict: {tool_name: handler_function}.
+One lookup replaces any if/elif chain.
+```
+
+## 仕組み
+
+1. 各ツールにハンドラ関数を定義する。パスのサンドボックス化でワークスペース外への脱出を防ぐ。
+
+```python
+def safe_path(p: str) -> Path:
+    path = (WORKDIR / p).resolve()
+    if not path.is_relative_to(WORKDIR):
+        raise ValueError(f"Path escapes workspace: {p}")
+    return path
+
+def run_read(path: str, limit: int = None) -> str:
+    text = safe_path(path).read_text()
+    lines = text.splitlines()
+    if limit and limit < len(lines):
+        lines = lines[:limit]
+    return "\n".join(lines)[:50000]
+```
+
+2. ディスパッチマップがツール名とハンドラを結びつける。
+
+```python
+TOOL_HANDLERS = {
+    "bash":       lambda **kw: run_bash(kw["command"]),
+    "read_file":  lambda **kw: run_read(kw["path"], kw.get("limit")),
+    "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
+    "edit_file":  lambda **kw: run_edit(kw["path"], kw["old_text"],
+                                        kw["new_text"]),
+}
+```
+
+3. ループ内で名前によりハンドラをルックアップする。ループ本体はs01から不変。
+
+```python
+for block in response.content:
+    if block.type == "tool_use":
+        handler = TOOL_HANDLERS.get(block.name)
+        output = handler(**block.input) if handler \
+            else f"Unknown tool: {block.name}"
+        results.append({
+            "type": "tool_result",
+            "tool_use_id": block.id,
+            "content": output,
+        })
+```
+
+ツール追加 = ハンドラ追加 + スキーマ追加。ループは決して変わらない。
+
+## s01からの変更点
+
+| Component      | Before (s01)       | After (s02)                |
+|----------------|--------------------|----------------------------|
+| Tools          | 1 (bash only)      | 4 (bash, read, write, edit)|
+| Dispatch       | Hardcoded bash call | `TOOL_HANDLERS` dict       |
+| Path safety    | None               | `safe_path()` sandbox      |
+| Agent loop     | Unchanged          | Unchanged                  |
+
+## 試してみる
+
+```sh
+cd learn-claude-code
+python agents/s02_tool_use.py
+```
+
+1. `Read the file requirements.txt`
+2. `Create a file called greet.py with a greet(name) function`
+3. `Edit greet.py to add a docstring to the function`
+4. `Read greet.py to verify the edit worked`

docs/ja/s03-todo-write.md

@@ -0,0 +1,96 @@
+# s03: TodoWrite
+
+`s01 > s02 > [ s03 ] s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
+
+> *"計画のないエージェントは行き当たりばったり"* -- まずステップを書き出し、それから実行。
+>
+> **Harness 層**: 計画 -- 航路を描かずにモデルを軌道に乗せる。
+
+## 問題
+
+マルチステップのタスクで、モデルは途中で迷子になる。作業を繰り返したり、ステップを飛ばしたり、脱線したりする。長い会話になるほど悪化する -- ツール結果がコンテキストを埋めるにつれ、システムプロンプトの影響力が薄れる。10ステップのリファクタリングでステップ1-3を完了した後、残りを忘れて即興を始めてしまう。
+
+## 解決策
+
+```
++--------+      +-------+      +---------+
+|  User  | ---> |  LLM  | ---> | Tools   |
+| prompt |      |       |      | + todo  |
++--------+      +---+---+      +----+----+
+                    ^                |
+                    |   tool_result  |
+                    +----------------+
+                          |
+              +-----------+-----------+
+              | TodoManager state     |
+              | [ ] task A            |
+              | [>] task B  <- doing  |
+              | [x] task C            |
+              +-----------------------+
+                          |
+              if rounds_since_todo >= 3:
+                inject <reminder> into tool_result
+```
+
+## 仕組み
+
+1. TodoManagerはアイテムのリストをステータス付きで保持する。`in_progress`にできるのは同時に1つだけ。
+
+```python
+class TodoManager:
+    def update(self, items: list) -> str:
+        validated, in_progress_count = [], 0
+        for item in items:
+            status = item.get("status", "pending")
+            if status == "in_progress":
+                in_progress_count += 1
+            validated.append({"id": item["id"], "text": item["text"],
+                              "status": status})
+        if in_progress_count > 1:
+            raise ValueError("Only one task can be in_progress")
+        self.items = validated
+        return self.render()
+```
+
+2. `todo`ツールは他のツールと同様にディスパッチマップに追加される。
+
+```python
+TOOL_HANDLERS = {
+    # ...base tools...
+    "todo": lambda **kw: TODO.update(kw["items"]),
+}
+```
+
+3. nagリマインダーが、モデルが3ラウンド以上`todo`を呼ばなかった場合にナッジを注入する。
+
+```python
+if rounds_since_todo >= 3 and messages:
+    last = messages[-1]
+    if last["role"] == "user" and isinstance(last.get("content"), list):
+        last["content"].insert(0, {
+            "type": "text",
+            "text": "<reminder>Update your todos.</reminder>",
+        })
+```
+
+「一度にin_progressは1つだけ」の制約が逐次的な集中を強制し、nagリマインダーが説明責任を生む。
+
+## s02からの変更点
+
+| Component      | Before (s02)     | After (s03)                |
+|----------------|------------------|----------------------------|
+| Tools          | 4                | 5 (+todo)                  |
+| Planning       | None             | TodoManager with statuses  |
+| Nag injection  | None             | `<reminder>` after 3 rounds|
+| Agent loop     | Simple dispatch  | + rounds_since_todo counter|
+
+## 試してみる
+
+```sh
+cd learn-claude-code
+python agents/s03_todo_write.py
+```
+
+1. `Refactor the file hello.py: add type hints, docstrings, and a main guard`
+2. `Create a Python package with __init__.py, utils.py, and tests/test_utils.py`
+3. `Review all Python files and fix any style issues`

docs/ja/s04-subagent.md

@@ -0,0 +1,94 @@
+# s04: Subagents
+
+`s01 > s02 > s03 > [ s04 ] s05 > s06 | s07 > s08 > s09 > s10 > s11 > s12`
+
+> *"大きなタスクを分割し、各サブタスクにクリーンなコンテキストを"* -- サブエージェントは独立した messages[] を使い、メイン会話を汚さない。
+>
+> **Harness 層**: コンテキスト隔離 -- モデルの思考の明晰さを守る。
+
+## 問題
+
+エージェントが作業するにつれ、messages配列は膨張し続ける。すべてのファイル読み取り、すべてのbash出力がコンテキストに永久に残る。「このプロジェクトはどのテストフレームワークを使っているか」という質問は5つのファイルを読む必要があるかもしれないが、親に必要なのは「pytest」という答えだけだ。
+
+## 解決策
+
+```
+Parent agent                     Subagent
++------------------+             +------------------+
+| messages=[...]   |             | messages=[]      | <-- fresh
+|                  |  dispatch   |                  |
+| tool: task       | ----------> | while tool_use:  |
+|   prompt="..."   |             |   call tools     |
+|                  |  summary    |   append results |
+|   result = "..." | <---------- | return last text |
++------------------+             +------------------+
+
+Parent context stays clean. Subagent context is discarded.
+```
+
+## 仕組み
+
+1. 親に`task`ツールを追加する。子は`task`を除くすべての基本ツールを取得する(再帰的な生成は不可)。
+
+```python
+PARENT_TOOLS = CHILD_TOOLS + [
+    {"name": "task",
+     "description": "Spawn a subagent with fresh context.",
+     "input_schema": {
+         "type": "object",
+         "properties": {"prompt": {"type": "string"}},
+         "required": ["prompt"],
+     }},
+]
+```
+
+2. サブエージェントは`messages=[]`で開始し、自身のループを実行する。最終テキストだけが親に返る。
+
+```python
+def run_subagent(prompt: str) -> str:
+    sub_messages = [{"role": "user", "content": prompt}]
+    for _ in range(30):  # safety limit
+        response = client.messages.create(
+            model=MODEL, system=SUBAGENT_SYSTEM,
+            messages=sub_messages,
+            tools=CHILD_TOOLS, max_tokens=8000,
+        )
+        sub_messages.append({"role": "assistant",
+                             "content": response.content})
+        if response.stop_reason != "tool_use":
+            break
+        results = []
+        for block in response.content:
+            if block.type == "tool_use":
+                handler = TOOL_HANDLERS.get(block.name)
+                output = handler(**block.input)
+                results.append({"type": "tool_result",
+                    "tool_use_id": block.id,
+                    "content": str(output)[:50000]})
+        sub_messages.append({"role": "user", "content": results})
+    return "".join(
+        b.text for b in response.content if hasattr(b, "text")
+    ) or "(no summary)"
+```
+
+子のメッセージ履歴全体(30回以上のツール呼び出し)は破棄される。親は1段落の要約を通常の`tool_result`として受け取る。
+
+## s03からの変更点
+
+| Component      | Before (s03)     | After (s04)               |
+|----------------|------------------|---------------------------|
+| Tools          | 5                | 5 (base) + task (parent)  |
+| Context        | Single shared    | Parent + child isolation  |
+| Subagent       | None             | `run_subagent()` function |
+| Return value   | N/A              | Summary text only         |
+
+## 試してみる
+
+```sh
+cd learn-claude-code
+python agents/s04_subagent.py
+```
+
+1. `Use a subtask to find what testing framework this project uses`
+2. `Delegate: read all .py files and summarize what each one does`
+3. `Use a task to create a new module, then verify it from here`

docs/ja/s05-skill-loading.md

@@ -0,0 +1,108 @@
+# s05: Skills
+
+`s01 > s02 > s03 > s04 > [ s05 ] s06 | s07 > s08 > s09 > s10 > s11 > s12`
+
+> *"必要な知識を、必要な時に読み込む"* -- system prompt ではなく tool_result で注入。
+>
+> **Harness 層**: オンデマンド知識 -- モデルが求めた時だけ渡すドメイン専門性。
+
+## 問題
+
+エージェントにドメイン固有のワークフローを遵守させたい: gitの規約、テストパターン、コードレビューチェックリスト。すべてをシステムプロンプトに入れると、使われないスキルにトークンを浪費する。10スキル x 2000トークン = 20,000トークン、ほとんどが任意のタスクに無関係だ。
+
+## 解決策
+
+```
+System prompt (Layer 1 -- always present):
++--------------------------------------+
+| You are a coding agent.              |
+| Skills available:                    |
+|   - git: Git workflow helpers        |  ~100 tokens/skill
+|   - test: Testing best practices     |
++--------------------------------------+
+
+When model calls load_skill("git"):
++--------------------------------------+
+| tool_result (Layer 2 -- on demand):  |
+| <skill name="git">                   |
+|   Full git workflow instructions...  |  ~2000 tokens
+|   Step 1: ...                        |
+| </skill>                             |
++--------------------------------------+
+```
+
+第1層: スキル*名*をシステムプロンプトに(低コスト)。第2層: スキル*本体*をtool_resultに(オンデマンド)。
+
+## 仕組み
+
+1. 各スキルは `SKILL.md` ファイルを含むディレクトリとして配置される。
+
+```
+skills/
+  pdf/
+    SKILL.md       # ---\n name: pdf\n description: Process PDF files\n ---\n ...
+  code-review/
+    SKILL.md       # ---\n name: code-review\n description: Review code\n ---\n ...
+```
+
+2. SkillLoaderが `SKILL.md` を再帰的に探索し、ディレクトリ名をスキル識別子として使用する。
+
+```python
+class SkillLoader:
+    def __init__(self, skills_dir: Path):
+        self.skills = {}
+        for f in sorted(skills_dir.rglob("SKILL.md")):
+            text = f.read_text()
+            meta, body = self._parse_frontmatter(text)
+            name = meta.get("name", f.parent.name)
+            self.skills[name] = {"meta": meta, "body": body}
+
+    def get_descriptions(self) -> str:
+        lines = []
+        for name, skill in self.skills.items():
+            desc = skill["meta"].get("description", "")
+            lines.append(f"  - {name}: {desc}")
+        return "\n".join(lines)
+
+    def get_content(self, name: str) -> str:
+        skill = self.skills.get(name)
+        if not skill:
+            return f"Error: Unknown skill '{name}'."
+        return f"<skill name=\"{name}\">\n{skill['body']}\n</skill>"
+```
+
+3. 第1層はシステムプロンプトに配置。第2層は通常のツールハンドラ。
+
+```python
+SYSTEM = f"""You are a coding agent at {WORKDIR}.
+Skills available:
+{SKILL_LOADER.get_descriptions()}"""
+
+TOOL_HANDLERS = {
+    # ...base tools...
+    "load_skill": lambda **kw: SKILL_LOADER.get_content(kw["name"]),
+}
+```
+
+モデルはどのスキルが存在するかを知り(低コスト)、関連する時にだけ読み込む(高コスト)。
+
+## s04からの変更点
+
+| Component      | Before (s04)     | After (s05)                |
+|----------------|------------------|----------------------------|
+| Tools          | 5 (base + task)  | 5 (base + load_skill)      |
+| System prompt  | Static string    | + skill descriptions       |
+| Knowledge      | None             | skills/\*/SKILL.md files   |
+| Injection      | None             | Two-layer (system + result)|
+
+## 試してみる
+
+```sh
+cd learn-claude-code
+python agents/s05_skill_loading.py
+```
+
+1. `What skills are available?`
+2. `Load the agent-builder skill and follow its instructions`
+3. `I need to do a code review -- load the relevant skill first`
+4. `Build an MCP server using the mcp-builder skill`

docs/ja/s06-context-compact.md

@@ -0,0 +1,124 @@
+# s06: Context Compact
+
+`s01 > s02 > s03 > s04 > s05 > [ s06 ] | s07 > s08 > s09 > s10 > s11 > s12`
+
+> *"コンテキストはいつか溢れる、空ける手段が要る"* -- 3層圧縮で無限セッションを実現。
+>
+> **Harness 層**: 圧縮 -- クリーンな記憶、無限のセッション。
+
+## 問題
+
+コンテキストウィンドウは有限だ。1000行のファイルに対する`read_file`1回で約4000トークンを消費する。30ファイルを読み20回のbashコマンドを実行すると、100,000トークン超。圧縮なしでは、エージェントは大規模コードベースで作業できない。
+
+## 解決策
+
+積極性を段階的に上げる3層構成:
+
+```
+Every turn:
++------------------+
+| Tool call result |
++------------------+
+        |
+        v
+[Layer 1: micro_compact]        (silent, every turn)
+  Replace tool_result > 3 turns old
+  with "[Previous: used {tool_name}]"
+        |
+        v
+[Check: tokens > 50000?]
+   |               |
+   no              yes
+   |               |
+   v               v
+continue    [Layer 2: auto_compact]
+              Save transcript to .transcripts/
+              LLM summarizes conversation.
+              Replace all messages with [summary].
+                    |
+                    v
+            [Layer 3: compact tool]
+              Model calls compact explicitly.
+              Same summarization as auto_compact.
+```
+
+## 仕組み
+
+1. **第1層 -- micro_compact**: 各LLM呼び出しの前に、古いツール結果をプレースホルダーに置換する。
+
+```python
+def micro_compact(messages: list) -> list:
+    tool_results = []
+    for i, msg in enumerate(messages):
+        if msg["role"] == "user" and isinstance(msg.get("content"), list):
+            for j, part in enumerate(msg["content"]):
+                if isinstance(part, dict) and part.get("type") == "tool_result":
+                    tool_results.append((i, j, part))
+    if len(tool_results) <= KEEP_RECENT:
+        return messages
+    for _, _, part in tool_results[:-KEEP_RECENT]:
+        if len(part.get("content", "")) > 100:
+            part["content"] = f"[Previous: used {tool_name}]"
+    return messages
+```
+
+2. **第2層 -- auto_compact**: トークンが閾値を超えたら、完全なトランスクリプトをディスクに保存し、LLMに要約を依頼する。
+
+```python
+def auto_compact(messages: list) -> list:
+    # Save transcript for recovery
+    transcript_path = TRANSCRIPT_DIR / f"transcript_{int(time.time())}.jsonl"
+    with open(transcript_path, "w") as f:
+        for msg in messages:
+            f.write(json.dumps(msg, default=str) + "\n")
+    # LLM summarizes
+    response = client.messages.create(
+        model=MODEL,
+        messages=[{"role": "user", "content":
+            "Summarize this conversation for continuity..."
+            + json.dumps(messages, default=str)[:80000]}],
+        max_tokens=2000,
+    )
+    return [
+        {"role": "user", "content": f"[Compressed]\n\n{response.content[0].text}"},
+    ]
+```
+
+3. **第3層 -- manual compact**: `compact`ツールが同じ要約処理をオンデマンドでトリガーする。
+
+4. ループが3層すべてを統合する:
+
+```python
+def agent_loop(messages: list):
+    while True:
+        micro_compact(messages)                        # Layer 1
+        if estimate_tokens(messages) > THRESHOLD:
+            messages[:] = auto_compact(messages)       # Layer 2
+        response = client.messages.create(...)
+        # ... tool execution ...
+        if manual_compact:
+            messages[:] = auto_compact(messages)       # Layer 3
+```
+
+トランスクリプトがディスク上に完全な履歴を保持する。何も真に失われず、アクティブなコンテキストの外に移動されるだけ。
+
+## s05からの変更点
+
+| Component      | Before (s05)     | After (s06)                |
+|----------------|------------------|----------------------------|
+| Tools          | 5                | 5 (base + compact)         |
+| Context mgmt   | None             | Three-layer compression    |
+| Micro-compact  | None             | Old results -> placeholders|
+| Auto-compact   | None             | Token threshold trigger    |
+| Transcripts    | None             | Saved to .transcripts/     |
+
+## 試してみる
+
+```sh
+cd learn-claude-code
+python agents/s06_context_compact.py
+```
+
+1. `Read every Python file in the agents/ directory one by one` (micro-compactが古い結果を置換するのを観察する)
+2. `Keep reading files until compression triggers automatically`
+3. `Use the compact tool to manually compress the conversation`

docs/ja/s07-task-system.md

@@ -0,0 +1,131 @@
+# s07: Task System
+
+`s01 > s02 > s03 > s04 > s05 > s06 | [ s07 ] s08 > s09 > s10 > s11 > s12`
+
+> *"大きな目標を小タスクに分解し、順序付けし、ディスクに記録する"* -- ファイルベースのタスクグラフ、マルチエージェント協調の基盤。
+>
+> **Harness 層**: 永続タスク -- どの会話よりも長く生きる目標。
+
+## 問題
+
+s03のTodoManagerはメモリ上のフラットなチェックリストに過ぎない: 順序なし、依存関係なし、ステータスは完了か未完了のみ。実際の目標には構造がある -- タスクBはタスクAに依存し、タスクCとDは並行実行でき、タスクEはCとDの両方を待つ。
+
+明示的な関係がなければ、エージェントは何が実行可能で、何がブロックされ、何が同時に走れるかを判断できない。しかもリストはメモリ上にしかないため、コンテキスト圧縮(s06)で消える。
+
+## 解決策
+
+フラットなチェックリストをディスクに永続化する**タスクグラフ**に昇格させる。各タスクは1つのJSONファイルで、ステータス・前方依存(`blockedBy`)を持つ。タスクグラフは常に3つの問いに答える:
+
+- **何が実行可能か?** -- `pending`ステータスで`blockedBy`が空のタスク。
+- **何がブロックされているか?** -- 未完了の依存を待つタスク。
+- **何が完了したか?** -- `completed`のタスク。完了時に後続タスクを自動的にアンブロックする。
+
+```
+.tasks/
+  task_1.json  {"id":1, "status":"completed"}
+  task_2.json  {"id":2, "blockedBy":[1], "status":"pending"}
+  task_3.json  {"id":3, "blockedBy":[1], "status":"pending"}
+  task_4.json  {"id":4, "blockedBy":[2,3], "status":"pending"}
+
+タスクグラフ (DAG):
+                 +----------+
+            +--> | task 2   | --+
+            |    | pending  |   |
++----------+     +----------+    +--> +----------+
+| task 1   |                          | task 4   |
+| completed| --> +----------+    +--> | blocked  |
++----------+     | task 3   | --+     +----------+
+                 | pending  |
+                 +----------+
+
+順序:       task 1 は 2 と 3 より先に完了する必要がある
+並行:       task 2 と 3 は同時に実行できる
+依存:       task 4 は 2 と 3 の両方を待つ
+ステータス: pending -> in_progress -> completed
+```
+
+このタスクグラフは s07 以降の全メカニズムの協調バックボーンとなる: バックグラウンド実行(s08)、マルチエージェントチーム(s09+)、worktree分離(s12)はすべてこの同じ構造を読み書きする。
+
+## 仕組み
+
+1. **TaskManager**: タスクごとに1つのJSONファイル、依存グラフ付きCRUD。
+
+```python
+class TaskManager:
+    def __init__(self, tasks_dir: Path):
+        self.dir = tasks_dir
+        self.dir.mkdir(exist_ok=True)
+        self._next_id = self._max_id() + 1
+
+    def create(self, subject, description=""):
+        task = {"id": self._next_id, "subject": subject,
+                "status": "pending", "blockedBy": [],
+                "owner": ""}
+        self._save(task)
+        self._next_id += 1
+        return json.dumps(task, indent=2)
+```
+
+2. **依存解除**: タスク完了時に、他タスクの`blockedBy`リストから完了IDを除去し、後続タスクをアンブロックする。
+
+```python
+def _clear_dependency(self, completed_id):
+    for f in self.dir.glob("task_*.json"):
+        task = json.loads(f.read_text())
+        if completed_id in task.get("blockedBy", []):
+            task["blockedBy"].remove(completed_id)
+            self._save(task)
+```
+
+3. **ステータス遷移 + 依存配線**: `update`がステータス変更と依存エッジを担う。
+
+```python
+def update(self, task_id, status=None,
+           add_blocked_by=None, remove_blocked_by=None):
+    task = self._load(task_id)
+    if status:
+        task["status"] = status
+        if status == "completed":
+            self._clear_dependency(task_id)
+    if add_blocked_by:
+        task["blockedBy"] = list(set(task["blockedBy"] + add_blocked_by))
+    if remove_blocked_by:
+        task["blockedBy"] = [x for x in task["blockedBy"] if x not in remove_blocked_by]
+    self._save(task)
+```
+
+4. 4つのタスクツールをディスパッチマップに追加する。
+
+```python
+TOOL_HANDLERS = {
+    # ...base tools...
+    "task_create": lambda **kw: TASKS.create(kw["subject"]),
+    "task_update": lambda **kw: TASKS.update(kw["task_id"], kw.get("status")),
+    "task_list":   lambda **kw: TASKS.list_all(),
+    "task_get":    lambda **kw: TASKS.get(kw["task_id"]),
+}
+```
+
+s07以降、タスクグラフがマルチステップ作業のデフォルト。s03のTodoは軽量な単一セッション用チェックリストとして残る。
+
+## s06からの変更点
+
+| コンポーネント | Before (s06) | After (s07) |
+|---|---|---|
+| Tools | 5 | 8 (`task_create/update/list/get`) |
+| 計画モデル | フラットチェックリスト (メモリ) | 依存関係付きタスクグラフ (ディスク) |
+| 関係 | なし | `blockedBy` エッジ |
+| ステータス追跡 | 完了か未完了 | `pending` -> `in_progress` -> `completed` |
+| 永続性 | 圧縮で消失 | 圧縮・再起動後も存続 |
+
+## 試してみる
+
+```sh
+cd learn-claude-code
+python agents/s07_task_system.py
+```
+
+1. `Create 3 tasks: "Setup project", "Write code", "Write tests". Make them depend on each other in order.`
+2. `List all tasks and show the dependency graph`
+3. `Complete task 1 and then list tasks to see task 2 unblocked`
+4. `Create a task board for refactoring: parse -> transform -> emit -> test, where transform and emit can run in parallel after parse`

docs/ja/s08-background-tasks.md

@@ -0,0 +1,107 @@
+# s08: Background Tasks
+
+`s01 > s02 > s03 > s04 > s05 > s06 | s07 > [ s08 ] s09 > s10 > s11 > s12`
+
+> *"遅い操作はバックグラウンドへ、エージェントは次を考え続ける"* -- デーモンスレッドがコマンド実行、完了後に通知を注入。
+>
+> **Harness 層**: バックグラウンド実行 -- モデルが考え続ける間、Harness が待つ。
+
+## 問題
+
+一部のコマンドは数分かかる: `npm install`、`pytest`、`docker build`。ブロッキングループでは、モデルはサブプロセスの完了を待って座っている。ユーザーが「依存関係をインストールして、その間にconfigファイルを作って」と言っても、エージェントは並列ではなく逐次的に処理する。
+
+## 解決策
+
+```
+Main thread                Background thread
++-----------------+        +-----------------+
+| agent loop      |        | subprocess runs |
+| ...             |        | ...             |
+| [LLM call] <---+------- | enqueue(result) |
+|  ^drain queue   |        +-----------------+
++-----------------+
+
+Timeline:
+Agent --[spawn A]--[spawn B]--[other work]----
+             |          |
+             v          v
+          [A runs]   [B runs]      (parallel)
+             |          |
+             +-- results injected before next LLM call --+
+```
+
+## 仕組み
+
+1. BackgroundManagerがスレッドセーフな通知キューでタスクを追跡する。
+
+```python
+class BackgroundManager:
+    def __init__(self):
+        self.tasks = {}
+        self._notification_queue = []
+        self._lock = threading.Lock()
+```
+
+2. `run()`がデーモンスレッドを開始し、即座にリターンする。
+
+```python
+def run(self, command: str) -> str:
+    task_id = str(uuid.uuid4())[:8]
+    self.tasks[task_id] = {"status": "running", "command": command}
+    thread = threading.Thread(
+        target=self._execute, args=(task_id, command), daemon=True)
+    thread.start()
+    return f"Background task {task_id} started"
+```
+
+3. サブプロセス完了時に、結果を通知キューへ。
+
+```python
+def _execute(self, task_id, command):
+    try:
+        r = subprocess.run(command, shell=True, cwd=WORKDIR,
+            capture_output=True, text=True, timeout=300)
+        output = (r.stdout + r.stderr).strip()[:50000]
+    except subprocess.TimeoutExpired:
+        output = "Error: Timeout (300s)"
+    with self._lock:
+        self._notification_queue.append({
+            "task_id": task_id, "result": output[:500]})
+```
+
+4. エージェントループが各LLM呼び出しの前に通知をドレインする。
+
+```python
+def agent_loop(messages: list):
+    while True:
+        notifs = BG.drain_notifications()
+        if notifs:
+            notif_text = "\n".join(
+                f"[bg:{n['task_id']}] {n['result']}" for n in notifs)
+            messages.append({"role": "user",
+                "content": f"<background-results>\n{notif_text}\n"
+                           f"</background-results>"})
+        response = client.messages.create(...)
+```
+
+ループはシングルスレッドのまま。サブプロセスI/Oだけが並列化される。
+
+## s07からの変更点
+
+| Component      | Before (s07)     | After (s08)                |
+|----------------|------------------|----------------------------|
+| Tools          | 8                | 6 (base + background_run + check)|
+| Execution      | Blocking only    | Blocking + background threads|
+| Notification   | None             | Queue drained per loop     |
+| Concurrency    | None             | Daemon threads             |
+
+## 試してみる
+
+```sh
+cd learn-claude-code
+python agents/s08_background_tasks.py
+```
+
+1. `Run "sleep 5 && echo done" in the background, then create a file while it runs`
+2. `Start 3 background tasks: "sleep 2", "sleep 4", "sleep 6". Check their status.`
+3. `Run pytest in the background and keep working on other things`

docs/ja/s09-agent-teams.md

@@ -0,0 +1,125 @@
+# s09: Agent Teams
+
+`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > [ s09 ] s10 > s11 > s12`
+
+> *"一人で終わらないなら、チームメイトに任せる"* -- 永続チームメイト + 非同期メールボックス。
+>
+> **Harness 層**: チームメールボックス -- 複数モデルをファイルで協調。
+
+## 問題
+
+サブエージェント(s04)は使い捨てだ: 生成し、作業し、要約を返し、消滅する。アイデンティティもなく、呼び出し間の記憶もない。バックグラウンドタスク(s08)はシェルコマンドを実行するが、LLM誘導の意思決定はできない。
+
+本物のチームワークには: (1)単一プロンプトを超えて存続する永続エージェント、(2)アイデンティティとライフサイクル管理、(3)エージェント間の通信チャネルが必要だ。
+
+## 解決策
+
+```
+Teammate lifecycle:
+  spawn -> WORKING -> IDLE -> WORKING -> ... -> SHUTDOWN
+
+Communication:
+  .team/
+    config.json           <- team roster + statuses
+    inbox/
+      alice.jsonl         <- append-only, drain-on-read
+      bob.jsonl
+      lead.jsonl
+
+              +--------+    send("alice","bob","...")    +--------+
+              | alice  | -----------------------------> |  bob   |
+              | loop   |    bob.jsonl << {json_line}    |  loop  |
+              +--------+                                +--------+
+                   ^                                         |
+                   |        BUS.read_inbox("alice")          |
+                   +---- alice.jsonl -> read + drain ---------+
+```
+
+## 仕組み
+
+1. TeammateManagerがconfig.jsonでチーム名簿を管理する。
+
+```python
+class TeammateManager:
+    def __init__(self, team_dir: Path):
+        self.dir = team_dir
+        self.dir.mkdir(exist_ok=True)
+        self.config_path = self.dir / "config.json"
+        self.config = self._load_config()
+        self.threads = {}
+```
+
+2. `spawn()`がチームメイトを作成し、そのエージェントループをスレッドで開始する。
+
+```python
+def spawn(self, name: str, role: str, prompt: str) -> str:
+    member = {"name": name, "role": role, "status": "working"}
+    self.config["members"].append(member)
+    self._save_config()
+    thread = threading.Thread(
+        target=self._teammate_loop,
+        args=(name, role, prompt), daemon=True)
+    thread.start()
+    return f"Spawned teammate '{name}' (role: {role})"
+```
+
+3. MessageBus: 追記専用のJSONLインボックス。`send()`がJSON行を追記し、`read_inbox()`がすべて読み取ってドレインする。
+
+```python
+class MessageBus:
+    def send(self, sender, to, content, msg_type="message", extra=None):
+        msg = {"type": msg_type, "from": sender,
+               "content": content, "timestamp": time.time()}
+        if extra:
+            msg.update(extra)
+        with open(self.dir / f"{to}.jsonl", "a") as f:
+            f.write(json.dumps(msg) + "\n")
+
+    def read_inbox(self, name):
+        path = self.dir / f"{name}.jsonl"
+        if not path.exists(): return "[]"
+        msgs = [json.loads(l) for l in path.read_text().strip().splitlines() if l]
+        path.write_text("")  # drain
+        return json.dumps(msgs, indent=2)
+```
+
+4. 各チームメイトは各LLM呼び出しの前にインボックスを確認し、受信メッセージをコンテキストに注入する。
+
+```python
+def _teammate_loop(self, name, role, prompt):
+    messages = [{"role": "user", "content": prompt}]
+    for _ in range(50):
+        inbox = BUS.read_inbox(name)
+        if inbox != "[]":
+            messages.append({"role": "user",
+                "content": f"<inbox>{inbox}</inbox>"})
+        response = client.messages.create(...)
+        if response.stop_reason != "tool_use":
+            break
+        # execute tools, append results...
+    self._find_member(name)["status"] = "idle"
+```
+
+## s08からの変更点
+
+| Component      | Before (s08)     | After (s09)                |
+|----------------|------------------|----------------------------|
+| Tools          | 6                | 9 (+spawn/send/read_inbox) |
+| Agents         | Single           | Lead + N teammates         |
+| Persistence    | None             | config.json + JSONL inboxes|
+| Threads        | Background cmds  | Full agent loops per thread|
+| Lifecycle      | Fire-and-forget  | idle -> working -> idle    |
+| Communication  | None             | message + broadcast        |
+
+## 試してみる
+
+```sh
+cd learn-claude-code
+python agents/s09_agent_teams.py
+```
+
+1. `Spawn alice (coder) and bob (tester). Have alice send bob a message.`
+2. `Broadcast "status update: phase 1 complete" to all teammates`
+3. `Check the lead inbox for any messages`
+4. `/team`と入力してステータス付きのチーム名簿を確認する
+5. `/inbox`と入力してリーダーのインボックスを手動確認する

docs/ja/s10-team-protocols.md

@@ -0,0 +1,106 @@
+# s10: Team Protocols
+
+`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > [ s10 ] s11 > s12`
+
+> *"チームメイト間には統一の通信ルールが必要"* -- 1つの request-response パターンが全交渉を駆動。
+>
+> **Harness 層**: プロトコル -- モデル間の構造化されたハンドシェイク。
+
+## 問題
+
+s09ではチームメイトが作業し通信するが、構造化された協調がない:
+
+**シャットダウン**: スレッドを強制終了するとファイルが中途半端に書かれ、config.jsonが不正な状態になる。ハンドシェイクが必要 -- リーダーが要求し、チームメイトが承認(完了して退出)か拒否(作業継続)する。
+
+**プラン承認**: リーダーが「認証モジュールをリファクタリングして」と言うと、チームメイトは即座に開始する。リスクの高い変更では、実行前にリーダーが計画をレビューすべきだ。
+
+両方とも同じ構造: 一方がユニークIDを持つリクエストを送り、他方がそのIDで応答する。
+
+## 解決策
+
+```
+Shutdown Protocol            Plan Approval Protocol
+==================           ======================
+
+Lead             Teammate    Teammate           Lead
+  |                 |           |                 |
+  |--shutdown_req-->|           |--plan_req------>|
+  | {req_id:"abc"}  |           | {req_id:"xyz"}  |
+  |                 |           |                 |
+  |<--shutdown_resp-|           |<--plan_resp-----|
+  | {req_id:"abc",  |           | {req_id:"xyz",  |
+  |  approve:true}  |           |  approve:true}  |
+
+Shared FSM:
+  [pending] --approve--> [approved]
+  [pending] --reject---> [rejected]
+
+Trackers:
+  shutdown_requests = {req_id: {target, status}}
+  plan_requests     = {req_id: {from, plan, status}}
+```
+
+## 仕組み
+
+1. リーダーがrequest_idを生成し、インボックス経由でシャットダウンを開始する。
+
+```python
+shutdown_requests = {}
+
+def handle_shutdown_request(teammate: str) -> str:
+    req_id = str(uuid.uuid4())[:8]
+    shutdown_requests[req_id] = {"target": teammate, "status": "pending"}
+    BUS.send("lead", teammate, "Please shut down gracefully.",
+             "shutdown_request", {"request_id": req_id})
+    return f"Shutdown request {req_id} sent (status: pending)"
+```
+
+2. チームメイトがリクエストを受信し、承認または拒否で応答する。
+
+```python
+if tool_name == "shutdown_response":
+    req_id = args["request_id"]
+    approve = args["approve"]
+    shutdown_requests[req_id]["status"] = "approved" if approve else "rejected"
+    BUS.send(sender, "lead", args.get("reason", ""),
+             "shutdown_response",
+             {"request_id": req_id, "approve": approve})
+```
+
+3. プラン承認も同一パターン。チームメイトがプランを提出(request_idを生成)、リーダーがレビュー(同じrequest_idを参照)。
+
+```python
+plan_requests = {}
+
+def handle_plan_review(request_id, approve, feedback=""):
+    req = plan_requests[request_id]
+    req["status"] = "approved" if approve else "rejected"
+    BUS.send("lead", req["from"], feedback,
+             "plan_approval_response",
+             {"request_id": request_id, "approve": approve})
+```
+
+1つのFSM、2つの応用。同じ`pending -> approved | rejected`状態機械が、あらゆるリクエスト-レスポンスプロトコルに適用できる。
+
+## s09からの変更点
+
+| Component      | Before (s09)     | After (s10)                  |
+|----------------|------------------|------------------------------|
+| Tools          | 9                | 12 (+shutdown_req/resp +plan)|
+| Shutdown       | Natural exit only| Request-response handshake   |
+| Plan gating    | None             | Submit/review with approval  |
+| Correlation    | None             | request_id per request       |
+| FSM            | None             | pending -> approved/rejected |
+
+## 試してみる
+
+```sh
+cd learn-claude-code
+python agents/s10_team_protocols.py
+```
+
+1. `Spawn alice as a coder. Then request her shutdown.`
+2. `List teammates to see alice's status after shutdown approval`
+3. `Spawn bob with a risky refactoring task. Review and reject his plan.`
+4. `Spawn charlie, have him submit a plan, then approve it.`
+5. `/team`と入力してステータスを監視する

docs/ja/s11-autonomous-agents.md

@@ -0,0 +1,142 @@
+# s11: Autonomous Agents
+
+`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > [ s11 ] s12`
+
+> *"チームメイトが自らボードを見て、仕事を取る"* -- リーダーが逐一割り振る必要はない。
+>
+> **Harness 層**: 自律 -- 指示なしで仕事を見つけるモデル。
+
+## 問題
+
+s09-s10では、チームメイトは明示的に指示された時のみ作業する。リーダーは各チームメイトを特定のプロンプトでspawnしなければならない。タスクボードに未割り当てのタスクが10個あっても、リーダーが手動で各タスクを割り当てる。これはスケールしない。
+
+真の自律性とは、チームメイトが自分で作業を見つけること: タスクボードをスキャンし、未確保のタスクを確保し、作業し、完了したら次を探す。
+
+もう1つの問題: コンテキスト圧縮(s06)後にエージェントが自分の正体を忘れる可能性がある。アイデンティティ再注入がこれを解決する。
+
+## 解決策
+
+```
+Teammate lifecycle with idle cycle:
+
++-------+
+| spawn |
++---+---+
+    |
+    v
++-------+   tool_use     +-------+
+| WORK  | <------------- |  LLM  |
++---+---+                +-------+
+    |
+    | stop_reason != tool_use (or idle tool called)
+    v
++--------+
+|  IDLE  |  poll every 5s for up to 60s
++---+----+
+    |
+    +---> check inbox --> message? ----------> WORK
+    |
+    +---> scan .tasks/ --> unclaimed? -------> claim -> WORK
+    |
+    +---> 60s timeout ----------------------> SHUTDOWN
+
+Identity re-injection after compression:
+  if len(messages) <= 3:
+    messages.insert(0, identity_block)
+```
+
+## 仕組み
+
+1. チームメイトのループはWORKとIDLEの2フェーズ。LLMがツール呼び出しを止めた時(または`idle`ツールを呼んだ時)、IDLEフェーズに入る。
+
+```python
+def _loop(self, name, role, prompt):
+    while True:
+        # -- WORK PHASE --
+        messages = [{"role": "user", "content": prompt}]
+        for _ in range(50):
+            response = client.messages.create(...)
+            if response.stop_reason != "tool_use":
+                break
+            # execute tools...
+            if idle_requested:
+                break
+
+        # -- IDLE PHASE --
+        self._set_status(name, "idle")
+        resume = self._idle_poll(name, messages)
+        if not resume:
+            self._set_status(name, "shutdown")
+            return
+        self._set_status(name, "working")
+```
+
+2. IDLEフェーズがインボックスとタスクボードをポーリングする。
+
+```python
+def _idle_poll(self, name, messages):
+    for _ in range(IDLE_TIMEOUT // POLL_INTERVAL):  # 60s / 5s = 12
+        time.sleep(POLL_INTERVAL)
+        inbox = BUS.read_inbox(name)
+        if inbox:
+            messages.append({"role": "user",
+                "content": f"<inbox>{inbox}</inbox>"})
+            return True
+        unclaimed = scan_unclaimed_tasks()
+        if unclaimed:
+            claim_task(unclaimed[0]["id"], name)
+            messages.append({"role": "user",
+                "content": f"<auto-claimed>Task #{unclaimed[0]['id']}: "
+                           f"{unclaimed[0]['subject']}</auto-claimed>"})
+            return True
+    return False  # timeout -> shutdown
+```
+
+3. タスクボードスキャン: pendingかつ未割り当てかつブロックされていないタスクを探す。
+
+```python
+def scan_unclaimed_tasks() -> list:
+    unclaimed = []
+    for f in sorted(TASKS_DIR.glob("task_*.json")):
+        task = json.loads(f.read_text())
+        if (task.get("status") == "pending"
+                and not task.get("owner")
+                and not task.get("blockedBy")):
+            unclaimed.append(task)
+    return unclaimed
+```
+
+4. アイデンティティ再注入: コンテキストが短すぎる(圧縮が起きた)場合にアイデンティティブロックを挿入する。
+
+```python
+if len(messages) <= 3:
+    messages.insert(0, {"role": "user",
+        "content": f"<identity>You are '{name}', role: {role}, "
+                   f"team: {team_name}. Continue your work.</identity>"})
+    messages.insert(1, {"role": "assistant",
+        "content": f"I am {name}. Continuing."})
+```
+
+## s10からの変更点
+
+| Component      | Before (s10)     | After (s11)                |
+|----------------|------------------|----------------------------|
+| Tools          | 12               | 14 (+idle, +claim_task)    |
+| Autonomy       | Lead-directed    | Self-organizing            |
+| Idle phase     | None             | Poll inbox + task board    |
+| Task claiming  | Manual only      | Auto-claim unclaimed tasks |
+| Identity       | System prompt    | + re-injection after compress|
+| Timeout        | None             | 60s idle -> auto shutdown  |
+
+## 試してみる
+
+```sh
+cd learn-claude-code
+python agents/s11_autonomous_agents.py
+```
+
+1. `Create 3 tasks on the board, then spawn alice and bob. Watch them auto-claim.`
+2. `Spawn a coder teammate and let it find work from the task board itself`
+3. `Create tasks with dependencies. Watch teammates respect the blocked order.`
+4. `/tasks`と入力してオーナー付きのタスクボードを確認する
+5. `/team`と入力して誰が作業中でアイドルかを監視する

docs/ja/s12-worktree-task-isolation.md

@@ -0,0 +1,121 @@
+# s12: Worktree + Task Isolation
+
+`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]`
+
+> *"各自のディレクトリで作業し、互いに干渉しない"* -- タスクは目標を管理、worktree はディレクトリを管理、IDで紐付け。
+>
+> **Harness 層**: ディレクトリ隔離 -- 決して衝突しない並列実行レーン。
+
+## 問題
+
+s11までにエージェントはタスクを自律的に確保して完了できるようになった。しかし全タスクが1つの共有ディレクトリで走る。2つのエージェントが同時に異なるモジュールをリファクタリングすると衝突する: 片方が`config.py`を編集し、もう片方も`config.py`を編集し、未コミットの変更が混ざり合い、どちらもクリーンにロールバックできない。
+
+タスクボードは*何をやるか*を追跡するが、*どこでやるか*には関知しない。解決策: 各タスクに専用のgit worktreeディレクトリを与える。タスクが目標を管理し、worktreeが実行コンテキストを管理する。タスクIDで紐付ける。
+
+## 解決策
+
+```
+Control plane (.tasks/)             Execution plane (.worktrees/)
++------------------+                +------------------------+
+| task_1.json      |                | auth-refactor/         |
+|   status: in_progress  <------>   branch: wt/auth-refactor
+|   worktree: "auth-refactor"   |   task_id: 1             |
++------------------+                +------------------------+
+| task_2.json      |                | ui-login/              |
+|   status: pending    <------>     branch: wt/ui-login
+|   worktree: "ui-login"       |   task_id: 2             |
++------------------+                +------------------------+
+                                    |
+                          index.json (worktree registry)
+                          events.jsonl (lifecycle log)
+
+State machines:
+  Task:     pending -> in_progress -> completed
+  Worktree: absent  -> active      -> removed | kept
+```
+
+## 仕組み
+
+1. **タスクを作成する。** まず目標を永続化する。
+
+```python
+TASKS.create("Implement auth refactor")
+# -> .tasks/task_1.json  status=pending  worktree=""
+```
+
+2. **worktreeを作成してタスクに紐付ける。** `task_id`を渡すと、タスクが自動的に`in_progress`に遷移する。
+
+```python
+WORKTREES.create("auth-refactor", task_id=1)
+# -> git worktree add -b wt/auth-refactor .worktrees/auth-refactor HEAD
+# -> index.json gets new entry, task_1.json gets worktree="auth-refactor"
+```
+
+紐付けは両側に状態を書き込む:
+
+```python
+def bind_worktree(self, task_id, worktree):
+    task = self._load(task_id)
+    task["worktree"] = worktree
+    if task["status"] == "pending":
+        task["status"] = "in_progress"
+    self._save(task)
+```
+
+3. **worktree内でコマンドを実行する。** `cwd`が分離ディレクトリを指す。
+
+```python
+subprocess.run(command, shell=True, cwd=worktree_path,
+               capture_output=True, text=True, timeout=300)
+```
+
+4. **終了処理。** 2つの選択肢:
+   - `worktree_keep(name)` -- ディレクトリを保持する。
+   - `worktree_remove(name, complete_task=True)` -- ディレクトリを削除し、紐付けられたタスクを完了し、イベントを発行する。1回の呼び出しで後片付けと完了を処理する。
+
+```python
+def remove(self, name, force=False, complete_task=False):
+    self._run_git(["worktree", "remove", wt["path"]])
+    if complete_task and wt.get("task_id") is not None:
+        self.tasks.update(wt["task_id"], status="completed")
+        self.tasks.unbind_worktree(wt["task_id"])
+        self.events.emit("task.completed", ...)
+```
+
+5. **イベントストリーム。** ライフサイクルの各ステップが`.worktrees/events.jsonl`に記録される:
+
+```json
+{
+  "event": "worktree.remove.after",
+  "task": {"id": 1, "status": "completed"},
+  "worktree": {"name": "auth-refactor", "status": "removed"},
+  "ts": 1730000000
+}
+```
+
+発行されるイベント: `worktree.create.before/after/failed`, `worktree.remove.before/after/failed`, `worktree.keep`, `task.completed`。
+
+クラッシュ後も`.tasks/` + `.worktrees/index.json`から状態を再構築できる。会話メモリは揮発性だが、ファイル状態は永続的だ。
+
+## s11からの変更点
+
+| Component          | Before (s11)               | After (s12)                                  |
+|--------------------|----------------------------|----------------------------------------------|
+| Coordination       | Task board (owner/status)  | Task board + explicit worktree binding       |
+| Execution scope    | Shared directory           | Task-scoped isolated directory               |
+| Recoverability     | Task status only           | Task status + worktree index                 |
+| Teardown           | Task completion            | Task completion + explicit keep/remove       |
+| Lifecycle visibility | Implicit in logs         | Explicit events in `.worktrees/events.jsonl` |
+
+## 試してみる
+
+```sh
+cd learn-claude-code
+python agents/s12_worktree_task_isolation.py
+```
+
+1. `Create tasks for backend auth and frontend login page, then list tasks.`
+2. `Create worktree "auth-refactor" for task 1, then bind task 2 to a new worktree "ui-login".`
+3. `Run "git status --short" in worktree "auth-refactor".`
+4. `Keep worktree "ui-login", then list worktrees and inspect events.`
+5. `Remove worktree "auth-refactor" with complete_task=true, then list tasks/worktrees/events.`