analysis_claude_code/web/src/data/generated/docs.json

[
  {
    "version": "s01",
    "locale": "en",
    "title": "s01: The Agent Loop — One Loop Is All You Need",
    "content": "# s01: The Agent Loop — One Loop Is All You Need\n\n`s01` → [s02](/en/s02) → s03 → s04 → ... → s20 → s21\n> *\"One loop & Bash is all you need\"* — One tool + one loop = one Agent.\n>\n> **Harness Layer**: The Loop — the first bridge between the model and the real world.\n\n---\n\n## The Problem\n\nYou ask the model: \"List the files in my directory and run XXX.py.\"\n\nThe model can output a bash command, but once it's done outputting, it stops — it won't execute the command on its own, and it won't keep reasoning based on the result.\n\nYou could run it manually, paste the output back into the chat, and let it continue. Next command comes out, you run it again, paste it back.\n\nEvery round-trip, you're the middle layer. Automating that is what this chapter is about.\n\n---\n\n## The Solution\n\n![Agent Loop](/course-assets/s01_agent_loop/agent-loop.en.svg)\n\nA `while True` loop: keep going when the model calls a tool, stop when it doesn't. The entire process hinges on two signals:\n\n| Signal | Meaning | Loop Action |\n|--------|---------|-------------|\n| `stop_reason == \"tool_use\"` | Model raises hand: \"I need a tool\" | Execute → feed result back → continue |\n| `stop_reason != \"tool_use\"` | Model says: \"I'm done\" | Exit loop |\n\n---\n\n## How It Works\n\nLet's translate this process into code. Step by step:\n\n**Step 1**: Start with the user's question as the first message.\n\n```python\nmessages = [{\"role\": \"user\", \"content\": query}]\n```\n\n**Step 2**: Send the messages and tool definitions to the LLM.\n\n```python\nresponse = client.messages.create(\n    model=MODEL, system=SYSTEM, messages=messages,\n    tools=TOOLS, max_tokens=8000,\n)\n```\n\n**Step 3**: Append the model's response and check whether it called a tool. No tool call → done.\n\n```python\nmessages.append({\"role\": \"assistant\", \"content\": response.content})\nif response.stop_reason != \"tool_use\":\n    return\n```\n\n**Step 4**: Execute the tool the model requested and collect the results.\n\n```python\nresults = []\nfor block in response.content:\n    if block.type == \"tool_use\":\n        output = run_bash(block.input[\"command\"])\n        results.append({\n            \"type\": \"tool_result\",\n            \"tool_use_id\": block.id,\n            \"content\": output,\n        })\n```\n\n**Step 5**: Append the tool results as a new message and go back to Step 2.\n\n```python\nmessages.append({\"role\": \"user\", \"content\": results})\n```\n\nAssembled into a complete function:\n\n```python\ndef agent_loop(messages):\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=SYSTEM, messages=messages,\n            tools=TOOLS, max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                output = run_bash(block.input[\"command\"])\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": output,\n                })\n        messages.append({\"role\": \"user\", \"content\": results})\n```\n\nUnder 30 lines — that's the minimal runnable agent harness kernel. It's not intelligence itself, but the smallest runtime framework that lets the model keep acting. The model decides (whether to call a tool, which one), the harness executes (if called, run it, feed the result back). The next 18 chapters all add mechanisms on top of this loop. The loop itself never changes.\n\n---\n\n## Try It\n\n> **Safety notice**: The code executes shell commands generated by the model. Run it in a temporary test directory to avoid affecting your project files. s03 adds permission controls.\n\n**Setup** (first run):\n\n```sh\npip install -r requirements.txt\ncp .env.example .env\n# Edit .env, fill in ANTHROPIC_API_KEY and MODEL_ID\n```\n\n**Run**:\n\n```sh\npython s01_agent_loop/code.py\n```\n\nTry these prompts:\n\n1. `Create a file called hello.py that prints \"Hello, World!\"`\n2. `List all Python files in this directory`\n3. `What is the current git branch?`\n\nWhat to watch for: When does the model call a tool (loop continues), and when does it not (loop ends)?\n\n---\n\n## What's Next\n\nRight now the model only has bash — reading files requires `cat`, writing files requires `echo ... >`, finding files requires `find`. Ugly and error-prone.\n\n→ s02 Tool Use: What happens when we give it 5 proper tools? Will the model call multiple tools at once? Will parallel tool executions step on each other?\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s01",
    "locale": "zh",
    "title": "s01: Agent Loop — 一个循环就够了",
    "content": "# s01: Agent Loop — 一个循环就够了\n\n`s01` → [s02](/zh/s02) → s03 → s04 → ... → s20 → s21\n> *\"One loop & Bash is all you need\"* — 一个工具 + 一个循环 = 一个 Agent。\n>\n> **Harness 层**: 循环 — 模型与真实世界的第一道连接。\n\n---\n\n## 问题\n\n你提出了一个问题给大模型：“帮我读取下我的目录下有哪些文件，并且执行XXX.py”。\n\n模型能输出一条 bash 命令，但输出完了就停了，它不会自己跑，也不会看到结果后继续推理。\n\n你可以手动跑一遍，把输出粘贴回对话框，让它接着干。下一个命令出来，你再跑一遍、再贴回去。\n\n每一个来回，你都在做中间层。而把它自动化，就是这一章要做的事。\n\n---\n\n## 解决方案\n\n![Agent Loop](/course-assets/s01_agent_loop/agent-loop.svg)\n\n一个 `while True` 循环，模型调用工具就继续，不调用就停。整个过程只有两个信号：\n\n| 信号 | 含义 | 循环动作 |\n|------|------|---------|\n| `stop_reason == \"tool_use\"` | 模型举手说\"我要用工具\" | 执行 → 结果喂回去 → 继续 |\n| `stop_reason != \"tool_use\"` | 模型说\"我做完了\" | 退出循环 |\n\n---\n\n## 工作原理\n\n将这个过程翻译成代码。分步来看：\n\n**第 1 步**：把用户的问题作为第一条消息。\n\n```python\nmessages = [{\"role\": \"user\", \"content\": query}]\n```\n\n**第 2 步**：将消息和工具定义一起发给 LLM。\n\n```python\nresponse = client.messages.create(\n    model=MODEL, system=SYSTEM, messages=messages,\n    tools=TOOLS, max_tokens=8000,\n)\n```\n\n**第 3 步**：追加模型回答，检查它是否调了工具。没调 → 结束。\n\n```python\nmessages.append({\"role\": \"assistant\", \"content\": response.content})\nif response.stop_reason != \"tool_use\":\n    return\n```\n\n**第 4 步**：执行模型要求的工具，收集结果。\n\n```python\nresults = []\nfor block in response.content:\n    if block.type == \"tool_use\":\n        output = run_bash(block.input[\"command\"])\n        results.append({\n            \"type\": \"tool_result\",\n            \"tool_use_id\": block.id,\n            \"content\": output,\n        })\n```\n\n**第 5 步**：把工具结果作为新消息追加，回到第 2 步。\n\n```python\nmessages.append({\"role\": \"user\", \"content\": results})\n```\n\n组装为一个完整函数：\n\n```python\ndef agent_loop(messages):\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=SYSTEM, messages=messages,\n            tools=TOOLS, max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                output = run_bash(block.input[\"command\"])\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": output,\n                })\n        messages.append({\"role\": \"user\", \"content\": results})\n```\n\n不到 30 行，这就是最小可运行的 agent harness 内核。它不是智能本身，而是让模型能持续行动的最小运行框架，模型负责决策（要不要调工具、调哪个），harness 负责执行（调了就跑、结果喂回去）。后面 18 个章节都在这个循环上叠加机制，循环本身始终不变。\n\n---\n\n## 试一下\n\n> **安全提示**：代码会执行模型生成的 shell 命令。建议在一个临时测试目录中运行，避免影响你的项目文件。s03 会加入权限控制。\n\n**准备**（首次运行）：\n\n```sh\npip install -r requirements.txt\ncp .env.example .env\n# 编辑 .env，填入 ANTHROPIC_API_KEY 和 MODEL_ID\n```\n\n**运行**：\n\n```sh\npython s01_agent_loop/code.py\n```\n\n试试这些 prompt：\n\n1. `Create a file called hello.py that prints \"Hello, World!\"`\n2. `List all Python files in this directory`\n3. `What is the current git branch?`\n\n观察重点：模型什么时候调用工具（循环继续），什么时候不调用（循环结束）？\n\n---\n\n## 接下来\n\n现在模型手里只有 bash 一个工具，读文件要 `cat`，写文件要 `echo ... >`，找个文件要 `find`，又丑又容易出错。\n\ns02 Tool Use → 给它 5 个真正的工具，会发生什么？模型会不会一次调用多个工具？几个工具同时跑会不会互相踩？\n\n\n<!-- translation-sync: zh@v1, en@v0, ja@v0 -->\n"
  },
  {
    "version": "s01",
    "locale": "ja",
    "title": "s01: Agent Loop — ループ一つで十分",
    "content": "# s01: Agent Loop — ループ一つで十分\n\n`s01` → [s02](/ja/s02) → s03 → s04 → ... → s20 → s21\n> *\"One loop & Bash is all you need\"* — ツール一つ + ループ一つ = 一つの Agent。\n>\n> **Harness レイヤー**: ループ — モデルと現実世界をつなぐ最初の架け橋。\n\n---\n\n## 課題\n\nモデルにこう頼んだとする：「ディレクトリ内のファイル一覧を取得して、XXX.py を実行して」。\n\nモデルは bash コマンドを出力できるが、出力が終わると止まってしまう — 自分で実行することも、結果を見て推論を続けることもない。\n\n手動で実行し、出力をチャットに貼り付ければ、モデルは続きを生成できる。次のコマンドが出たら、また実行して貼り付ける。\n\n毎回の往復で、あなたが中間層になっている。これを自動化するのが、この章の目的だ。\n\n---\n\n## ソリューション\n\n![Agent Loop](/course-assets/s01_agent_loop/agent-loop.ja.svg)\n\n一つの `while True` ループ — モデルがツールを呼べば続き、呼ばなければ停止。全体でたった 2 つのシグナル：\n\n| シグナル | 意味 | ループの動作 |\n|----------|------|-------------|\n| `stop_reason == \"tool_use\"` | モデルが「ツールが必要」と挙手 | 実行 → 結果を戻す → 続行 |\n| `stop_reason != \"tool_use\"` | モデルが「完了」と宣言 | ループ終了 |\n\n---\n\n## 仕組み\n\nこのプロセスをコードに変換してみよう。ステップごとに：\n\n**ステップ 1**：ユーザーの質問を最初のメッセージとして設定する。\n\n```python\nmessages = [{\"role\": \"user\", \"content\": query}]\n```\n\n**ステップ 2**：メッセージとツール定義を一緒に LLM に送信する。\n\n```python\nresponse = client.messages.create(\n    model=MODEL, system=SYSTEM, messages=messages,\n    tools=TOOLS, max_tokens=8000,\n)\n```\n\n**ステップ 3**：モデルの応答を追加し、ツールを呼び出したか確認する。呼び出しなし → 終了。\n\n```python\nmessages.append({\"role\": \"assistant\", \"content\": response.content})\nif response.stop_reason != \"tool_use\":\n    return\n```\n\n**ステップ 4**：モデルが要求したツールを実行し、結果を収集する。\n\n```python\nresults = []\nfor block in response.content:\n    if block.type == \"tool_use\":\n        output = run_bash(block.input[\"command\"])\n        results.append({\n            \"type\": \"tool_result\",\n            \"tool_use_id\": block.id,\n            \"content\": output,\n        })\n```\n\n**ステップ 5**：ツールの結果を新しいメッセージとして追加し、ステップ 2 に戻る。\n\n```python\nmessages.append({\"role\": \"user\", \"content\": results})\n```\n\n完全な関数に組み立てる：\n\n```python\ndef agent_loop(messages):\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=SYSTEM, messages=messages,\n            tools=TOOLS, max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                output = run_bash(block.input[\"command\"])\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": output,\n                })\n        messages.append({\"role\": \"user\", \"content\": results})\n```\n\n30 行未満 — これが最小実行可能な agent harness のカーネルだ。これは知能そのものではなく、モデルが継続的に行動できるための最小ランタイムフレームワーク。モデルが決定し（ツールを呼ぶか、どれを呼ぶか）、harness が実行する（呼ばれたら実行し、結果を戻す）。次の 18 章はすべてこのループの上に仕組みを積み重ねていく。ループ自体は永遠に変わらない。\n\n---\n\n## 試してみよう\n\n> **安全上の注意**: このコードはモデルが生成したシェルコマンドを実行します。プロジェクトファイルへの影響を避けるため、一時テストディレクトリで実行してください。s03 で権限制御を追加します。\n\n**準備**（初回のみ）：\n\n```sh\npip install -r requirements.txt\ncp .env.example .env\n# .env を編集し、ANTHROPIC_API_KEY と MODEL_ID を入力\n```\n\n**実行**：\n\n```sh\npython s01_agent_loop/code.py\n```\n\n以下のプロンプトを試してみよう：\n\n1. `Create a file called hello.py that prints \"Hello, World!\"`\n2. `List all Python files in this directory`\n3. `What is the current git branch?`\n\n観察のポイント：モデルがツールを呼び出すとき（ループ継続）、呼び出さないとき（ループ終了）の違い。\n\n---\n\n## 次へ\n\n現在、モデルが持っているのは bash だけだ — ファイルを読むには `cat`、書くには `echo ... >`、探すには `find`。不便でエラーも起きやすい。\n\n→ s02 Tool Use：5 つの本格的なツールを与えたらどうなる？ モデルは複数のツールを同時に呼び出すか？ 並列実行で競合は起きないか？\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s02",
    "locale": "en",
    "title": "s02: Tool Use — Add a Tool, Add Just One Line",
    "content": "# s02: Tool Use — Add a Tool, Add Just One Line\n\ns01 → `s02` → [s03](/en/s03) → s04 → ... → s20 → s21\n> *\"Add a tool, add just one handler\"* — The loop stays the same. Register the new tool in the dispatch map and you're done.\n>\n> **Harness Layer**: Tool Dispatch — Expanding the model's reach.\n\n---\n\n## Only One Tool: Bash\n\nThe s01 Agent has only one tool: bash. To read a file, `cat`; to write, `echo \"...\" > file.py`; to edit, `sed`.\n\nThe model thinks \"read this file\" but has to spell out `cat path/to/file`. An extra layer of translation that wastes tokens and invites errors.\n\n---\n\n## Overview: Tool Dispatch\n\n![Tool Dispatch](/course-assets/s02_tool_use/tool-dispatch.en.svg)\n\nThe s01 loop is fully preserved (LLM call, stop_reason check, message append — not a single word changed). The only change is in that one line of tool execution: `run_bash()` is replaced with `TOOL_HANDLERS[block.name]()` dispatch lookup.\n\nAdding a tool to the Agent requires just two things:\n\n1. **Define the tool**: Add one entry to the `TOOLS` array\n2. **Register the handler**: Add one mapping in the `TOOL_HANDLERS` dict\n\n---\n\n## From 1 Tool to 5 Tools\n\ns01 had only bash:\n\n```python\nTOOLS = [{\"name\": \"bash\", ...}]\n\ndef run_bash(command): ...\n```\n\ns02 expands to 5 tools, each independently defined:\n\n```python\nTOOLS = [\n    {\"name\": \"bash\",       \"description\": \"Run a shell command.\", ...},\n    {\"name\": \"read_file\",  \"description\": \"Read file contents.\",  ...},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\", ...},\n    {\"name\": \"edit_file\",  \"description\": \"Replace text in file once.\", ...},\n    {\"name\": \"glob\",       \"description\": \"Find files by pattern.\", ...},\n]\n```\n\nEach tool has its own implementation function:\n\n```python\ndef run_read(path, limit=None):\n    lines = safe_path(path).read_text().splitlines()\n    if limit:\n        lines = lines[:limit]\n    return \"\\n\".join(lines)\n\ndef run_write(path, content):\n    safe_path(path).write_text(content)\n    return f\"Wrote {len(content)} bytes to {path}\"\n\ndef run_edit(path, old_text, new_text):\n    text = safe_path(path).read_text()\n    if old_text not in text:\n        return \"Error: text not found\"\n    safe_path(path).write_text(text.replace(old_text, new_text, 1))\n    return f\"Edited {path}\"\n\ndef run_glob(pattern):\n    import glob as g\n    return \"\\n\".join(g.glob(pattern, root_dir=WORKDIR))\n```\n\n---\n\n## Tool Dispatch\n\n```python\nTOOL_HANDLERS = {\n    \"bash\":       run_bash,\n    \"read_file\":  run_read,\n    \"write_file\": run_write,\n    \"edit_file\":  run_edit,\n    \"glob\":       run_glob,\n}\n\n# Only one line changed in the loop — from hardcoded run_bash to dispatch lookup:\nfor block in response.content:\n    if block.type == \"tool_use\":\n        handler = TOOL_HANDLERS[block.name]    # lookup\n        output = handler(**block.input)         # call\n        results.append(...)\n```\n\nAdding a tool = one entry in `TOOLS` array + one line in `TOOL_HANDLERS` dict. The loop stays the same.\n\n---\n\n## Multiple Tool Calls\n\nThe model often returns multiple tool_use calls at once — \"read a.py and b.py, then list all .py files\".\n\nCalls are executed one by one in their original `response.content` order.\n\n---\n\n## Quick Reference\n\n| Concept | One-Liner |\n|---------|-----------|\n| TOOL_HANDLERS | Tool name → handler function dict. Add a tool = add one mapping line |\n| Tool Definition | JSON schema telling the model \"what I can do\" |\n| Multiple tool calls | Model may return multiple tool_use at once; calls execute in their original order |\n| Loop Unchanged | s01's `while True` loop — not a single line changed |\n\n---\n\n## Changes from s01\n\n| Component | Before (s01) | After (s02) |\n|-----------|-------------|-------------|\n| Tool count | 1 (bash) | 5 (+read, write, edit, glob) |\n| Tool execution | Hardcoded `run_bash()` | TOOL_HANDLERS dispatch lookup |\n| Path safety | None | safe_path validation (file tools only) |\n| Loop | `while True` + `stop_reason` | Identical to s01 |\n\n---\n\n## Try It\n\n```sh\ncd learn-claude-code\npython s02_tool_use/code.py\n```\n\nTry these prompts:\n\n1. `Read the file README.md and tell me what this project is about`\n2. `Create a file called test.py that prints \"hello\", then read it back`\n3. `Find all Python files in this directory`\n4. `Read both README.md and requirements.txt, then create a summary file`\n\nWhat to watch for: When does the model call just one tool, and when does it call multiple at once? Are multiple tool calls executed in the correct order?\n\n---\n\n## What's Next\n\nThe Agent now has 5 specialized tools. File tools are protected by `safe_path`, but bash is unrestricted — `rm -rf /` still runs.\n\n→ s03 Permission: Add a gate before tool execution — is this operation safe? Does it need user approval?\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s02",
    "locale": "zh",
    "title": "s02: Tool Use — 多加一个工具，只加一行",
    "content": "# s02: Tool Use — 多加一个工具，只加一行\n\ns01 → `s02` → [s03](/zh/s03) → s04 → ... → s20 → s21\n> *\"加一个工具, 只加一个 handler\"* — 循环不用动, 新工具注册进 dispatch map 就行。\n>\n> **Harness 层**: 工具分发 — 扩展模型能触达的边界。\n\n---\n\n## 只有 bash 一个工具\n\ns01 的 Agent 只有一个 bash 工具。读文件要 `cat`，写文件要 `echo \"...\" > file.py`，改文件要 `sed`。\n\n模型想的是\"读这个文件\"，却要拼出 `cat path/to/file`。多了一层翻译，浪费 token，还容易拼错。\n\n---\n\n## 全局视角：工具分发\n\n![Tool Dispatch](/course-assets/s02_tool_use/tool-dispatch.svg)\n\ns01 的循环完全保留（LLM 调用、stop_reason 判断、消息追加）。唯一的变动在工具执行那 1 行：`run_bash()` 替换为 `TOOL_HANDLERS[block.name]()` 查表分发。\n\n给 Agent 加一个工具只需要做两件事：\n\n1. **定义工具**：在 `TOOLS` 数组里加一条描述\n2. **注册处理函数**：在 `TOOL_HANDLERS` 字典里加一个映射\n\n---\n\n## 从 1 个工具到 5 个工具\n\ns01 只有一个 bash：\n\n```python\nTOOLS = [{\"name\": \"bash\", ...}]\n\ndef run_bash(command): ...\n```\n\ns02 加到 5 个，每个工具都是独立定义：\n\n```python\nTOOLS = [\n    {\"name\": \"bash\",       \"description\": \"Run a shell command.\", ...},\n    {\"name\": \"read_file\",  \"description\": \"Read file contents.\",  ...},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\", ...},\n    {\"name\": \"edit_file\",  \"description\": \"Replace text in file once.\", ...},\n    {\"name\": \"glob\",       \"description\": \"Find files by pattern.\", ...},\n]\n```\n\n每个工具有自己的实现函数：\n\n```python\ndef run_read(path, limit=None):\n    lines = safe_path(path).read_text().splitlines()\n    if limit:\n        lines = lines[:limit]\n    return \"\\n\".join(lines)\n\ndef run_write(path, content):\n    safe_path(path).write_text(content)\n    return f\"Wrote {len(content)} bytes to {path}\"\n\ndef run_edit(path, old_text, new_text):\n    text = safe_path(path).read_text()\n    if old_text not in text:\n        return \"Error: text not found\"\n    safe_path(path).write_text(text.replace(old_text, new_text, 1))\n    return f\"Edited {path}\"\n\ndef run_glob(pattern):\n    import glob as g\n    return \"\\n\".join(g.glob(pattern, root_dir=WORKDIR))\n```\n\n---\n\n## 工具分发\n\n```python\nTOOL_HANDLERS = {\n    \"bash\":       run_bash,\n    \"read_file\":  run_read,\n    \"write_file\": run_write,\n    \"edit_file\":  run_edit,\n    \"glob\":       run_glob,\n}\n\n# 循环里只改了一行——从硬编码 run_bash 变成查表：\nfor block in response.content:\n    if block.type == \"tool_use\":\n        handler = TOOL_HANDLERS[block.name]    # 查表\n        output = handler(**block.input)         # 调用\n        results.append(...)\n```\n\n加一个工具 = 在 `TOOLS` 数组加一条 + 在 `TOOL_HANDLERS` 字典加一行。循环不变。\n\n---\n\n## 多个工具调用\n\n模型经常一次返回多个 tool_use：\"读一下 a.py 和 b.py，然后列出所有 .py 文件\"。\n\n这些调用按照 `response.content` 中的原始顺序逐个执行。\n\n---\n\n## 速查\n\n| 概念 | 一句话 |\n|------|--------|\n| TOOL_HANDLERS | 工具名 → 处理函数的字典。加工具 = 加一行映射 |\n| 工具定义 | 告诉模型\"我能做什么\"的 JSON schema |\n| 多工具调用 | 模型可一次返回多个 tool_use，并按原始顺序逐个执行 |\n| 循环不变 | s01 的 `while True` 循环一行都没改 |\n\n---\n\n## 相对 s01 的变更\n\n| 组件 | 之前 (s01) | 之后 (s02) |\n|------|-----------|-----------|\n| 工具数量 | 1 (bash) | 5 (+read, write, edit, glob) |\n| 工具执行 | 硬编码 `run_bash()` | TOOL_HANDLERS 查表分发 |\n| 路径安全 | 无 | safe_path 校验（仅 file tools） |\n| 循环 | `while True` + `stop_reason` | 与 s01 完全一致 |\n\n---\n\n## 试一下\n\n```sh\ncd learn-claude-code\npython s02_tool_use/code.py\n```\n\n试试这些 prompt：\n\n1. `Read the file README.md and tell me what this project is about`\n2. `Create a file called test.py that prints \"hello\", then read it back`\n3. `Find all Python files in this directory`\n4. `Read both README.md and requirements.txt, then create a summary file`\n\n观察重点：模型什么时候只调一个工具，什么时候一次调多个？多个工具调用的顺序和结果是否正确？\n\n---\n\n## 接下来\n\n现在 Agent 有 5 个专用工具。file tools 受 `safe_path` 保护，但 bash 不受限制，`rm -rf /` 还是能跑。\n\ns03 Permission → 在工具执行之前加一道门：这个操作安全吗？需要用户批准吗？\n\n\n<!-- translation-sync: zh@v1, en@v0, ja@v0 -->\n"
  },
  {
    "version": "s02",
    "locale": "ja",
    "title": "s02: Tool Use — ツール一つ追加、一行追加だけ",
    "content": "# s02: Tool Use — ツール一つ追加、一行追加だけ\n\ns01 → `s02` → [s03](/ja/s03) → s04 → ... → s20 → s21\n> *\"ツールを一つ追加、ハンドラを一つ追加\"* — ループはそのまま。新しいツールをディスパッチマップに登録するだけ。\n>\n> **Harness レイヤー**: ツールディスパッチ — モデルが触れる範囲を拡張。\n\n---\n\n## ツールは bash 一つだけ\n\ns01 の Agent には bash 一つのツールしかない。ファイルを読むには `cat`、書くには `echo \"...\" > file.py`、編集するには `sed`。\n\nモデルは「このファイルを読みたい」と考えながら、`cat path/to/file` と組み立てなければならない。翻訳の層が一つ増え、トークンを無駄にし、エラーも起きやすい。\n\n---\n\n## 概要：ツールディスパッチ\n\n![Tool Dispatch](/course-assets/s02_tool_use/tool-dispatch.ja.svg)\n\ns01 のループは完全に保持される（LLM 呼び出し、stop_reason 判定、メッセージ追加 — 一文字も変更なし）。唯一の変更点はツール実行の 1 行：`run_bash()` が `TOOL_HANDLERS[block.name]()` の検索ディスパッチに置き換わる。\n\nAgent にツールを追加するには、たった二つ：\n\n1. **ツールを定義**：`TOOLS` 配列に一条を追加\n2. **ハンドラを登録**：`TOOL_HANDLERS` 辞書に一つのマッピングを追加\n\n---\n\n## 1 つのツールから 5 つのツールへ\n\ns01 には bash だけだった：\n\n```python\nTOOLS = [{\"name\": \"bash\", ...}]\n\ndef run_bash(command): ...\n```\n\ns02 では 5 つに増え、各ツールは独立して定義される：\n\n```python\nTOOLS = [\n    {\"name\": \"bash\",       \"description\": \"Run a shell command.\", ...},\n    {\"name\": \"read_file\",  \"description\": \"Read file contents.\",  ...},\n    {\"name\": \"write_file\", \"description\": \"Write content to file.\", ...},\n    {\"name\": \"edit_file\",  \"description\": \"Replace text in file once.\", ...},\n    {\"name\": \"glob\",       \"description\": \"Find files by pattern.\", ...},\n]\n```\n\n各ツールには専用の実装関数がある：\n\n```python\ndef run_read(path, limit=None):\n    lines = safe_path(path).read_text().splitlines()\n    if limit:\n        lines = lines[:limit]\n    return \"\\n\".join(lines)\n\ndef run_write(path, content):\n    safe_path(path).write_text(content)\n    return f\"Wrote {len(content)} bytes to {path}\"\n\ndef run_edit(path, old_text, new_text):\n    text = safe_path(path).read_text()\n    if old_text not in text:\n        return \"Error: text not found\"\n    safe_path(path).write_text(text.replace(old_text, new_text, 1))\n    return f\"Edited {path}\"\n\ndef run_glob(pattern):\n    import glob as g\n    return \"\\n\".join(g.glob(pattern, root_dir=WORKDIR))\n```\n\n---\n\n## ツールディスパッチ\n\n```python\nTOOL_HANDLERS = {\n    \"bash\":       run_bash,\n    \"read_file\":  run_read,\n    \"write_file\": run_write,\n    \"edit_file\":  run_edit,\n    \"glob\":       run_glob,\n}\n\n# ループ内で変更されたのは一行だけ — ハードコードの run_bash から検索ディスパッチへ：\nfor block in response.content:\n    if block.type == \"tool_use\":\n        handler = TOOL_HANDLERS[block.name]    # 検索\n        output = handler(**block.input)         # 呼び出し\n        results.append(...)\n```\n\nツールの追加 = `TOOLS` 配列に一条 + `TOOL_HANDLERS` 辞書に一行。ループは変わらない。\n\n---\n\n## 複数のツール呼び出し\n\nモデルはよく一度に複数の tool_use を返す — 「a.py と b.py を読んで、全 .py ファイルを列挙して」。\n\nこれらの呼び出しは、`response.content` に現れる元の順序で一つずつ実行する。\n\n---\n\n## 速查\n\n| 概念 | 一言で |\n|------|--------|\n| TOOL_HANDLERS | ツール名 → ハンドラ関数の辞書。ツール追加 = マッピング一行追加 |\n| ツール定義 | モデルに「何ができるか」を伝える JSON schema |\n| 複数ツール呼び出し | モデルは一度に複数の tool_use を返す可能性があり、元の順序で一つずつ実行する |\n| ループ不変 | s01 の `while True` ループ — 一行も変更なし |\n\n---\n\n## s01 からの変更\n\n| コンポーネント | 変更前 (s01) | 変更後 (s02) |\n|--------------|-------------|-------------|\n| ツール数 | 1 (bash) | 5 (+read, write, edit, glob) |\n| ツール実行 | ハードコード `run_bash()` | TOOL_HANDLERS 検索ディスパッチ |\n| パス安全性 | なし | safe_path 検証（file tools のみ） |\n| ループ | `while True` + `stop_reason` | s01 と完全に同一 |\n\n---\n\n## 試してみよう\n\n```sh\ncd learn-claude-code\npython s02_tool_use/code.py\n```\n\n以下のプロンプトを試してみよう：\n\n1. `Read the file README.md and tell me what this project is about`\n2. `Create a file called test.py that prints \"hello\", then read it back`\n3. `Find all Python files in this directory`\n4. `Read both README.md and requirements.txt, then create a summary file`\n\n観察のポイント：モデルがツールを一つだけ呼び出すときと、複数同時に呼び出すときの違い。複数のツール呼び出しは正しい順序で実行されているか？\n\n---\n\n## 次へ\n\nAgent は 5 つの専用ツールを持つようになった。file tools は `safe_path` で保護されるが、bash は制限なし — `rm -rf /` はまだ実行できる。\n\n→ s03 Permission：ツール実行前にゲートを追加 — この操作は安全か？ ユーザーの承認が必要か？\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s03",
    "locale": "en",
    "title": "s03: Permission — Check Permissions Before Execution",
    "content": "# s03: Permission — Check Permissions Before Execution\n\ns01 → s02 → `s03` → [s04](/en/s04) → s05 → ... → s20 → s21\n> *\"Check permissions before executing\"* — The permission pipeline decides which operations need approval.\n>\n> **Harness Layer**: Permission — a gate before tool execution.\n\n---\n\n## The Problem\n\ns02's Agent has 5 tools. File tools are protected by `safe_path`, but bash is unrestricted. Ask it to \"clean up the project,\" and it might run `rm -rf /`.\n\nSafety can't rely on trusting the model — it needs code: a check before every tool execution.\n\n---\n\n## The Solution\n\n![Permission Overview](/course-assets/s03_permission/permission-overview.en.svg)\n\ns02's loop is fully preserved. The only change is inserting `check_permission()` before tool execution — each tool call passes through three gates in a fixed order: hard deny first, then soft ask, and if neither matches, allow.\n\nThe three gates correspond to three decisions:\n\n| Gate | Purpose | On Match |\n|------|---------|----------|\n| 1. Deny List | Permanently forbidden operations (`rm -rf /`, `sudo`) | Denied immediately, not executed |\n| 2. Rule Matching | Context-dependent operations (reading/writing outside workspace, `rm` files) | Passed to Gate 3 |\n| 3. User Approval | After Gate 2 matches, pauses for user confirmation | User decides allow or deny |\n\nNone of the three gates match → execute directly. Most routine operations take this path.\n\n---\n\n## How It Works\n\n![Permission Pipeline](/course-assets/s03_permission/permission-pipeline.en.svg)\n\n**Gate 1**: A hard deny list. Check first; if matched, return a block message. This list uses simple string matching to show where the permission gate sits; it is not a complete security boundary.\n\n```python\nDENY_LIST = [\n    \"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\",\n    \"mkfs\", \"dd if=\", \"> /dev/sda\",\n]\n\ndef check_deny_list(command: str) -> str | None:\n    for pattern in DENY_LIST:\n        if pattern in command:\n            return f\"Blocked: '{pattern}' is on the deny list\"\n    return None\n```\n\n**Gate 2**: Rule matching — describes \"when to ask the user.\" Each rule specifies a tool and a check condition.\n\n```python\nPERMISSION_RULES = [\n    {\n        \"tools\": [\"read_file\", \"write_file\", \"edit_file\"],\n        \"check\": lambda args: not (WORKDIR / args.get(\"path\", \"\")).resolve().is_relative_to(WORKDIR),\n        \"message\": \"Access outside workspace\",\n    },\n    {\n        \"tools\": [\"bash\"],\n        \"check\": lambda args: any(kw in args.get(\"command\", \"\") for kw in [\"rm \", \"> /etc/\", \"chmod 777\"]),\n        \"message\": \"Potentially destructive command\",\n    },\n]\n\ndef check_rules(tool_name: str, args: dict) -> str | None:\n    for rule in PERMISSION_RULES:\n        if tool_name in rule[\"tools\"] and rule[\"check\"](args):\n            return rule[\"message\"]\n    return None\n```\n\n**Gate 3**: After a rule matches, pause for user input.\n\n```python\ndef ask_user(tool_name: str, args: dict, reason: str) -> str:\n    print(f\"\\n⚠  {reason}\")\n    print(f\"   Tool: {tool_name}({args})\")\n    choice = input(\"   Allow? [y/N] \").strip().lower()\n    return \"allow\" if choice in (\"y\", \"yes\") else \"deny\"\n```\n\n**All three gates chained together**, inserted before tool execution:\n\n```python\ndef check_permission(block) -> bool:\n    # Gate 1: Hard deny\n    if block.name == \"bash\":\n        reason = check_deny_list(block.input.get(\"command\", \"\"))\n        if reason:\n            print(f\"\\n⛔ {reason}\")\n            return False\n\n    # Gate 2 + 3: Rule matching → User approval\n    reason = check_rules(block.name, block.input)\n    if reason:\n        decision = ask_user(block.name, block.input, reason)\n        if decision == \"deny\":\n            return False\n\n    return True\n\n# In agent_loop — s02's loop with just one line added:\nfor block in response.content:\n    if block.type == \"tool_use\":\n        if not check_permission(block):           # ← NEW\n            results.append({... \"content\": \"Permission denied.\"})\n            continue\n        output = TOOL_HANDLERS[block.name](**block.input)  # s02 original\n        results.append(...)\n```\n\n---\n\n## Changes from s02\n\n| Component | Before (s02) | After (s03) |\n|-----------|-------------|-------------|\n| Security model | None (trust the model) | Three-gate permission pipeline |\n| New functions | — | check_deny_list, check_rules, ask_user, check_permission |\n| Loop | Executes all tools directly | Inserts check_permission() before execution |\n\n---\n\n## Try It\n\n```sh\ncd learn-claude-code\npython s03_permission/code.py\n```\n\nTry these prompts:\n\n1. `Create a file called test.txt in the current directory` (should pass through)\n2. `Delete the file test.txt` (bash + rm triggers Gate 2)\n3. `What files are in the current directory?` (read-only, all pass)\n4. `Try to write a file to /etc/something` (writing outside workspace triggers Gate 2)\n\nWhat to watch for: Which operations pass through? Which need your confirmation? Which are denied outright?\n\n---\n\n## What's Next\n\nPermission checks are in place — but every check is hardcoded as `check_permission()` inside the loop. What if you want to add logging before and after each tool execution? What if you want to auto-trigger a git commit after certain operations? Scattering this extension logic throughout the loop makes it bloat.\n\n→ s04 Hooks: Add hooks to the loop. Extension logic hangs on hooks; the loop stays clean.\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s03",
    "locale": "zh",
    "title": "s03: Permission — 执行前做权限判断",
    "content": "# s03: Permission — 执行前做权限判断\n\ns01 → s02 → `s03` → [s04](/zh/s04) → s05 → ... → s20 → s21\n> *\"工具执行前先做权限判断\"* — 权限管线决定哪些操作需要审批。\n>\n> **Harness 层**: 权限 — 在工具执行前加一道门。\n\n---\n\n## 问题\n\ns02 的 Agent 有 5 个工具。file tools 受 `safe_path` 保护，但 bash 不受限制。让它\"清理一下项目\"，可能执行 `rm -rf /`。\n\n安全不能靠信任模型，要靠代码——在工具执行之前做判断。\n\n---\n\n## 解决方案\n\n![Permission Overview](/course-assets/s03_permission/permission-overview.svg)\n\ns02 的循环完全保留。唯一的变动在工具执行前插入 `check_permission()`——每个工具调用经过三道闸门，顺序固定：硬拒绝优先，软询问次之，都没命中就放行。\n\n三道闸门对应三种决策：\n\n| 闸门 | 作用 | 命中后 |\n|------|------|--------|\n| 1. 拒绝列表 | 永远禁止的操作（`rm -rf /`、`sudo`） | 直接拒绝，不执行 |\n| 2. 规则匹配 | 取决于上下文的操作（读/写工作区外、`rm` 文件） | 交给闸门 3 |\n| 3. 用户审批 | 闸门 2 命中后，暂停等用户确认 | 用户决定允许或拒绝 |\n\n三道都没命中 → 直接执行。大部分日常操作走这条路。\n\n---\n\n## 工作原理\n\n![Permission Pipeline](/course-assets/s03_permission/permission-pipeline.svg)\n\n**闸门 1**：一张硬拒绝表，先查，命中就返回阻止信息。这张表使用简单字符串匹配来说明权限闸门的位置，不能视为完整的安全边界。\n\n```python\nDENY_LIST = [\n    \"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\",\n    \"mkfs\", \"dd if=\", \"> /dev/sda\",\n]\n\ndef check_deny_list(command: str) -> str | None:\n    for pattern in DENY_LIST:\n        if pattern in command:\n            return f\"Blocked: '{pattern}' is on the deny list\"\n    return None\n```\n\n**闸门 2**：规则匹配——描述\"什么时候需要问用户\"。每条规则指定工具和检查条件。\n\n```python\nPERMISSION_RULES = [\n    {\n        \"tools\": [\"read_file\", \"write_file\", \"edit_file\"],\n        \"check\": lambda args: not (WORKDIR / args.get(\"path\", \"\")).resolve().is_relative_to(WORKDIR),\n        \"message\": \"Access outside workspace\",\n    },\n    {\n        \"tools\": [\"bash\"],\n        \"check\": lambda args: any(kw in args.get(\"command\", \"\") for kw in [\"rm \", \"> /etc/\", \"chmod 777\"]),\n        \"message\": \"Potentially destructive command\",\n    },\n]\n\ndef check_rules(tool_name: str, args: dict) -> str | None:\n    for rule in PERMISSION_RULES:\n        if tool_name in rule[\"tools\"] and rule[\"check\"](args):\n            return rule[\"message\"]\n    return None\n```\n\n**闸门 3**：规则命中后，暂停等用户输入。\n\n```python\ndef ask_user(tool_name: str, args: dict, reason: str) -> str:\n    print(f\"\\n⚠  {reason}\")\n    print(f\"   Tool: {tool_name}({args})\")\n    choice = input(\"   Allow? [y/N] \").strip().lower()\n    return \"allow\" if choice in (\"y\", \"yes\") else \"deny\"\n```\n\n**三道闸门串在一起**，插在工具执行之前：\n\n```python\ndef check_permission(block) -> bool:\n    # 闸门 1: 硬拒绝\n    if block.name == \"bash\":\n        reason = check_deny_list(block.input.get(\"command\", \"\"))\n        if reason:\n            print(f\"\\n⛔ {reason}\")\n            return False\n\n    # 闸门 2 + 3: 规则匹配 → 用户审批\n    reason = check_rules(block.name, block.input)\n    if reason:\n        decision = ask_user(block.name, block.input, reason)\n        if decision == \"deny\":\n            return False\n\n    return True\n\n# 在 agent_loop 中——s02 的循环只加了一行：\nfor block in response.content:\n    if block.type == \"tool_use\":\n        if not check_permission(block):           # ← 新增\n            results.append({... \"content\": \"Permission denied.\"})\n            continue\n        output = TOOL_HANDLERS[block.name](**block.input)  # s02 原有\n        results.append(...)\n```\n\n---\n\n## 相对 s02 的变更\n\n| 组件 | 之前 (s02) | 之后 (s03) |\n|------|-----------|-----------|\n| 安全模型 | 无（信任模型） | 三道闸门权限管线 |\n| 新函数 | — | check_deny_list, check_rules, ask_user, check_permission |\n| 循环 | 直接执行所有工具 | 执行前插入 check_permission() |\n\n---\n\n## 试一下\n\n```sh\ncd learn-claude-code\npython s03_permission/code.py\n```\n\n试试这些 prompt：\n\n1. `Create a file called test.txt in the current directory`（应该直接通过）\n2. `Delete the file test.txt`（bash + rm 会触发闸门 2）\n3. `What files are in the current directory?`（只读，全部通过）\n4. `Try to write a file to /etc/something`（写工作区外，触发闸门 2）\n\n观察重点：哪些操作直接通过？哪些需要你确认？哪些被直接拒绝？\n\n---\n\n## 接下来\n\n权限检查做了——但每次都在循环里硬编码 `check_permission()`。如果我想在每次工具执行前后加日志？如果想在某些操作后自动触发 git commit？这些扩展逻辑散落在 loop 里，循环很快就会膨胀。\n\ns04 Hooks → 给循环加钩子，扩展逻辑挂在钩子上，循环保持干净。\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s03",
    "locale": "ja",
    "title": "s03: Permission — 実行前に権限を判断する",
    "content": "# s03: Permission — 実行前に権限を判断する\n\ns01 → s02 → `s03` → [s04](/ja/s04) → s05 → ... → s20 → s21\n> *\"ツール実行前に権限を判断\"* — 権限パイプラインは、どの操作に承認が必要かを決める。\n>\n> **Harness レイヤー**: 権限 — ツール実行前に一つのゲートを追加。\n\n---\n\n## 課題\n\ns02 の Agent は 5 つのツールを持つ。file tools は `safe_path` で保護されるが、bash は制限なし。「プロジェクトを掃除して」と頼むと、`rm -rf /` を実行しかねない。\n\n安全性はモデルを信頼することではなく、コードに頼る — ツール実行前に判断を挟む。\n\n---\n\n## ソリューション\n\n![Permission Overview](/course-assets/s03_permission/permission-overview.ja.svg)\n\ns02 のループは完全に維持される。唯一の変更は、ツール実行前に `check_permission()` を挿入すること — 各ツール呼び出しは 3 つのゲートを固定順序で通過する：ハード拒否が最優先、次にソフト確認、どちらも一致しなければ許可。\n\n3 つのゲートは 3 つの決定に対応する：\n\n| ゲート | 役割 | 一致時 |\n|--------|------|--------|\n| 1. 拒否リスト | 常に禁止される操作（`rm -rf /`、`sudo`） | 即座に拒否、実行しない |\n| 2. ルールマッチング | コンテキスト依存の操作（作業ディレクトリ外への読み書き、`rm` ファイル） | ゲート 3 へ |\n| 3. ユーザー承認 | ゲート 2 が一致した場合、ユーザー確認を待機 | ユーザーが許可または拒否を決定 |\n\n3 つのゲートのどれにも一致しない → 直接実行。日常の操作の大部分はこの経路を通る。\n\n---\n\n## 仕組み\n\n![Permission Pipeline](/course-assets/s03_permission/permission-pipeline.ja.svg)\n\n**ゲート 1**：ハード拒否リスト。最初に確認し、一致すればブロックメッセージを返す。このリストは権限ゲートの位置を示すための単純な文字列照合であり、完全なセキュリティ境界ではない。\n\n```python\nDENY_LIST = [\n    \"rm -rf /\", \"sudo\", \"shutdown\", \"reboot\",\n    \"mkfs\", \"dd if=\", \"> /dev/sda\",\n]\n\ndef check_deny_list(command: str) -> str | None:\n    for pattern in DENY_LIST:\n        if pattern in command:\n            return f\"Blocked: '{pattern}' is on the deny list\"\n    return None\n```\n\n**ゲート 2**：ルールマッチング — 「いつユーザーに聞くべきか」を記述する。各ルールはツールとチェック条件を指定する。\n\n```python\nPERMISSION_RULES = [\n    {\n        \"tools\": [\"read_file\", \"write_file\", \"edit_file\"],\n        \"check\": lambda args: not (WORKDIR / args.get(\"path\", \"\")).resolve().is_relative_to(WORKDIR),\n        \"message\": \"Access outside workspace\",\n    },\n    {\n        \"tools\": [\"bash\"],\n        \"check\": lambda args: any(kw in args.get(\"command\", \"\") for kw in [\"rm \", \"> /etc/\", \"chmod 777\"]),\n        \"message\": \"Potentially destructive command\",\n    },\n]\n\ndef check_rules(tool_name: str, args: dict) -> str | None:\n    for rule in PERMISSION_RULES:\n        if tool_name in rule[\"tools\"] and rule[\"check\"](args):\n            return rule[\"message\"]\n    return None\n```\n\n**ゲート 3**：ルールが一致した後、ユーザー入力を待機。\n\n```python\ndef ask_user(tool_name: str, args: dict, reason: str) -> str:\n    print(f\"\\n⚠  {reason}\")\n    print(f\"   Tool: {tool_name}({args})\")\n    choice = input(\"   Allow? [y/N] \").strip().lower()\n    return \"allow\" if choice in (\"y\", \"yes\") else \"deny\"\n```\n\n**3 つのゲートを直列に接続**、ツール実行前に挿入する：\n\n```python\ndef check_permission(block) -> bool:\n    # ゲート 1: ハード拒否\n    if block.name == \"bash\":\n        reason = check_deny_list(block.input.get(\"command\", \"\"))\n        if reason:\n            print(f\"\\n⛔ {reason}\")\n            return False\n\n    # ゲート 2 + 3: ルールマッチング → ユーザー承認\n    reason = check_rules(block.name, block.input)\n    if reason:\n        decision = ask_user(block.name, block.input, reason)\n        if decision == \"deny\":\n            return False\n\n    return True\n\n# agent_loop で — s02 のループに 1 行追加するだけ：\nfor block in response.content:\n    if block.type == \"tool_use\":\n        if not check_permission(block):           # ← 新規\n            results.append({... \"content\": \"Permission denied.\"})\n            continue\n        output = TOOL_HANDLERS[block.name](**block.input)  # s02 既存\n        results.append(...)\n```\n\n---\n\n## s02 からの変更点\n\n| コンポーネント | 変更前 (s02) | 変更後 (s03) |\n|---------------|-------------|-------------|\n| セキュリティモデル | なし（モデルを信頼） | 3 ゲート権限パイプライン |\n| 新規関数 | — | check_deny_list, check_rules, ask_user, check_permission |\n| ループ | すべてのツールを直接実行 | 実行前に check_permission() を挿入 |\n\n---\n\n## 試してみよう\n\n```sh\ncd learn-claude-code\npython s03_permission/code.py\n```\n\n以下のプロンプトを試してみよう：\n\n1. `Create a file called test.txt in the current directory`（そのまま通過するはず）\n2. `Delete the file test.txt`（bash + rm でゲート 2 が発動）\n3. `What files are in the current directory?`（読み取り専用、すべて通過）\n4. `Try to write a file to /etc/something`（作業ディレクトリ外への書き込みでゲート 2 が発動）\n\n観察のポイント：どの操作がそのまま通過するか？ どれに確認が必要か？ どれが即座に拒否されるか？\n\n---\n\n## 次へ\n\n権限チェックは実装された — しかし、毎回ループ内に `check_permission()` をハードコードしている。ツール実行の前後にログを追加したい場合は？ 特定の操作後に自動的に git commit をトリガーしたい場合は？ このような拡張ロジックがループ内に散らばると、ループはすぐに膨張する。\n\n→ s04 Hooks：ループにフックを追加する。拡張ロジックはフックにぶら下げ、ループはクリーンに保つ。\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s04",
    "locale": "en",
    "title": "s04: Hooks — Hang on the Loop, Don't Write into It",
    "content": "# s04: Hooks — Hang on the Loop, Don't Write into It\n\ns01 → s02 → s03 → `s04` → [s05](/en/s05) → s06 → ... → s20 → s21\n\n> *\"Hang on the loop, don't write into it\"* — Hooks inject extension logic before and after tool execution.\n>\n> **Harness Layer**: Hooks — Extension points that don't invade the loop.\n\n---\n\n## The Problem\n\nThe s03 Agent has permission checks. But every new check, \"log every bash call\", \"auto git add after writes\", requires modifying the `agent_loop` function.\n\nThe loop quickly becomes this:\n\n```python\ndef agent_loop(messages):\n    while True:\n        # ... LLM call ...\n        for block in response.content:\n            if block.type != \"tool_use\":\n                continue\n            log_to_file(block)          # added a line\n            check_permission(block)     # added a line\n            notify_slack(block)         # added another line\n            output = execute(block)\n            auto_git_add(block)         # yet another line\n            # ... the loop is unrecognizable\n```\n\nWhat you want to extend is the Agent's behavior, but what you're modifying is the loop itself. The loop should be a stable core; extensions should hang on the outside.\n\n---\n\n## The Solution\n\n![Hooks Overview](/course-assets/s04_hooks/hooks-overview.en.svg)\n\nThe s03 loop and permission logic are fully preserved. The only change is moving `check_permission()` from inside the loop body onto a hook. The loop no longer directly calls any check function. Instead it calls `trigger_hooks(\"PreToolUse\", block)`, and the registry decides what to run.\n\nFour events, covering a complete agent cycle:\n\n| Event | Trigger Timing | Typical Use |\n|-------|---------------|-------------|\n| UserPromptSubmit | After user input, before entering LLM | Input validation, context injection |\n| PreToolUse | Before tool execution | Permission checks, logging |\n| PostToolUse | After tool execution | Side effects (auto git add etc.), output checking |\n| Stop | When the loop is about to exit | Cleanup, decide whether the loop continues |\n\nExtensions are added via `register_hook()`. The loop only calls `trigger_hooks()`.\n\n---\n\n## How It Works\n\n**Hook registry**: a dict mapping event names to callback lists.\n\n```python\nHOOKS = {\n    \"UserPromptSubmit\": [],\n    \"PreToolUse\": [],\n    \"PostToolUse\": [],\n    \"Stop\": [],\n}\n\ndef register_hook(event: str, callback):\n    HOOKS[event].append(callback)\n\ndef trigger_hooks(event: str, *args):\n    for callback in HOOKS[event]:\n        result = callback(*args)\n        if result is not None:   # return value ≠ None → hook says \"stop\"\n            return result\n    return None\n```\n\nWhen `PreToolUse` returns non-None, the current tool execution is blocked. When `Stop` returns non-None, the loop continues. Return values from `UserPromptSubmit` and `PostToolUse` do not affect control flow.\n\n**UserPromptSubmit** triggers after user input and before entering the LLM. The following hook records the current working directory:\n\n```python\ndef context_inject_hook(query: str) -> str | None:\n    \"\"\"Inject current working directory info into every prompt.\"\"\"\n    print(f\"\\033[90m[HOOK] UserPromptSubmit: working in {WORKDIR}\\033[0m\")\n    return None   # return None = no modification, let prompt through\n\nregister_hook(\"UserPromptSubmit\", context_inject_hook)\n```\n\nIn the main loop, triggered right after user input:\n\n```python\nquery = input(\"s04 >> \")\ntrigger_hooks(\"UserPromptSubmit\", query)   # ← before entering LLM\nhistory.append({\"role\": \"user\", \"content\": query})\nagent_loop(history)\n```\n\n**PreToolUse / PostToolUse**, hooks before and after tool execution. s03's permission check logic is now wrapped as a PreToolUse hook, plus a logging hook and a large-output reminder:\n\n```python\n# PreToolUse: permission check (s03 logic, moved from loop to hook)\ndef permission_hook(block):\n    if block.name == \"bash\":\n        for pattern in DENY_LIST:\n            if pattern in block.input.get(\"command\", \"\"):\n                return \"Permission denied by deny list\"\n    if block.name in (\"read_file\", \"write_file\", \"edit_file\"):\n        path = block.input.get(\"path\", \"\")\n        if not (WORKDIR / path).resolve().is_relative_to(WORKDIR):\n            choice = input(\"   Allow? [y/N] \").strip().lower()\n            if choice not in (\"y\", \"yes\"):\n                return \"Permission denied by user\"\n    return None\n\n# PreToolUse: logging\ndef log_hook(block):\n    print(f\"[HOOK] {block.name}(...)\")\n\n# PostToolUse: large output reminder\ndef large_output_hook(block, output):\n    if len(str(output)) > 100000:\n        print(f\"[HOOK] ⚠ Large output from {block.name}\")\n\nregister_hook(\"PreToolUse\", permission_hook)\nregister_hook(\"PreToolUse\", log_hook)\nregister_hook(\"PostToolUse\", large_output_hook)\n```\n\n**Stop** triggers when the loop is about to exit (`stop_reason != \"tool_use\"`). The following hook prints a cleanup summary:\n\n```python\ndef summary_hook(messages: list) -> str | None:\n    \"\"\"Print a summary when the loop is about to stop.\"\"\"\n    tool_count = sum(1 for m in messages\n                     for b in (m.get(\"content\") if isinstance(m.get(\"content\"), list) else [])\n                     if isinstance(b, dict) and b.get(\"type\") == \"tool_result\")\n    print(f\"\\033[90m[HOOK] Stop: session used {tool_count} tool calls\\033[0m\")\n    return None   # return None = allow stop, return string = force continuation\n\nregister_hook(\"Stop\", summary_hook)\n```\n\nIn agent_loop, triggered before exit:\n\n```python\nif response.stop_reason != \"tool_use\":\n    force = trigger_hooks(\"Stop\", messages)   # ← before exiting\n    if force:\n        # hook returned a message → inject it and continue\n        messages.append({\"role\": \"user\", \"content\": force})\n        continue\n    return\n```\n\n**Only one change in the loop**: s03 directly called `check_permission(block)`, s04 replaces it with `trigger_hooks(\"PreToolUse\", block)`:\n\n```python\nfor block in response.content:\n    if block.type != \"tool_use\":\n        continue\n\n    # s03: if not check_permission(block): ...\n    # s04: hooks replace hardcoding\n    blocked = trigger_hooks(\"PreToolUse\", block)\n    if blocked:\n        results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id,\n                        \"content\": str(blocked)})\n        continue\n\n    handler = TOOL_HANDLERS.get(block.name)\n    output = handler(**block.input) if handler else f\"Unknown: {block.name}\"\n\n    trigger_hooks(\"PostToolUse\", block, output)\n\n    results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id,\n                    \"content\": output})\n```\n\nFour hooks cover the critical nodes of the agent cycle: input → before execution → after execution → exit. The loop only calls trigger_hooks(); all logic lives in hook callbacks.\n\n---\n\n## Changes from s03\n\n| Component | Before (s03) | After (s04) |\n|-----------|-------------|-------------|\n| Extension method | check_permission() hardcoded in the loop | HOOKS registry + trigger_hooks() |\n| New functions | — | register_hook, trigger_hooks |\n| Hook callbacks | — | context_inject_hook, permission_hook, log_hook, large_output_hook, summary_hook |\n| Loop | Directly calls check_permission() | Calls trigger_hooks(\"PreToolUse\", ...) |\n| Exit control | None | trigger_hooks(\"Stop\", ...) can prevent exit |\n| Input interception | None | trigger_hooks(\"UserPromptSubmit\", ...) can inject context |\n\n---\n\n## Try It\n\n```sh\ncd learn-claude-code\npython s04_hooks/code.py\n```\n\nTry these prompts:\n\n1. `Read the file README.md` (should pass directly, observe hook logs)\n2. `Create a file called test.txt` (after creation, observe if PostToolUse fires)\n3. `Delete all temporary files in /tmp` (bash + rm triggers permission hook)\n\nWhat to watch for: Before each tool execution, does the `[HOOK]` log appear? When permission is denied, was it intercepted by a hook or hardcoded in the loop?\n\n---\n\n## What's Next\n\nThe Agent can now safely execute operations. But does it ever stop to think \"what should I do first, and what next?\" Given a complex task, does it jump straight in, or plan first?\n\n→ s05 TodoWrite: Give the Agent a planning tool. Make a list first, then execute.\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s04",
    "locale": "zh",
    "title": "s04: Hooks — 挂在循环上，不写进循环里",
    "content": "# s04: Hooks — 挂在循环上，不写进循环里\n\ns01 → s02 → s03 → `s04` → [s05](/zh/s05) → s06 → ... → s20 → s21\n\n> *\"挂在循环上, 不写进循环里\"* — hook 在工具执行前后注入扩展逻辑。\n>\n> **Harness 层**: hook — 扩展点不侵入循环。\n\n---\n\n## 问题\n\ns03 的 Agent 有权限检查了。但每次加一个新检查，比如\"记录每次 bash 调用\"、\"操作后自动 git add\"，都要修改 `agent_loop` 函数。\n\n循环很快就变成了这样：\n\n```python\ndef agent_loop(messages):\n    while True:\n        # ... LLM call ...\n        for block in response.content:\n            if block.type != \"tool_use\":\n                continue\n            log_to_file(block)          # 加一行\n            check_permission(block)     # 加一行\n            notify_slack(block)         # 又加一行\n            output = execute(block)\n            auto_git_add(block)         # 再加一行\n            # ... 很快循环就认不出来了\n```\n\n你想扩展的是 Agent 的行为，但你改的却是循环本身。循环应该是一个稳定的核心，扩展应该挂在外面。\n\n---\n\n## 解决方案\n\n![Hooks Overview](/course-assets/s04_hooks/hooks-overview.svg)\n\ns03 的循环和权限逻辑完全保留。唯一的变动是把 `check_permission()` 从循环体内移到了 hook 上，循环不再直接调用任何检查函数，改为 `trigger_hooks(\"PreToolUse\", block)`，由注册表决定跑什么。\n\n四个事件，覆盖一个完整的 agent cycle：\n\n| 事件 | 触发时机 | 典型用途 |\n|------|---------|---------|\n| UserPromptSubmit | 用户输入提交后、进入 LLM 前 | 输入验证、注入上下文 |\n| PreToolUse | 工具执行前 | 权限检查、日志记录 |\n| PostToolUse | 工具执行后 | 副作用（自动 git add 等）、输出检查 |\n| Stop | 循环即将退出时 | 收尾清理、决定是否继续循环 |\n\n扩展通过 `register_hook()` 添加，循环只调用 `trigger_hooks()`。\n\n---\n\n## 工作原理\n\n**hook 注册表**：一个字典，事件名映射到回调列表。\n\n```python\nHOOKS = {\n    \"UserPromptSubmit\": [],\n    \"PreToolUse\": [],\n    \"PostToolUse\": [],\n    \"Stop\": [],\n}\n\ndef register_hook(event: str, callback):\n    HOOKS[event].append(callback)\n\ndef trigger_hooks(event: str, *args):\n    for callback in HOOKS[event]:\n        result = callback(*args)\n        if result is not None:   # 返回值 ≠ None → hook 说\"停\"\n            return result\n    return None\n```\n\n`PreToolUse` 返回非 `None` 时，本次工具执行被阻止；`Stop` 返回非 `None` 时，循环继续。`UserPromptSubmit` 和 `PostToolUse` 的返回值不参与控制流。\n\n**UserPromptSubmit** 在用户输入提交后、进入 LLM 前触发。以下 hook 记录当前工作目录：\n\n```python\ndef context_inject_hook(query: str) -> str | None:\n    \"\"\"Inject current working directory info into every prompt.\"\"\"\n    print(f\"\\033[90m[HOOK] UserPromptSubmit: working in {WORKDIR}\\033[0m\")\n    return None   # return None = no modification, let prompt through\n\nregister_hook(\"UserPromptSubmit\", context_inject_hook)\n```\n\n在主循环中，用户输入后立即触发：\n\n```python\nquery = input(\"s04 >> \")\ntrigger_hooks(\"UserPromptSubmit\", query)   # ← 进入 LLM 之前\nhistory.append({\"role\": \"user\", \"content\": query})\nagent_loop(history)\n```\n\n**PreToolUse / PostToolUse**，工具执行前后的 hook。s03 的权限检查逻辑现在包装成 PreToolUse hook，再加一个日志 hook 和一个大输出提醒：\n\n```python\n# PreToolUse: 权限检查（s03 的逻辑，从循环移到 hook）\ndef permission_hook(block):\n    if block.name == \"bash\":\n        for pattern in DENY_LIST:\n            if pattern in block.input.get(\"command\", \"\"):\n                return \"Permission denied by deny list\"\n    if block.name in (\"read_file\", \"write_file\", \"edit_file\"):\n        path = block.input.get(\"path\", \"\")\n        if not (WORKDIR / path).resolve().is_relative_to(WORKDIR):\n            choice = input(\"   Allow? [y/N] \").strip().lower()\n            if choice not in (\"y\", \"yes\"):\n                return \"Permission denied by user\"\n    return None\n\n# PreToolUse: 日志\ndef log_hook(block):\n    print(f\"[HOOK] {block.name}(...)\")\n\n# PostToolUse: 大文件提醒\ndef large_output_hook(block, output):\n    if len(str(output)) > 100000:\n        print(f\"[HOOK] ⚠ Large output from {block.name}\")\n\nregister_hook(\"PreToolUse\", permission_hook)\nregister_hook(\"PreToolUse\", log_hook)\nregister_hook(\"PostToolUse\", large_output_hook)\n```\n\n**Stop** 在循环即将退出时触发（`stop_reason != \"tool_use\"`）。以下 hook 打印收尾统计：\n\n```python\ndef summary_hook(messages: list) -> str | None:\n    \"\"\"Print a summary when the loop is about to stop.\"\"\"\n    tool_count = sum(1 for m in messages\n                     for b in (m.get(\"content\") if isinstance(m.get(\"content\"), list) else [])\n                     if isinstance(b, dict) and b.get(\"type\") == \"tool_result\")\n    print(f\"\\033[90m[HOOK] Stop: session used {tool_count} tool calls\\033[0m\")\n    return None   # return None = allow stop, return string = force continuation\n\nregister_hook(\"Stop\", summary_hook)\n```\n\n在 agent_loop 中，退出前触发：\n\n```python\nif response.stop_reason != \"tool_use\":\n    force = trigger_hooks(\"Stop\", messages)   # ← 退出之前\n    if force:\n        # hook returned a message → inject it and continue\n        messages.append({\"role\": \"user\", \"content\": force})\n        continue\n    return\n```\n\n**循环里只改了一处**：s03 直接调用 `check_permission(block)`，s04 改为 `trigger_hooks(\"PreToolUse\", block)`：\n\n```python\nfor block in response.content:\n    if block.type != \"tool_use\":\n        continue\n\n    # s03: if not check_permission(block): ...\n    # s04: hook 替代硬编码\n    blocked = trigger_hooks(\"PreToolUse\", block)\n    if blocked:\n        results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id,\n                        \"content\": str(blocked)})\n        continue\n\n    handler = TOOL_HANDLERS.get(block.name)\n    output = handler(**block.input) if handler else f\"Unknown: {block.name}\"\n\n    trigger_hooks(\"PostToolUse\", block, output)\n\n    results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id,\n                    \"content\": output})\n```\n\n四个 hook 覆盖了 agent cycle 的关键节点：输入→执行前→执行后→退出。循环只负责调用 trigger_hooks()，具体逻辑全在 hook 回调里。\n\n---\n\n## 相对 s03 的变更\n\n| 组件 | 之前 (s03) | 之后 (s04) |\n|------|-----------|-----------|\n| 扩展方式 | check_permission() 硬编码在循环里 | HOOKS 注册表 + trigger_hooks() |\n| 新函数 | — | register_hook, trigger_hooks |\n| hook 回调 | — | context_inject_hook, permission_hook, log_hook, large_output_hook, summary_hook |\n| 循环 | 直接调用 check_permission() | 调用 trigger_hooks(\"PreToolUse\", ...) |\n| 退出控制 | 无 | trigger_hooks(\"Stop\", ...) 可阻止退出 |\n| 输入拦截 | 无 | trigger_hooks(\"UserPromptSubmit\", ...) 可注入上下文 |\n\n---\n\n## 试一下\n\n```sh\ncd learn-claude-code\npython s04_hooks/code.py\n```\n\n试试这些 prompt：\n\n1. `Read the file README.md`（应该直接通过，观察 hook 日志）\n2. `Create a file called test.txt`（通过后观察 PostToolUse 是否触发）\n3. `Delete all temporary files in /tmp`（bash + rm 触发权限 hook）\n\n观察重点：每次工具执行前，是否出现了 `[HOOK]` 日志？权限被拒时，是 hook 拦截的还是循环里硬编码的？\n\n---\n\n## 接下来\n\nAgent 现在能安全执行操作了。但它有没有停下来想过\"我应该先做什么，再做什么\"？给它一个复杂任务，它是一上来就动手，还是先列个计划？\n\ns05 TodoWrite → 给 Agent 一个计划工具。先列清单，再做。\n\n\n<!-- translation-sync: zh@v1, en@v0, ja@v0 -->\n"
  },
  {
    "version": "s04",
    "locale": "ja",
    "title": "s04: Hooks — ループに掛ける、ループには書き込まない",
    "content": "# s04: Hooks — ループに掛ける、ループには書き込まない\n\ns01 → s02 → s03 → `s04` → [s05](/ja/s05) → s06 → ... → s20 → s21\n\n> *\"ループに掛ける、ループには書き込まない\"* — フックがツール実行の前後に拡張ロジックを注入する。\n>\n> **Harness レイヤー**: フック — ループを侵襲しない拡張ポイント。\n\n---\n\n## 課題\n\ns03 の Agent には権限チェックがある。しかし新しいチェックを追加するたび、「bash 呼び出しを毎回ログに記録」「操作後に自動 git add」、`agent_loop` 関数を修正する必要がある。\n\nループはすぐにこうなる：\n\n```python\ndef agent_loop(messages):\n    while True:\n        # ... LLM call ...\n        for block in response.content:\n            if block.type != \"tool_use\":\n                continue\n            log_to_file(block)          # 一行追加\n            check_permission(block)     # 一行追加\n            notify_slack(block)         # さらに一行追加\n            output = execute(block)\n            auto_git_add(block)         # さらに一行追加\n            # ... もうループが見えない\n```\n\n拡張したいのは Agent の振る舞いなのに、変更しているのはループそのもの。ループは安定した核心であるべき。拡張は外側に掛ける。\n\n---\n\n## ソリューション\n\n![Hooks Overview](/course-assets/s04_hooks/hooks-overview.ja.svg)\n\ns03 のループと権限ロジックは完全に保持される。唯一の変更点は `check_permission()` をループ本体内からフックに移動したこと。ループはもうチェック関数を直接呼び出さず、代わりに `trigger_hooks(\"PreToolUse\", block)` を呼び、登録済みのフックが何を実行するかを決める。\n\n4 つのイベントで、完全な agent cycle をカバー：\n\n| イベント | 発火タイミング | 典型的な用途 |\n|----------|--------------|-------------|\n| UserPromptSubmit | ユーザー入力後、LLM に入る前 | 入力バリデーション、コンテキスト注入 |\n| PreToolUse | ツール実行前 | 権限チェック、ログ記録 |\n| PostToolUse | ツール実行後 | 副作用（自動 git add など）、出力チェック |\n| Stop | ループが終了する直前 | 後処理、ループを続行するかの判断 |\n\n拡張は `register_hook()` で追加する。ループは `trigger_hooks()` を呼ぶだけ。\n\n---\n\n## 仕組み\n\n**フック登録簿**：イベント名をコールバックリストにマッピングする辞書。\n\n```python\nHOOKS = {\n    \"UserPromptSubmit\": [],\n    \"PreToolUse\": [],\n    \"PostToolUse\": [],\n    \"Stop\": [],\n}\n\ndef register_hook(event: str, callback):\n    HOOKS[event].append(callback)\n\ndef trigger_hooks(event: str, *args):\n    for callback in HOOKS[event]:\n        result = callback(*args)\n        if result is not None:   # 戻り値 ≠ None → フックが「止め」と指示\n            return result\n    return None\n```\n\n`PreToolUse` が `None` 以外を返すと、現在のツール実行は中止される。`Stop` が `None` 以外を返すと、ループは続行する。`UserPromptSubmit` と `PostToolUse` の戻り値は制御フローに影響しない。\n\n**UserPromptSubmit** はユーザー入力後、LLM に入る前に発火する。以下の hook は現在の作業ディレクトリを記録する：\n\n```python\ndef context_inject_hook(query: str) -> str | None:\n    \"\"\"Inject current working directory info into every prompt.\"\"\"\n    print(f\"\\033[90m[HOOK] UserPromptSubmit: working in {WORKDIR}\\033[0m\")\n    return None   # return None = 変更なし、プロンプトを通す\n\nregister_hook(\"UserPromptSubmit\", context_inject_hook)\n```\n\nメインループでは、ユーザー入力直後に発火：\n\n```python\nquery = input(\"s04 >> \")\ntrigger_hooks(\"UserPromptSubmit\", query)   # ← LLM に入る前\nhistory.append({\"role\": \"user\", \"content\": query})\nagent_loop(history)\n```\n\n**PreToolUse / PostToolUse**、ツール実行の前後のフック。s03 の権限チェックロジックは PreToolUse フックに包まれ、さらにログフックと大出力リマインダーが追加される：\n\n```python\n# PreToolUse: 権限チェック（s03 のロジック、ループからフックに移動）\ndef permission_hook(block):\n    if block.name == \"bash\":\n        for pattern in DENY_LIST:\n            if pattern in block.input.get(\"command\", \"\"):\n                return \"Permission denied by deny list\"\n    if block.name in (\"read_file\", \"write_file\", \"edit_file\"):\n        path = block.input.get(\"path\", \"\")\n        if not (WORKDIR / path).resolve().is_relative_to(WORKDIR):\n            choice = input(\"   Allow? [y/N] \").strip().lower()\n            if choice not in (\"y\", \"yes\"):\n                return \"Permission denied by user\"\n    return None\n\n# PreToolUse: ログ\ndef log_hook(block):\n    print(f\"[HOOK] {block.name}(...)\")\n\n# PostToolUse: 大ファイルリマインダー\ndef large_output_hook(block, output):\n    if len(str(output)) > 100000:\n        print(f\"[HOOK] ⚠ Large output from {block.name}\")\n\nregister_hook(\"PreToolUse\", permission_hook)\nregister_hook(\"PreToolUse\", log_hook)\nregister_hook(\"PostToolUse\", large_output_hook)\n```\n\n**Stop** はループが終了する直前に発火する（`stop_reason != \"tool_use\"`）。以下の hook は終了時の統計を出力する：\n\n```python\ndef summary_hook(messages: list) -> str | None:\n    \"\"\"Print a summary when the loop is about to stop.\"\"\"\n    tool_count = sum(1 for m in messages\n                     for b in (m.get(\"content\") if isinstance(m.get(\"content\"), list) else [])\n                     if isinstance(b, dict) and b.get(\"type\") == \"tool_result\")\n    print(f\"\\033[90m[HOOK] Stop: session used {tool_count} tool calls\\033[0m\")\n    return None   # return None = 終了を許可、return 文字列 = 強制続行\n\nregister_hook(\"Stop\", summary_hook)\n```\n\nagent_loop 内では、終了前に発火：\n\n```python\nif response.stop_reason != \"tool_use\":\n    force = trigger_hooks(\"Stop\", messages)   # ← 終了する前に\n    if force:\n        # フックがメッセージを返した → 注入して続行\n        messages.append({\"role\": \"user\", \"content\": force})\n        continue\n    return\n```\n\n**ループ内で変更されたのは一箇所だけ**：s03 は直接 `check_permission(block)` を呼び出していたが、s04 は `trigger_hooks(\"PreToolUse\", block)` に置き換えた：\n\n```python\nfor block in response.content:\n    if block.type != \"tool_use\":\n        continue\n\n    # s03: if not check_permission(block): ...\n    # s04: フックがハードコードを代替\n    blocked = trigger_hooks(\"PreToolUse\", block)\n    if blocked:\n        results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id,\n                        \"content\": str(blocked)})\n        continue\n\n    handler = TOOL_HANDLERS.get(block.name)\n    output = handler(**block.input) if handler else f\"Unknown: {block.name}\"\n\n    trigger_hooks(\"PostToolUse\", block, output)\n\n    results.append({\"type\": \"tool_result\", \"tool_use_id\": block.id,\n                    \"content\": output})\n```\n\n4 つのフックが agent cycle の重要ノードをカバー：入力→実行前→実行後→終了。ループは trigger_hooks() を呼ぶだけで、具体的なロジックは全てフックコールバックにある。\n\n---\n\n## s03 からの変更\n\n| コンポーネント | 変更前 (s03) | 変更後 (s04) |\n|--------------|-------------|-------------|\n| 拡張方式 | check_permission() をループ内にハードコード | HOOKS 登録簿 + trigger_hooks() |\n| 新規関数 | — | register_hook, trigger_hooks |\n| フックコールバック | — | context_inject_hook, permission_hook, log_hook, large_output_hook, summary_hook |\n| ループ | check_permission() を直接呼び出し | trigger_hooks(\"PreToolUse\", ...) を呼び出し |\n| 終了制御 | なし | trigger_hooks(\"Stop\", ...) が終了を阻止可能 |\n| 入力横取り | なし | trigger_hooks(\"UserPromptSubmit\", ...) がコンテキスト注入可能 |\n\n---\n\n## 試してみよう\n\n```sh\ncd learn-claude-code\npython s04_hooks/code.py\n```\n\n以下のプロンプトを試してみよう：\n\n1. `Read the file README.md`（そのまま通過するはず、フックログを観察）\n2. `Create a file called test.txt`（作成後、PostToolUse が発火するか観察）\n3. `Delete all temporary files in /tmp`（bash + rm で権限フックが発動）\n\n観察のポイント：各ツール実行前に `[HOOK]` ログが表示されるか？ 権限が拒否されたとき、フックが拦截したのか、ループ内のハードコードが拦截したのか？\n\n---\n\n## 次へ\n\nAgent は安全に操作を実行できるようになった。しかし「まず何をして、次に何をすべきか」を立ち止まって考えたことはあるか？ 複雑なタスクを与えたとき、すぐに取り掛かるのか、まず計画を立てるのか？\n\n→ s05 TodoWrite：Agent に計画ツールを与える。まずリストを作り、それから実行。\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s05",
    "locale": "en",
    "title": "s05: TodoWrite — An Agent Without a Plan Drifts Off Course",
    "content": "# s05: TodoWrite — An Agent Without a Plan Drifts Off Course\n\ns01 → s02 → s03 → s04 → `s05` → [s06](/en/s06) → s07 → ... → s20 → s21\n\n> *\"An agent without a plan goes wherever the wind blows\"* — List the steps first, then execute. Complex tasks are less likely to miss steps.\n>\n> **Harness Layer**: Planning — Let the Agent think before it acts.\n\n---\n\n## The Problem\n\nGive the Agent a complex task: \"Rename all Python files to snake_case, run tests, and fix failures.\"\n\nThe Agent starts working, renames 3 files, runs a test, finds 2 failures, starts fixing. While fixing, it forgets the original goal was \"rename to snake_case\", the test failures have consumed all its attention.\n\nThe longer the conversation, the worse it gets: tool results keep filling the context, diluting the system prompt's influence. A 10-step refactoring: after steps 1-3, the Agent starts improvising because steps 4-10 have been pushed out of its attention.\n\n---\n\n## The Solution\n\n![Todo Overview](/course-assets/s05_todo_write/todo-overview.en.svg)\n\nThe minimal hook structure from the previous chapter is preserved, focusing on the new `todo_write` tool and reminder mechanism. `todo_write` does no actual work, can't read files or run commands, it simply lets the Agent organize its thoughts before diving in.\n\nThe dispatch mechanism is unchanged; the new tool is still routed through `TOOL_HANDLERS[block.name]`. However, to demonstrate the todo reminder, a counter was added to the loop: after 3 consecutive rounds without calling `todo_write`, a reminder is injected.\n\n---\n\n## How It Works\n\n**The todo_write tool** accepts a list with statuses, keeps it in the current process memory, and displays progress in the terminal:\n\n```python\nCURRENT_TODOS: list[dict] = []\n\ndef run_todo_write(todos: list) -> str:\n    global CURRENT_TODOS\n    CURRENT_TODOS = todos\n\n    lines = [\"\\n## Current Tasks\"]\n    for t in CURRENT_TODOS:\n        icon = {\"pending\": \" \", \"in_progress\": \"▸\", \"completed\": \"✓\"}[t[\"status\"]]\n        lines.append(f\"  [{icon}] {t['content']}\")\n    print(\"\\n\".join(lines))\n    return f\"Updated {len(CURRENT_TODOS)} tasks\"\n```\n\nThe tool definition joins the other 5 in the dispatch map:\n\n```python\nTOOLS = [\n    {\"name\": \"bash\",       ...},\n    {\"name\": \"read_file\",  ...},\n    {\"name\": \"write_file\", ...},\n    {\"name\": \"edit_file\",  ...},\n    {\"name\": \"glob\",       ...},\n    # s05: new entry\n    {\"name\": \"todo_write\", \"description\": \"Create and manage a task list ...\",\n     \"input_schema\": {\n         \"type\": \"object\",\n         \"properties\": {\n             \"todos\": {\n                 \"type\": \"array\",\n                 \"items\": {\n                     \"type\": \"object\",\n                     \"properties\": {\n                         \"content\": {\"type\": \"string\"},\n                         \"status\": {\"type\": \"string\", \"enum\": [\"pending\", \"in_progress\", \"completed\"]},\n                     },\n                 },\n             },\n         },\n     },\n    },\n]\n\nTOOL_HANDLERS[\"todo_write\"] = run_todo_write\n```\n\n**Nag reminder**: when the model has not called `todo_write` for 3 consecutive rounds, a reminder is automatically injected:\n\n```python\nif rounds_since_todo >= 3 and messages:\n    messages.append({\n        \"role\": \"user\",\n        \"content\": \"<reminder>Update your todos.</reminder>\",\n    })\n    rounds_since_todo = 0\n```\n\nTypical flow when the Agent receives a task: first call `todo_write` to list all steps (all `pending`) → pick one step, set it to `in_progress` → complete it, set to `completed` → look at the next `pending` → continue. After 3 rounds without `todo_write`, the loop appends a reminder before the next LLM call.\n\n**Key insight**: todo_write doesn't give the Agent any additional **execution capability**. What it adds is **planning capability**.\n\n---\n\n## Changes from s04\n\n| Component | Before (s04) | After (s05) |\n|-----------|-------------|-------------|\n| Tool count | 5 (bash, read, write, edit, glob) | 6 (+todo_write) |\n| Planning | None | Stateful TODO list + nag reminder |\n| SYSTEM prompt | Generic prompt | Added \"plan before executing\" guidance |\n| Loop | Unchanged | Dispatch unchanged, added rounds_since_todo counter and reminder injection |\n\n---\n\n## Try It\n\n```sh\ncd learn-claude-code\npython s05_todo_write/code.py\n```\n\nTry these prompts:\n\n1. `Refactor s05_todo_write/example/hello.py: add type hints, docstrings, and a main guard` (should list 3 steps first, then execute)\n2. `Create a Python package under s05_todo_write/example/demo_pkg with __init__.py, utils.py, and tests/test_utils.py`\n3. `Review Python files under s05_todo_write/example and fix any style issues`\n\nWhat to watch for: Was the first tool call `todo_write`? How many TODO steps were listed? Did statuses move from `pending` to `in_progress` / `completed` during execution?\n\n---\n\n## What's Next\n\nThe Agent can plan now. But if a task is too large, say \"refactor the entire auth module\", a TODO list alone isn't enough. That task is itself a collection of dozens of subtasks that would drown in a single conversation's context.\n\n→ s06 Subagent: Break large tasks into subtasks, each handled by an independent Agent with its own clean context, no cross-contamination.\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s05",
    "locale": "zh",
    "title": "s05: TodoWrite — 没有计划的 Agent，做着做着就偏了",
    "content": "# s05: TodoWrite — 没有计划的 Agent，做着做着就偏了\n\ns01 → s02 → s03 → s04 → `s05` → [s06](/zh/s06) → s07 → ... → s20 → s21\n\n> *\"没有计划的 agent 走哪算哪\"* — 先列步骤再动手，长任务更不容易漏项。\n>\n> **Harness 层**: 规划 — 让 Agent 在动手之前先想清楚。\n\n---\n\n## 问题\n\n给 Agent 一个复杂任务：\"把所有 Python 文件改成 snake_case 命名，然后跑测试，修好失败。\"\n\nAgent 开始干活，改了 3 个文件，跑了个测试，发现 2 个失败，开始修。修着修着，它忘了最初是\"改成 snake_case\"，测试失败把注意力全吸走了。\n\n对话越长越严重：工具结果不断填满上下文，系统提示的影响力被稀释。一个 10 步重构，做完 1-3 步就开始即兴发挥，因为 4-10 步已经被挤出注意力了。\n\n---\n\n## 解决方案\n\n![Todo Overview](/course-assets/s05_todo_write/todo-overview.svg)\n\n保留上一章的最小 hook 结构，重点看新增的 `todo_write` 工具和 reminder 机制。`todo_write` 本身不做任何实际工作，不能读文件、不能跑命令，只是让 Agent 在动手之前先理清思路。\n\ndispatch 机制不变，新工具仍然走 `TOOL_HANDLERS[block.name]` 分发。但为了演示 todo reminder，循环里加了一个计数器：连续 3 轮没调 `todo_write` 就注入一条提醒。\n\n---\n\n## 工作原理\n\n**todo_write 工具**，接收一个带状态的列表，保存在当前进程内存中，同时在终端显示进度：\n\n```python\nCURRENT_TODOS: list[dict] = []\n\ndef run_todo_write(todos: list) -> str:\n    global CURRENT_TODOS\n    CURRENT_TODOS = todos\n\n    lines = [\"\\n## Current Tasks\"]\n    for t in CURRENT_TODOS:\n        icon = {\"pending\": \" \", \"in_progress\": \"▸\", \"completed\": \"✓\"}[t[\"status\"]]\n        lines.append(f\"  [{icon}] {t['content']}\")\n    print(\"\\n\".join(lines))\n    return f\"Updated {len(CURRENT_TODOS)} tasks\"\n```\n\n工具定义和其他 5 个工具一起加入 dispatch map：\n\n```python\nTOOLS = [\n    {\"name\": \"bash\",       ...},\n    {\"name\": \"read_file\",  ...},\n    {\"name\": \"write_file\", ...},\n    {\"name\": \"edit_file\",  ...},\n    {\"name\": \"glob\",       ...},\n    # s05: 新增一条\n    {\"name\": \"todo_write\", \"description\": \"Create and manage a task list ...\",\n     \"input_schema\": {\n         \"type\": \"object\",\n         \"properties\": {\n             \"todos\": {\n                 \"type\": \"array\",\n                 \"items\": {\n                     \"type\": \"object\",\n                     \"properties\": {\n                         \"content\": {\"type\": \"string\"},\n                         \"status\": {\"type\": \"string\", \"enum\": [\"pending\", \"in_progress\", \"completed\"]},\n                     },\n                 },\n             },\n         },\n     },\n    },\n]\n\nTOOL_HANDLERS[\"todo_write\"] = run_todo_write\n```\n\n**Nag reminder**：模型连续 3 轮未调用 `todo_write` 时，自动注入提醒：\n\n```python\nif rounds_since_todo >= 3 and messages:\n    messages.append({\n        \"role\": \"user\",\n        \"content\": \"<reminder>Update your todos.</reminder>\",\n    })\n    rounds_since_todo = 0\n```\n\nAgent 收到任务后的典型流程：先调 `todo_write` 列出所有步骤（全 `pending`）→ 做一个步骤，改成 `in_progress` → 做完改成 `completed` → 看下一个 `pending` → 继续。连续 3 轮没有调用 `todo_write` 时，循环会在下一次 LLM 调用前追加一条 reminder。\n\n**关键洞察**：todo_write 不给 Agent 增加任何**执行能力**。它增加的是**规划能力**。\n\n---\n\n## 相对 s04 的变更\n\n| 组件 | 之前 (s04) | 之后 (s05) |\n|------|-----------|-----------|\n| 工具数量 | 5 (bash, read, write, edit, glob) | 6 (+todo_write) |\n| 规划能力 | 无 | 带状态的 TODO 列表 + nag reminder |\n| SYSTEM 提示 | 通用提示 | 加入 \"先计划再执行\" 引导 |\n| 循环 | 不变 | dispatch 不变，新增 rounds_since_todo 计数器和 reminder 注入 |\n\n---\n\n## 试一下\n\n```sh\ncd learn-claude-code\npython s05_todo_write/code.py\n```\n\n试试这些 prompt：\n\n1. `Refactor s05_todo_write/example/hello.py: add type hints, docstrings, and a main guard`（先列 3 步再执行）\n2. `Create a Python package under s05_todo_write/example/demo_pkg with __init__.py, utils.py, and tests/test_utils.py`\n3. `Review Python files under s05_todo_write/example and fix any style issues`\n\n观察重点：第一次工具调用是不是 `todo_write`？TODO 列了几步？执行过程中状态有没有从 `pending` 变成 `in_progress` / `completed`？\n\n---\n\n## 接下来\n\nAgent 能计划了。但如果一个任务太大，比如\"重构整个认证模块\"，光靠 TODO 列表不够。这个任务本身就是几十个小任务的集合，放在同一个对话里会被上下文淹没。\n\ns06 Subagent → 把大任务拆成子任务，每个子任务派一个独立的 Agent。它们有自己的干净上下文，不会互相污染。\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s05",
    "locale": "ja",
    "title": "s05: TodoWrite — 計画なき Agent は途中で道を外れる",
    "content": "# s05: TodoWrite — 計画なき Agent は途中で道を外れる\n\ns01 → s02 → s03 → s04 → `s05` → [s06](/ja/s06) → s07 → ... → s20 → s21\n\n> *\"計画なき agent は風の向くままに\"* — まず手順を列挙してから実行。長いタスクで見落としが減る。\n>\n> **Harness レイヤー**: 計画 — Agent が行動する前に考えさせる。\n\n---\n\n## 課題\n\nAgent に複雑なタスクを与える：「全 Python ファイルを snake_case にリネームし、テストを実行し、失敗を修正して。」\n\nAgent は作業を開始する。3 つのファイルをリネーム、テストを実行、2 つの失敗を発見、修正を開始。修正しているうちに、本来の目的が「snake_case にリネーム」だったことを忘れる。テストの失敗に注意を全て持っていかれる。\n\n会話が長くなるほど悪化する：ツールの結果がコンテキストを埋め続け、システムプロンプトの影響力が希釈される。10 ステップのリファクタリング：ステップ 1-3 を終えた時点で Agent は即興で動き始める。ステップ 4-10 は既に注意の外に追い出されているから。\n\n---\n\n## ソリューション\n\n![Todo Overview](/course-assets/s05_todo_write/todo-overview.ja.svg)\n\n前章の最小フック構造を保持し、本章では新規の `todo_write` ツールとリマインダー機構に注目する。`todo_write` は実際の作業を何もしない。ファイルを読めない、コマンドを実行できない。Agent が手を動かす前に思考を整理できるようにするだけ。\n\nディスパッチ機構は変わらず、新ツールも `TOOL_HANDLERS[block.name]` を経由する。ただし、todo リマインダーのデモのため、ループにカウンターを追加した：連続 3 ラウンド `todo_write` を呼び出さないとリマインダーが注入される。\n\n---\n\n## 仕組み\n\n**todo_write ツール**は、ステータス付きのリストを受け取り、現在のプロセスメモリに保持し、端末に進捗を表示する：\n\n```python\nCURRENT_TODOS: list[dict] = []\n\ndef run_todo_write(todos: list) -> str:\n    global CURRENT_TODOS\n    CURRENT_TODOS = todos\n\n    lines = [\"\\n## Current Tasks\"]\n    for t in CURRENT_TODOS:\n        icon = {\"pending\": \" \", \"in_progress\": \"▸\", \"completed\": \"✓\"}[t[\"status\"]]\n        lines.append(f\"  [{icon}] {t['content']}\")\n    print(\"\\n\".join(lines))\n    return f\"Updated {len(CURRENT_TODOS)} tasks\"\n```\n\nツール定義は他の 5 つと一緒にディスパッチマップに追加される：\n\n```python\nTOOLS = [\n    {\"name\": \"bash\",       ...},\n    {\"name\": \"read_file\",  ...},\n    {\"name\": \"write_file\", ...},\n    {\"name\": \"edit_file\",  ...},\n    {\"name\": \"glob\",       ...},\n    # s05: 新規追加\n    {\"name\": \"todo_write\", \"description\": \"Create and manage a task list ...\",\n     \"input_schema\": {\n         \"type\": \"object\",\n         \"properties\": {\n             \"todos\": {\n                 \"type\": \"array\",\n                 \"items\": {\n                     \"type\": \"object\",\n                     \"properties\": {\n                         \"content\": {\"type\": \"string\"},\n                         \"status\": {\"type\": \"string\", \"enum\": [\"pending\", \"in_progress\", \"completed\"]},\n                     },\n                 },\n             },\n         },\n     },\n    },\n]\n\nTOOL_HANDLERS[\"todo_write\"] = run_todo_write\n```\n\n**Nag リマインダー**：モデルが 3 ラウンド連続で `todo_write` を呼び出さなかった場合、リマインダーが自動的に注入される：\n\n```python\nif rounds_since_todo >= 3 and messages:\n    messages.append({\n        \"role\": \"user\",\n        \"content\": \"<reminder>Update your todos.</reminder>\",\n    })\n    rounds_since_todo = 0\n```\n\nAgent がタスクを受け取った後の典型的な流れ：まず `todo_write` を呼び出して全手順を列挙（全て `pending`）→ 一つの手順に取り掛かり、`in_progress` に変更 → 完了したら `completed` に変更 → 次の `pending` を見る → 続行。3 ラウンド `todo_write` がない場合、次の LLM 呼び出し前にリマインダーが追加される。\n\n**重要な洞察**：todo_write は Agent に**実行能力**を何も追加しない。追加するのは**計画能力**だ。\n\n---\n\n## s04 からの変更\n\n| コンポーネント | 変更前 (s04) | 変更後 (s05) |\n|--------------|-------------|-------------|\n| ツール数 | 5 (bash, read, write, edit, glob) | 6 (+todo_write) |\n| 計画能力 | なし | ステータス付き TODO リスト + Nag リマインダー |\n| SYSTEM プロンプト | 汎用プロンプト | 「先に計画してから実行」のガイダンスを追加 |\n| ループ | 不変 | ディスパッチは不変、rounds_since_todo カウンターとリマインダー注入を追加 |\n\n---\n\n## 試してみよう\n\n```sh\ncd learn-claude-code\npython s05_todo_write/code.py\n```\n\n以下のプロンプトを試してみよう：\n\n1. `Refactor s05_todo_write/example/hello.py: add type hints, docstrings, and a main guard`（まず 3 手順を列挙してから実行するはず）\n2. `Create a Python package under s05_todo_write/example/demo_pkg with __init__.py, utils.py, and tests/test_utils.py`\n3. `Review Python files under s05_todo_write/example and fix any style issues`\n\n観察のポイント：最初のツール呼び出しは `todo_write` か？ TODO は何手順列挙されたか？ 実行中にステータスが `pending` から `in_progress` / `completed` に変わったか？\n\n---\n\n## 次へ\n\nAgent は計画できるようになった。しかしタスクが大きすぎる場合、例えば「認証モジュール全体をリファクタリング」、TODO リストだけでは不十分。そのタスク自体が数十のサブタスクの集合体で、同じ会話のコンテキストに押し込めると溢れてしまう。\n\n→ s06 Subagent：大きなタスクをサブタスクに分割し、それぞれを独立した Agent に任せる。それぞれが独自のクリーンなコンテキストを持ち、相互汚染がない。\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s06",
    "locale": "en",
    "title": "s06: Subagent — Break Large Tasks into Small Ones with Clean Context",
    "content": "# s06: Subagent — Break Large Tasks into Small Ones with Clean Context\n\ns01 → s02 → s03 → s04 → s05 → `s06` → [s07](/en/s07) → s08 → ... → s20 → s21\n\n> *\"Break large tasks small, each with clean context\"* — Subagent uses an independent messages[], no pollution in the main conversation.\n>\n> **Harness Layer**: Sub-Agent — Context isolation, attention doesn't drift.\n\n---\n\n## The Problem\n\nThe Agent is fixing a bug. It reads 30 files to trace the call chain, chatting for 60 rounds along the way. The messages list grows to 120 entries, most of which are intermediate steps from \"tracing the call chain\" — unrelated to the final goal of \"fixing the bug.\"\n\nThese intermediate steps occupy context space, making the Agent increasingly \"forgetful\" — it can no longer remember what the original problem was.\n\nThink of it differently: when you fix a bug, you'd \"open a new terminal\" to trace the call chain. When done, close the terminal, write the result into your notes, and return to the original terminal to keep fixing. The Agent needs this ability too — **open an independent sub-process, give it an independent message list, let it focus on one thing.**\n\n---\n\n## The Solution\n\n![Subagent Overview](/course-assets/s06_subagent/subagent-overview.en.svg)\n\nThe minimal hook structure and `todo_write` tool from the previous chapter are preserved; this chapter focuses on the new `task` tool. When called, it spawns a sub-Agent with a fresh `messages[]`, running its own loop, and returning only a summary text to the main Agent. Conversation context is discarded, but file system side effects (writes, edits, commands) remain in the working directory.\n\nThe sub-Agent's tools are restricted: it has bash/read/write/edit/glob, but no task, preventing recursive spawning. The sub-Agent's tool calls still go through permission hooks; context isolation does not bypass security.\n\n---\n\n## How It Works\n\n**spawn_subagent**, gives the sub-Agent a fresh messages list, runs its own loop, returns only the conclusion:\n\n```python\ndef spawn_subagent(description: str) -> str:\n    # Sub-Agent tools: base tools, but no task (no recursion)\n    sub_tools = [...]\n    messages = [{\"role\": \"user\", \"content\": description}]  # fresh messages[]\n\n    for _ in range(30):  # safety limit\n        response = client.messages.create(\n            model=MODEL, system=SUB_SYSTEM,\n            messages=messages, tools=sub_tools, max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n        if response.stop_reason != \"tool_use\":\n            break\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                blocked = trigger_hooks(\"PreToolUse\", block)\n                if blocked:\n                    results.append({... \"content\": str(blocked)})\n                    continue\n                handler = SUB_HANDLERS.get(block.name)\n                output = handler(**block.input) if handler else f\"Unknown\"\n                trigger_hooks(\"PostToolUse\", block, output)\n                results.append({... \"content\": output})\n        messages.append({\"role\": \"user\", \"content\": results})\n\n    # Return only the final text conclusion, all intermediate steps discarded\n    return extract_text(messages[-1][\"content\"])\n```\n\nThe main Agent calls it just like any other tool:\n\n```python\nTOOLS = [\n    {\"name\": \"bash\", ...},\n    {\"name\": \"read_file\", ...},\n    {\"name\": \"write_file\", ...},\n    {\"name\": \"edit_file\", ...},\n    {\"name\": \"glob\", ...},\n    {\"name\": \"todo_write\", ...},\n    # s06: new task tool\n    {\"name\": \"task\",\n     \"description\": \"Launch a subagent to handle a complex subtask. Returns only the final conclusion.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"description\": {\"type\": \"string\"}}, \"required\": [\"description\"]}},\n]\n\nTOOL_HANDLERS[\"task\"] = spawn_subagent\n```\n\nThree key design decisions:\n\n| Decision | Choice | Reason |\n|----------|--------|--------|\n| Context isolation | Fresh `messages[]` | Sub-Agent's intermediate steps don't pollute main Agent's context |\n| Return only conclusion | `extract_text(last_message)` | Not returning the entire messages list |\n| No recursion | Sub-Agent has no task tool | Prevents sub-Agent from spawning further sub-Agents |\n| Security not bypassed | Sub-Agent tool calls go through PreToolUse hook | Context isolation does not mean permission isolation |\n\nThe dispatch mechanism is unchanged; the task tool is routed through `TOOL_HANDLERS[block.name]`. The sub-Agent has its own `SUB_SYSTEM` prompt, explicitly instructing \"complete the task, do not delegate further.\"\n\n---\n\n## Changes from s05\n\n| Component | Before (s05) | After (s06) |\n|-----------|-------------|-------------|\n| Tool count | 6 (bash, read, write, edit, glob, todo_write) | 7 (+task) |\n| New function | — | spawn_subagent (independent messages[] + 30-round safety limit) |\n| Context isolation | Everything in the main conversation | Sub-Agent uses fresh messages[] |\n| Loop | Unchanged | Dispatch unchanged, sub-Agent has independent SUB_SYSTEM and hook-protected loop |\n\n---\n\n## Try It\n\n```sh\ncd learn-claude-code\npython s06_subagent/code.py\n```\n\nTry these prompts:\n\n1. `Use a subtask to find what testing framework this project uses` (sub-Agent reads files, main Agent receives only the conclusion)\n2. `Delegate: read all .py files in agents/ and summarize what each one does`\n3. `Use a task to create s06_subagent/example/string_tools.py with a slugify(text: str) function, then verify it from the parent agent`\n\nWhat to watch for: Do `[Subagent spawned]` / `[Subagent done]` appear? Do sub-Agent tool calls print as `[sub] ...`? Does the parent Agent continue with only the summary returned by the sub-Agent?\n\n---\n\n## What's Next\n\nThe Agent can now break tasks apart. But different tasks require different knowledge: editing frontend components needs React conventions, writing SQL needs table schemas. Stuffing all this knowledge into the system prompt would blow up the context.\n\n→ s07 Skill Loading: Inject skills on demand instead of piling documents into the system prompt. Load only when needed, as natural as reading a file.\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s06",
    "locale": "zh",
    "title": "s06: Subagent — 大任务拆小，每个拿到的都是干净上下文",
    "content": "# s06: Subagent — 大任务拆小，每个拿到的都是干净上下文\n\ns01 → s02 → s03 → s04 → s05 → `s06` → [s07](/zh/s07) → s08 → ... → s20 → s21\n\n> *\"大任务拆小, 每个小任务干净的上下文\"* — Subagent 用独立 messages[], 不污染主对话。\n>\n> **Harness 层**: 子 Agent — 上下文隔离, 注意力不漂移。\n\n---\n\n## 问题\n\nAgent 在修一个 bug。它读了 30 个文件来追踪调用链，中间聊了 60 轮。messages 列表涨到 120 条，其中大部分是\"追踪调用链\"的中间过程，和\"修 bug\"这个最终目标无关。\n\n这些中间过程占着上下文位置，让 Agent 越来越\"健忘\"，它记不住最初的问题是什么了。\n\n换个角度：你修 bug 的时候，会\"开一个新终端\"来追踪调用链。追踪完了，终端关掉，结果写进笔记，回到原来的终端继续修 bug。Agent 也需要这个能力：开一个独立的子进程，给它一个独立的消息列表，让它专心做一件事。\n\n---\n\n## 解决方案\n\n![Subagent Overview](/course-assets/s06_subagent/subagent-overview.svg)\n\n保留上一章的最小 hook 结构和 `todo_write` 工具，本章重点转向新增的 `task` 工具。调用它时，spawn 一个子 Agent，拥有全新的 `messages[]`，跑自己的循环，结束后只把摘要文本回传给主 Agent。对话上下文被丢弃，但文件系统的副作用（写文件、改文件、跑命令）保留在工作目录中。\n\n子 Agent 的工具受限：有 bash/read/write/edit/glob，但没有 task，不能递归 spawn 新的子 Agent。子 Agent 的工具调用仍经过权限 hook，安全策略不因上下文隔离而跳过。\n\n---\n\n## 工作原理\n\n**spawn_subagent**，给子 Agent 一个全新的 messages 列表，跑自己的循环，只回传结论：\n\n```python\ndef spawn_subagent(description: str) -> str:\n    # 子 Agent 的工具：基础工具，但没有 task（禁止递归）\n    sub_tools = [\n        {\"name\": \"bash\", ...}, {\"name\": \"read_file\", ...},\n        {\"name\": \"write_file\", ...}, {\"name\": \"edit_file\", ...},\n        {\"name\": \"glob\", ...},\n    ]\n    messages = [{\"role\": \"user\", \"content\": description}]  # 全新 messages[]\n\n    for _ in range(30):  # safety limit\n        response = client.messages.create(\n            model=MODEL, system=SUB_SYSTEM,\n            messages=messages, tools=sub_tools, max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n        if response.stop_reason != \"tool_use\":\n            break\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                blocked = trigger_hooks(\"PreToolUse\", block)\n                if blocked:\n                    results.append({... \"content\": str(blocked)})\n                    continue\n                handler = SUB_HANDLERS.get(block.name)\n                output = handler(**block.input) if handler else f\"Unknown\"\n                trigger_hooks(\"PostToolUse\", block, output)\n                results.append({... \"content\": output})\n        messages.append({\"role\": \"user\", \"content\": results})\n\n    # 只返回最后的文本结论，中间过程全部丢弃\n    return extract_text(messages[-1][\"content\"])\n```\n\n主 Agent 调用时，跟调其他工具一样：\n\n```python\nTOOLS = [\n    {\"name\": \"bash\", ...},\n    {\"name\": \"read_file\", ...},\n    {\"name\": \"write_file\", ...},\n    {\"name\": \"edit_file\", ...},\n    {\"name\": \"glob\", ...},\n    {\"name\": \"todo_write\", ...},\n    # s06: 新增 task 工具\n    {\"name\": \"task\",\n     \"description\": \"Launch a subagent to handle a complex subtask. Returns only the final conclusion.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"description\": {\"type\": \"string\"}}, \"required\": [\"description\"]}},\n]\n\nTOOL_HANDLERS[\"task\"] = spawn_subagent\n```\n\n三个关键设计决策：\n\n| 决策 | 选择 | 原因 |\n|------|------|------|\n| 上下文隔离 | 全新 `messages[]` | 子 Agent 的中间过程不污染主 Agent 的上下文 |\n| 只回传结论 | `extract_text(last_message)` | 不是回传整个 messages 列表 |\n| 禁止递归 | 子 Agent 无 task 工具 | 防止子 Agent 再 spawn 新的子 Agent |\n| 安全策略不跳过 | 子 Agent 工具调用也走 PreToolUse hook | 上下文隔离不代表权限隔离 |\n\ndispatch 机制不变，task 工具通过 `TOOL_HANDLERS[block.name]` 分发。子 Agent 有独立的 `SUB_SYSTEM` 提示，明确要求\"直接完成任务，不要再委派\"。\n\n---\n\n## 相对 s05 的变更\n\n| 组件 | 之前 (s05) | 之后 (s06) |\n|------|-----------|-----------|\n| 工具数量 | 6 (bash, read, write, edit, glob, todo_write) | 7 (+task) |\n| 新函数 | — | spawn_subagent（独立 messages[] + 30 轮安全限制） |\n| 上下文隔离 | 全部在主对话中 | 子 Agent 用全新的 messages[] |\n| 循环 | 不变 | dispatch 不变，子 Agent 有独立 SUB_SYSTEM 和 hook 保护的循环 |\n\n---\n\n## 试一下\n\n```sh\ncd learn-claude-code\npython s06_subagent/code.py\n```\n\n试试这些 prompt：\n\n1. `Use a subtask to find what testing framework this project uses`（子 Agent 去读文件，主 Agent 只收结论）\n2. `Delegate: read all .py files in agents/ and summarize what each one does`\n3. `Use a task to create s06_subagent/example/string_tools.py with a slugify(text: str) function, then verify it from the parent agent`\n\n观察重点：是否出现 `[Subagent spawned]` / `[Subagent done]`？子 Agent 的工具调用是否以 `[sub] ...` 输出？主 Agent 最后是否只继续处理子 Agent 返回的摘要？\n\n---\n\n## 接下来\n\nAgent 现在能拆任务了。但每个任务需要的知识不一样：改前端组件需要知道 React 规范，写 SQL 需要知道表结构。这些知识全塞进 system prompt，上下文直接爆了。\n\ns07 Skill Loading → 技能按需注入，不在 system prompt 里堆文档。用到的时候才加载，和读文件一样自然。\n\n\n<!-- translation-sync: zh@v1, en@v0, ja@v0 -->\n"
  },
  {
    "version": "s06",
    "locale": "ja",
    "title": "s06: Subagent — 大きなタスクを分割、それぞれがクリーンなコンテキストを取得",
    "content": "# s06: Subagent — 大きなタスクを分割、それぞれがクリーンなコンテキストを取得\n\ns01 → s02 → s03 → s04 → s05 → `s06` → [s07](/ja/s07) → s08 → ... → s20 → s21\n\n> *\"大きなタスクは小さく、小さなタスクごとにクリーンなコンテキスト\"* — Subagent は独立した messages[] を使い、メイン会話を汚染しない。\n>\n> **Harness レイヤー**: サブエージェント — コンテキストの隔離、注意の散漫を防ぐ。\n\n---\n\n## 課題\n\nAgent がバグを修正している。呼び出しチェーンを追跡するために 30 のファイルを読み、途中で 60 ラウンドやり取りした。messages リストは 120 件に膨らみ、その大部分は「呼び出しチェーンの追跡」という中間過程 — 「バグ修正」という最終目標とは無関係。\n\nこの中間過程がコンテキストの席を占め、Agent はますます「健忘」になる — 最初の問題が何だったか覚えていられない。\n\n別の見方をすると：バグを修正するとき、あなたは「新しいターミナルを開いて」呼び出しチェーンを追跡するだろう。追跡が終わったらターミナルを閉じ、結果をメモに書き、元のターミナルに戻ってバグ修正を続ける。Agent にもこの能力が必要 — **独立したサブプロセスを開き、独立したメッセージリストを与え、一つのことに集中させる。**\n\n---\n\n## ソリューション\n\n![Subagent Overview](/course-assets/s06_subagent/subagent-overview.ja.svg)\n\n前章の最小フック構造と `todo_write` ツールを保持し、本章は新規の `task` ツールに注目する。呼び出されると、サブエージェントを spawn する。新しい `messages[]` を持ち、自分自身のループを実行し、終了後に要約テキストのみをメイン Agent に返す。会話コンテキストは破棄されるが、ファイルシステムの副作用（書き込み、編集、コマンド実行）は作業ディレクトリに残る。\n\nサブエージェントのツールは制限される：bash/read/write/edit/glob を持つが、task はない。再帰 spawn を防止する。サブエージェントのツール呼び出しも権限フックを経由する。コンテキスト分離は権限のバイパスではない。\n\n---\n\n## 仕組み\n\n**spawn_subagent**、サブエージェントに新しいメッセージリストを与え、自分自身のループを実行し、結論のみを返す：\n\n```python\ndef spawn_subagent(description: str) -> str:\n    # サブエージェントのツール：基本ツールのみ、task なし（再帰禁止）\n    sub_tools = [...]\n    messages = [{\"role\": \"user\", \"content\": description}]  # 新規 messages[]\n\n    for _ in range(30):  # safety limit\n        response = client.messages.create(\n            model=MODEL, system=SUB_SYSTEM,\n            messages=messages, tools=sub_tools, max_tokens=8000,\n        )\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n        if response.stop_reason != \"tool_use\":\n            break\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                blocked = trigger_hooks(\"PreToolUse\", block)\n                if blocked:\n                    results.append({... \"content\": str(blocked)})\n                    continue\n                handler = SUB_HANDLERS.get(block.name)\n                output = handler(**block.input) if handler else f\"Unknown\"\n                trigger_hooks(\"PostToolUse\", block, output)\n                results.append({... \"content\": output})\n        messages.append({\"role\": \"user\", \"content\": results})\n\n    # 最後のテキスト結論のみを返す、中間過程はすべて破棄\n    return extract_text(messages[-1][\"content\"])\n```\n\nメイン Agent の呼び出しは、他のツールと同じ：\n\n```python\nTOOLS = [\n    {\"name\": \"bash\", ...},\n    {\"name\": \"read_file\", ...},\n    {\"name\": \"write_file\", ...},\n    {\"name\": \"edit_file\", ...},\n    {\"name\": \"glob\", ...},\n    {\"name\": \"todo_write\", ...},\n    # s06: 新規 task ツール\n    {\"name\": \"task\",\n     \"description\": \"Launch a subagent to handle a complex subtask. Returns only the final conclusion.\",\n     \"input_schema\": {\"type\": \"object\", \"properties\": {\"description\": {\"type\": \"string\"}}, \"required\": [\"description\"]}},\n]\n\nTOOL_HANDLERS[\"task\"] = spawn_subagent\n```\n\n三つの重要な設計決定：\n\n| 決定 | 選択 | 理由 |\n|------|------|------|\n| コンテキスト隔離 | 新規 `messages[]` | サブエージェントの中間過程がメイン Agent のコンテキストを汚染しない |\n| 結論のみ返却 | `extract_text(last_message)` | messages リスト全体を返すのではない |\n| 再帰禁止 | サブエージェントに task ツールなし | サブエージェントがさらにサブエージェントを spawn するのを防止 |\n| セキュリティのバイパスなし | サブエージェントのツール呼び出しも PreToolUse フックを経由 | コンテキスト分離は権限分離ではない |\n\nディスパッチ機構は変わらず、task ツールは `TOOL_HANDLERS[block.name]` を経由する。サブエージェントは独立した `SUB_SYSTEM` プロンプトを持ち、「タスクを完了し、さらに委託しない」と明示される。\n\n---\n\n## s05 からの変更\n\n| コンポーネント | 変更前 (s05) | 変更後 (s06) |\n|--------------|-------------|-------------|\n| ツール数 | 6 (bash, read, write, edit, glob, todo_write) | 7 (+task) |\n| 新規関数 | — | spawn_subagent（独立 messages[] + 30 ラウンド安全制限） |\n| コンテキスト隔離 | すべてメイン会話内 | サブエージェントが新規 messages[] を使用 |\n| ループ | 不変 | ディスパッチは不変、サブエージェントに独立した SUB_SYSTEM とフック保護されたループ |\n\n---\n\n## 試してみよう\n\n```sh\ncd learn-claude-code\npython s06_subagent/code.py\n```\n\n以下のプロンプトを試してみよう：\n\n1. `Use a subtask to find what testing framework this project uses`（サブエージェントがファイルを読み、メイン Agent は結論のみ受け取る）\n2. `Delegate: read all .py files in agents/ and summarize what each one does`\n3. `Use a task to create s06_subagent/example/string_tools.py with a slugify(text: str) function, then verify it from the parent agent`\n\n観察のポイント：`[Subagent spawned]` / `[Subagent done]` が表示されるか？ サブエージェントのツール呼び出しが `[sub] ...` として出力されるか？ 親 Agent はサブエージェントが返した要約だけを受け取って続行するか？\n\n---\n\n## 次へ\n\nAgent はタスクを分割できるようになった。しかし各タスクに必要な知識は異なる。フロントエンドコンポーネントの変更には React 規約が必要で、SQL を書くにはテーブル構造を知る必要がある。これらの知識をすべて system prompt に詰め込むと、コンテキストが溢れてしまう。\n\n→ s07 Skill Loading：スキルをオンデマンドで注入する。system prompt にドキュメントを積み上げるのではなく、必要なときだけ読み込む。ファイルを読むのと同じくらい自然に。\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s07",
    "locale": "en",
    "title": "s07: Skill Loading — Load Only When Needed",
    "content": "# s07: Skill Loading — Load Only When Needed\n\ns01 → s02 → s03 → s04 → s05 → s06 → `s07` → [s08](/en/s08) → s09 → ... → s20 → s21\n> *\"Load when needed, don't stuff the prompt\"* — Inject via tool_result, not system prompt.\n>\n> **Harness Layer**: Knowledge — load on demand, don't fill the context.\n\n---\n\n## The Problem\n\nYour project has a React component spec, a SQL style guide, and an API design doc. You want the Agent to follow these specs automatically. The most straightforward idea — stuff them all into the system prompt:\n\n```python\nSYSTEM = (\n    f\"You are a coding agent. \"\n    + open(\"docs/react-style.md\").read()       # 2000 lines\n    + open(\"docs/sql-style.md\").read()         # 1500 lines\n    + open(\"docs/api-design.md\").read()        # 3000 lines\n)\n```\n\n6500 lines of system prompt. The Agent carries these docs on every LLM call — whether it's changing a CSS color or fixing a SQL query. 99% of the content is irrelevant to the current task, burning tokens for nothing.\n\n---\n\n## The Solution\n\n![Skill Overview](/course-assets/s07_skill_loading/skill-overview.en.svg)\n\nThe minimal hook structure, `todo_write`, and sub-Agent from the previous chapter are preserved. This chapter focuses on the new `load_skill` tool. At startup, inject the skill catalog into the SYSTEM prompt; at runtime, register one more tool to load full content, spending tokens only when used.\n\nTwo-level design:\n\n| Level | Location | Timing | Cost |\n|-------|----------|--------|------|\n| 1. Catalog | system prompt | Injected at startup (harness scans skills/) | ~100 tokens/skill, carried every turn |\n| 2. Content | tool_result | When Agent calls load_skill; SKILL.md can guide later read_file/bash access to extra resources | ~2000 tokens/skill, on demand |\n\nThe dispatch mechanism is unchanged, `load_skill` auto-dispatches via `TOOL_HANDLERS[block.name]`.\n\n---\n\n## How It Works\n\n**skills/ directory**, one subdirectory per skill, each containing a `SKILL.md` file:\n\n```\nskills/\n  agent-builder/SKILL.md\n  code-review/SKILL.md\n  mcp-builder/SKILL.md\n  pdf/SKILL.md\n```\n\n**Level 1: Inject catalog at startup**: the harness calls `_scan_skills()` at startup to scan the skills/ directory, parsing each SKILL.md's YAML frontmatter (`name`, `description`) into a `SKILL_REGISTRY` dictionary. `list_skills()` generates the catalog from the registry, injected into the SYSTEM prompt. The Agent sees \"which skills I have available\" every turn, with no extra API calls:\n\n```python\nSKILL_REGISTRY: dict[str, dict] = {}\n\ndef _scan_skills():\n    if not SKILLS_DIR.exists():\n        return\n    for d in sorted(SKILLS_DIR.iterdir()):\n        if not d.is_dir():\n            continue\n        manifest = d / \"SKILL.md\"\n        if manifest.exists():\n            raw = manifest.read_text()\n            meta, body = _parse_frontmatter(raw)\n            name = meta.get(\"name\", d.name)\n            desc = meta.get(\"description\", raw.split(\"\\n\")[0].lstrip(\"#\").strip())\n            SKILL_REGISTRY[name] = {\"name\": name, \"description\": desc, \"content\": raw}\n\n_scan_skills()  # runs once at startup\n\ndef list_skills() -> str:\n    return \"\\n\".join(f\"- **{s['name']}**: {s['description']}\" for s in SKILL_REGISTRY.values())\n\ndef build_system() -> str:\n    catalog = list_skills()\n    return (\n        f\"You are a coding agent at {WORKDIR}. \"\n        f\"Skills available:\\n{catalog}\\n\"\n        \"Use load_skill to get full details when needed.\"\n    )\n\nSYSTEM = build_system()\n```\n\n**Level 2: load_skill**: the Agent decides \"I need the SQL style guide\" and calls `load_skill(\"sql-style\")`. Lookup goes through the registry, not file paths, eliminating path traversal risk. The SKILL.md content is injected via `tool_result`, and can include later access to referenced `references/`, `scripts/`, or `assets/` through the existing file and bash tools.\n\n```python\ndef load_skill(name: str) -> str:\n    skill = SKILL_REGISTRY.get(name)\n    if not skill:\n        return f\"Skill not found: {name}\"\n    return skill[\"content\"]\n```\n\nThe key distinction: skill content is not part of the system prompt. It enters the current messages as a tool result. Subsequent calls carry it along with the history until context compaction, truncation, or session end. This naturally connects to s08's compact: on-demand loading solves \"don't carry what you shouldn't\", compact solves \"how to drop what you should.\"\n\n---\n\n## Changes from s06\n\n| Component | Before (s06) | After (s07) |\n|-----------|-------------|-------------|\n| Tool count | 7 (bash, read, write, edit, glob, todo_write, task) | 8 (+load_skill) |\n| Knowledge loading | None | Two-level: startup catalog in SYSTEM + runtime load_skill; SKILL.md may guide later resource access |\n| SYSTEM prompt | Static string | Startup scan of skills/ injects catalog |\n| Skill registry | None | SKILL_REGISTRY (populated at startup, prevents path traversal) |\n| Loop | Unchanged | Unchanged (skill tool auto-dispatches) |\n\n---\n\n## Try It\n\n```sh\ncd learn-claude-code\npython s07_skill_loading/code.py\n```\n\nTry these prompts:\n\n1. `What skills are available?`\n2. `Load the code-review skill and follow its instructions`\n3. `I need to do a code review -- load the relevant skill first`\n\nWhat to watch for: Does the Agent know available skills from the SYSTEM catalog? Does `[HOOK] load_skill` appear when full instructions are needed? Does the answer use the loaded skill's instructions?\n\n---\n\n## What's Next\n\nOn-demand loading solved \"don't carry what you shouldn't.\" But another problem looms: after the Agent works for 30 minutes, the messages list fills up with intermediate process. Old tool_results, stale file contents, occupying context but adding no value.\n\n→ s08 Context Compact: A four-layer compaction strategy. Cheap layers run first, expensive layers run last.\n\n\n<!-- translation-sync: zh@v2, en@v2, ja@v2 -->\n"
  },
  {
    "version": "s07",
    "locale": "zh",
    "title": "s07: Skill Loading — 用到的时候才加载",
    "content": "# s07: Skill Loading — 用到的时候才加载\n\ns01 → s02 → s03 → s04 → s05 → s06 → `s07` → [s08](/zh/s08) → s09 → ... → s20 → s21\n> *\"用到时再加载, 别全塞 prompt 里\"* — 通过 tool_result 注入, 不塞 system prompt。\n>\n> **Harness 层**: 知识 — 按需加载, 不堆满上下文。\n\n---\n\n## 问题\n\n你的项目有一套 React 组件规范、一份 SQL 风格指南、一份 API 设计文档。你希望 Agent 自动遵守这些规范。最直接的想法，全塞进 system prompt：\n\n```python\nSYSTEM = (\n    f\"You are a coding agent. \"\n    + open(\"docs/react-style.md\").read()       # 2000 行\n    + open(\"docs/sql-style.md\").read()         # 1500 行\n    + open(\"docs/api-design.md\").read()        # 3000 行\n)\n```\n\n6500 行 system prompt。Agent 每次调用 LLM 都带着这些文档——不管是在改 CSS 颜色还是修 SQL 查询。99% 的内容和当前任务无关，白白消耗 token。\n\n---\n\n## 解决方案\n\n![Skill Overview](/course-assets/s07_skill_loading/skill-overview.svg)\n\n保留上一章的最小 hook 结构、`todo_write` 和子 Agent，本章重点转向新增的 `load_skill` 工具。启动时把技能目录注入 SYSTEM prompt，运行时多注册一个工具加载完整内容，用到才花 token。\n\n两层设计：\n\n| 层 | 位置 | 时机 | 代价 |\n|---|------|------|------|\n| 1. 目录 | system prompt | 启动时注入（harness 扫描 skills/） | ~100 tokens/skill，每轮都带 |\n| 2. 内容 | tool_result | Agent 调用 load_skill 时；SKILL.md 可指引后续的 read_file/bash 调用，用于按需访问额外资源 | ~2000 tokens/skill，按需 |\n\ndispatch 机制不变，load_skill 通过 `TOOL_HANDLERS[block.name]` 分发。\n\n---\n\n## 工作原理\n\n**skills/ 目录**，每个技能一个子目录，包含 `SKILL.md` 文件：\n\n```\nskills/\n  agent-builder/SKILL.md\n  code-review/SKILL.md\n  mcp-builder/SKILL.md\n  pdf/SKILL.md\n```\n\n**第一级：启动时注入目录**：harness 启动时调用 `_scan_skills()` 扫描 skills/ 目录，解析每个 SKILL.md 的 YAML frontmatter（`name`、`description`），存入 `SKILL_REGISTRY` 字典。`list_skills()` 从注册表生成目录，注入 SYSTEM prompt。Agent 每轮都能看到\"我有哪些技能可用\"，不花额外 API 调用：\n\n```python\nSKILL_REGISTRY: dict[str, dict] = {}\n\ndef _scan_skills():\n    if not SKILLS_DIR.exists():\n        return\n    for d in sorted(SKILLS_DIR.iterdir()):\n        if not d.is_dir():\n            continue\n        manifest = d / \"SKILL.md\"\n        if manifest.exists():\n            raw = manifest.read_text()\n            meta, body = _parse_frontmatter(raw)\n            name = meta.get(\"name\", d.name)\n            desc = meta.get(\"description\", raw.split(\"\\n\")[0].lstrip(\"#\").strip())\n            SKILL_REGISTRY[name] = {\"name\": name, \"description\": desc, \"content\": raw}\n\n_scan_skills()  # runs once at startup\n\ndef list_skills() -> str:\n    return \"\\n\".join(f\"- **{s['name']}**: {s['description']}\" for s in SKILL_REGISTRY.values())\n\ndef build_system() -> str:\n    catalog = list_skills()\n    return (\n        f\"You are a coding agent at {WORKDIR}. \"\n        f\"Skills available:\\n{catalog}\\n\"\n        \"Use load_skill to get full details when needed.\"\n    )\n\nSYSTEM = build_system()\n```\n\n**第二级：load_skill**：Agent 决定\"我需要 SQL 风格指南\"，调用 `load_skill(\"sql-style\")`。通过注册表查找，不走文件路径，没有路径遍历风险。SKILL.md 内容通过 `tool_result` 注入，并可通过现有的 file 和 bash 工具进一步访问引用的 `references/`、`scripts/` 或 `assets/`。\n\n```python\ndef load_skill(name: str) -> str:\n    skill = SKILL_REGISTRY.get(name)\n    if not skill:\n        return f\"Skill not found: {name}\"\n    return skill[\"content\"]\n```\n\n关键区别：技能内容不是 system prompt 的一部分，它作为一次工具结果进入当前 messages。后续调用会随历史一起携带，直到上下文压缩、截断或会话结束。这和 s08 的 compact 自然衔接：按需加载解决了\"不该提前带的不要带\"，compact 解决\"该丢的怎么丢\"。\n\n---\n\n## 相对 s06 的变更\n\n| 组件 | 之前 (s06) | 之后 (s07) |\n|------|-----------|-----------|\n| 工具数量 | 7 (bash, read, write, edit, glob, todo_write, task) | 8 (+load_skill) |\n| 知识加载 | 无 | 两级：启动时目录注入 SYSTEM + 运行时 load_skill；SKILL.md 可指引后续资源访问 |\n| SYSTEM 提示 | 静态字符串 | 启动时扫描 skills/ 注入目录 |\n| 技能注册表 | 无 | SKILL_REGISTRY（启动时填充，防路径遍历） |\n| 循环 | 不变 | 不变（skill 工具自动分发） |\n\n---\n\n## 试一下\n\n```sh\ncd learn-claude-code\npython s07_skill_loading/code.py\n```\n\n试试这些 prompt：\n\n1. `What skills are available?`\n2. `Load the code-review skill and follow its instructions`\n3. `I need to do a code review -- load the relevant skill first`\n\n观察重点：Agent 是否直接从 SYSTEM 里的目录知道有哪些技能？需要完整规范时是否出现 `[HOOK] load_skill`？加载后回答是否使用了对应 skill 的说明？\n\n---\n\n## 接下来\n\n按需加载解决了\"不该带的不要带\"。但另一个问题来了：Agent 连续工作 30 分钟后，messages 列表塞满了中间过程。旧的 tool_result、过时的文件内容，占着上下文但不产生价值。\n\ns08 Context Compact → 四层压缩策略。便宜的先跑，贵的后跑。\n\n\n<!-- translation-sync: zh@v2, en@v2, ja@v2 -->\n"
  },
  {
    "version": "s07",
    "locale": "ja",
    "title": "s07: Skill Loading — 必要なときにだけ読み込む",
    "content": "# s07: Skill Loading — 必要なときにだけ読み込む\n\ns01 → s02 → s03 → s04 → s05 → s06 → `s07` → [s08](/ja/s08) → s09 → ... → s20 → s21\n> *\"Load when needed, don't stuff the prompt\"* — tool_result で注入、system prompt には詰め込まない。\n>\n> **Harness レイヤー**: 知識 — 必要に応じて読み込み、コンテキストに詰め込まない。\n\n---\n\n## 課題\n\nプロジェクトには React コンポーネント仕様、SQL スタイルガイド、API 設計ドキュメントがある。Agent にこれらの仕様を自動的に守らせたい。最も直接的な方法 — すべて system prompt に詰め込む：\n\n```python\nSYSTEM = (\n    f\"You are a coding agent. \"\n    + open(\"docs/react-style.md\").read()       # 2000 行\n    + open(\"docs/sql-style.md\").read()         # 1500 行\n    + open(\"docs/api-design.md\").read()        # 3000 行\n)\n```\n\n6500 行の system prompt。Agent は LLM を呼び出すたびにこれらのドキュメントを運ぶ — CSS の色を変えるときも SQL クエリを修正するときも。99% の内容が現在のタスクと無関係で、トークンを無駄に消費する。\n\n---\n\n## ソリューション\n\n![Skill Overview](/course-assets/s07_skill_loading/skill-overview.ja.svg)\n\n前章の最小フック構造、`todo_write`、サブ Agent を維持し、本章は新規の `load_skill` ツールに注目する。起動時にスキルカタログを SYSTEM prompt に注入し、実行時に完全な内容を読み込むツールを登録する。使ったときだけトークンを消費。\n\n2 層設計：\n\n| 層 | 場所 | タイミング | コスト |\n|---|------|-----------|--------|\n| 1. カタログ | system prompt | 起動時に注入（harness が skills/ をスキャン） | ~100 トークン/スキル、毎ターン携帯 |\n| 2. 内容 | tool_result | Agent が load_skill を呼び出したとき。SKILL.md は、必要に応じて read_file/bash で追加リソースへアクセスするための手がかりになる | ~2000 トークン/スキル、オンデマンド |\n\nディスパッチ機構は変わらず、`load_skill` は `TOOL_HANDLERS[block.name]` を通じて自動的にディスパッチされる。\n\n---\n\n## 仕組み\n\n**skills/ ディレクトリ**、スキルごとに 1 つのサブディレクトリ、それぞれに `SKILL.md` ファイルを含む：\n\n```\nskills/\n  agent-builder/SKILL.md\n  code-review/SKILL.md\n  mcp-builder/SKILL.md\n  pdf/SKILL.md\n```\n\n**第 1 層：起動時にカタログを注入**：harness は起動時に `_scan_skills()` を呼び出して skills/ ディレクトリをスキャンし、各 SKILL.md の YAML frontmatter（`name`、`description`）を解析して `SKILL_REGISTRY` 辞書に格納する。`list_skills()` はレジストリからカタログを生成し、SYSTEM prompt に注入する。Agent は毎ターン「どのスキルが利用可能か」を確認できる。追加の API 呼び出しは不要：\n\n```python\nSKILL_REGISTRY: dict[str, dict] = {}\n\ndef _scan_skills():\n    if not SKILLS_DIR.exists():\n        return\n    for d in sorted(SKILLS_DIR.iterdir()):\n        if not d.is_dir():\n            continue\n        manifest = d / \"SKILL.md\"\n        if manifest.exists():\n            raw = manifest.read_text()\n            meta, body = _parse_frontmatter(raw)\n            name = meta.get(\"name\", d.name)\n            desc = meta.get(\"description\", raw.split(\"\\n\")[0].lstrip(\"#\").strip())\n            SKILL_REGISTRY[name] = {\"name\": name, \"description\": desc, \"content\": raw}\n\n_scan_skills()  # runs once at startup\n\ndef list_skills() -> str:\n    return \"\\n\".join(f\"- **{s['name']}**: {s['description']}\" for s in SKILL_REGISTRY.values())\n\ndef build_system() -> str:\n    catalog = list_skills()\n    return (\n        f\"You are a coding agent at {WORKDIR}. \"\n        f\"Skills available:\\n{catalog}\\n\"\n        \"Use load_skill to get full details when needed.\"\n    )\n\nSYSTEM = build_system()\n```\n\n**第 2 層：load_skill**：Agent が「SQL スタイルガイドが必要」と判断し、`load_skill(\"sql-style\")` を呼び出す。レジストリを通じて検索し、ファイルパスを経由しないため、パストラバーサルのリスクがない。SKILL.md の内容は `tool_result` を通じて注入され、既存の file および bash ツールを通じて、参照される `references/`、`scripts/`、`assets/` へのその後のアクセスも含められる。\n\n```python\ndef load_skill(name: str) -> str:\n    skill = SKILL_REGISTRY.get(name)\n    if not skill:\n        return f\"Skill not found: {name}\"\n    return skill[\"content\"]\n```\n\n重要な違い：スキル内容は system prompt の一部ではなく、ツール結果として現在の messages に入る。後続の呼び出しでは履歴とともに携帯され、コンテキスト圧縮、切り捨て、またはセッション終了まで保持される。これは s08 の compact と自然に接続する：オンデマンド読み込みで「運ぶべきでないものは運ばない」を解決し、compact が「捨てるべきものをどう捨てるか」を解決する。\n\n---\n\n## s06 からの変更点\n\n| コンポーネント | 変更前 (s06) | 変更後 (s07) |\n|---------------|-------------|-------------|\n| ツール数 | 7 (bash, read, write, edit, glob, todo_write, task) | 8 (+load_skill) |\n| 知識読み込み | なし | 2 層：起動時カタログ注入 SYSTEM + 実行時 load_skill。SKILL.md がその後のリソースアクセスを案内できる |\n| SYSTEM プロンプト | 静的文字列 | 起動時に skills/ をスキャンしてカタログ注入 |\n| スキルレジストリ | なし | SKILL_REGISTRY（起動時に充填、パストラバーサル防止） |\n| ループ | 変更なし | 変更なし（スキルツールは自動ディスパッチ） |\n\n---\n\n## 試してみよう\n\n```sh\ncd learn-claude-code\npython s07_skill_loading/code.py\n```\n\n以下のプロンプトを試してみよう：\n\n1. `What skills are available?`\n2. `Load the code-review skill and follow its instructions`\n3. `I need to do a code review -- load the relevant skill first`\n\n観察のポイント：Agent は SYSTEM 内のカタログから利用可能なスキルを知っているか？ 完全な手順が必要なときに `[HOOK] load_skill` が表示されるか？ 読み込んだスキルの説明を使って回答しているか？\n\n---\n\n## 次へ\n\nオンデマンド読み込みで「運ぶべきでないものは運ばない」問題は解決した。しかし別の問題が待っている：Agent が 30 分連続で作業すると、messages リストが中間プロセスで埋め尽くされる。古い tool_result、期限切れのファイル内容、コンテキストを占領しているが価値を生まない。\n\n→ s08 Context Compact：4 層圧縮戦略。安価な層を先に実行、高価な層を後に実行。\n\n\n<!-- translation-sync: zh@v2, en@v2, ja@v2 -->\n"
  },
  {
    "version": "s08",
    "locale": "en",
    "title": "s08: Context Compact — Context Will Fill Up, Have a Way to Make Room",
    "content": "# s08: Context Compact — Context Will Fill Up, Have a Way to Make Room\n\ns01 → s02 → s03 → s04 → s05 → s06 → s07 → `s08` → [s09](/en/s09) → s10 → ... → s20 → s21\n> *\"Context will fill up — have a way to make room\"* — Four-layer compression pipeline: cheap first, expensive last.\n>\n> **Harness Layer**: Compression — clean memory, unlimited sessions.\n\n---\n\n## The Problem\n\nThe agent is running along, then freezes.\n\nIt has bash, read, write — all the capabilities it needs. But it read a 1000-line file (~4000 tokens), then read 30 more files, ran 20 commands. Every command's output, every file's contents, all pile up in the `messages` list.\n\nThe context window is finite. Once full, the API outright rejects the call: `prompt_too_long`.\n\nWithout compression, an agent simply cannot work on large projects.\n\n---\n\n## The Solution\n\n![Compact Overview](/course-assets/s08_context_compact/compact-overview.en.svg)\n\nThe hook structure, skill loading, and sub-Agent from s07 are preserved, with some tools omitted to focus on compaction. The core change: insert three pre-processors (0 API calls) before each LLM call, trigger an LLM summary (1 API call) when tokens still exceed the threshold, and emergency-trim if the API throws an error.\n\nCore design: cheap first, expensive last.\n\n> **Boundary with s09:** s08 manages the current session's finite context and may lose detail while compressing it. s09 adds a separate durable store for selected information that must survive compaction and future sessions. They solve different failure modes, so they remain separate lessons.\n\n---\n\n## How It Works\n\n![Four-layer compression pipeline](/course-assets/s08_context_compact/compaction-layers.en.svg)\n\n### L1: snip_compact — Trim Irrelevant Old Conversation\n\nThe agent ran 80 turns of conversation, accumulating 160 `messages`. The very first \"help me create hello.py\" is barely relevant to current work, yet it still occupies space.\n\nMessage count exceeds 50 → keep the first 3 (initial context) and the last 47 (current work), trim the middle; the only extra boundary rule is that `assistant(tool_use)` must not be separated from the following `user(tool_result)`:\n\n```python\ndef snip_compact(messages, max_messages=50):\n    if len(messages) <= max_messages:\n        return messages\n    head_end, tail_start = 3, len(messages) - (max_messages - 3)\n    if head_end > 0 and _message_has_tool_use(messages[head_end - 1]):\n        while head_end < len(messages) and _is_tool_result_message(messages[head_end]):\n            head_end += 1\n    if (tail_start > 0 and tail_start < len(messages)\n            and _is_tool_result_message(messages[tail_start])\n            and _message_has_tool_use(messages[tail_start - 1])):\n        tail_start -= 1\n    snipped = tail_start - head_end\n    placeholder = {\"role\": \"user\", \"content\": f\"[snipped {snipped} messages from conversation middle]\"}\n    return messages[:head_end] + [placeholder] + messages[tail_start:]\n```\n\nMessages are still trimmed directly; this just adds one boundary guard. `tool_result` content within remaining messages still keeps accumulating — message #34 may still hold 30KB of old file contents. → L2.\n\n### L2: micro_compact — Placeholder for Old Tool Results\n\n![Old results placeholder](/course-assets/s08_context_compact/micro-compact.en.svg)\n\nThe agent read 10 files consecutively. The full contents of reads 1–7 are still sitting in context, no longer needed, but hogging large amounts of space.\n\nKeep only the 3 most recent `tool_result` entries intact; replace older ones with a one-line placeholder:\n\n```python\nKEEP_RECENT_TOOL_RESULTS = 3\n\ndef micro_compact(messages):\n    tool_results = collect_tool_result_blocks(messages)\n    if len(tool_results) <= KEEP_RECENT_TOOL_RESULTS:\n        return messages\n    for _, _, block in tool_results[:-KEEP_RECENT_TOOL_RESULTS]:\n        if len(block.get(\"content\", \"\")) > 120:\n            block[\"content\"] = \"[Earlier tool result compacted. Re-run if needed.]\"\n    return messages\n```\n\nOld results are cleared, but a single new result can be 500KB — one `cat` of a large file can max out the context. → L3.\n\n### L3: tool_result_budget — Persist Large Results to Disk\n\n![Large results to disk](/course-assets/s08_context_compact/layer1-budget.en.svg)\n\nThe model read 5 large files in one go; all `tool_result` blocks in the last user message total 500KB.\n\nSum the size of all `tool_result` blocks in the last user message. If over 200KB → sort by size, starting from the largest, persist to `.task_outputs/tool-results/`, keeping only a `<persisted-output>` marker + a 2000-character preview in context. The model sees the marker and knows the full content is on disk, re-reading it when needed.\n\n```python\ndef tool_result_budget(messages, max_bytes=200_000):\n    last = messages[-1]\n    blocks = [(i, b) for i, b in enumerate(last[\"content\"])\n              if b.get(\"type\") == \"tool_result\"]\n    total = sum(len(str(b.get(\"content\", \"\"))) for _, b in blocks)\n    if total <= max_bytes:\n        return messages\n    ranked = sorted(blocks, key=lambda p: len(str(p[1].get(\"content\", \"\"))), reverse=True)\n    for idx, block in ranked:\n        if total <= max_bytes:\n            break\n        block[\"content\"] = persist_large_output(block[\"tool_use_id\"], str(block[\"content\"]))\n        total = recalculate_total(blocks)\n    return messages\n```\n\nThe first three layers are all plain-text / structural operations — 0 API calls — but they cannot \"understand\" conversation content. Context may still be too large. → L4.\n\n### L4: compact_history — Full LLM Summary\n\n![Full LLM summary](/course-assets/s08_context_compact/auto-compact.en.svg)\n\nAll three previous layers have run, but after 30 minutes of continuous work on a huge project, tokens still exceed the threshold.\n\nThree-step process:\n\n1. **Save transcript**: Write the full conversation to `.transcripts/` in JSONL format. The transcript keeps a complete record; the message list keeps only the summary, so the original details no longer enter later model calls.\n2. **LLM generates summary**: Send conversation history to the LLM, asking it to preserve key information: current goals, important findings, modified files, remaining work, user constraints, etc.\n3. **Replace message list**: All old messages are replaced with a single summary.\n\n```python\ndef compact_history(messages):\n    transcript_path = write_transcript(messages)  # Save full conversation first\n    summary = summarize_history(messages)          # LLM generates summary\n    return [{\"role\": \"user\",\n             \"content\": f\"[Compacted]\\n\\n{summary}\"}]\n```\n\n**Circuit breaker**: After 3 consecutive failures, stop retrying to prevent an infinite loop wasting API calls.\n\n### Reactive: reactive_compact\n\nSometimes the API still returns `prompt_too_long` (413) — when context grows faster than compression triggers.\n\nThis triggers **reactive_compact**: more aggressive than compact_history in trigger (emergency response to a 413 error), but more conservative in what it removes, keeping ~5 recent messages and only summarizing earlier history. Still avoids an orphaned `tool_result`.\n\n```python\ndef reactive_compact(messages):\n    transcript = write_transcript(messages)\n    tail_start = max(0, len(messages) - 5)\n    if (tail_start > 0 and tail_start < len(messages)\n            and _is_tool_result_message(messages[tail_start])\n            and _message_has_tool_use(messages[tail_start - 1])):\n        tail_start -= 1\n    summary = summarize_history(messages[:tail_start])\n    return [{\"role\": \"user\",\n             \"content\": f\"[Reactive compact]\\n\\n{summary}\"}, *messages[tail_start:]]\n```\n\nReactive compact has a retry limit (default 1). If it still fails, an exception is raised instead of looping forever. Full error recovery is deferred to s11.\n\n### Putting It All Together\n\n```python\ndef agent_loop(messages):\n    reactive_retries = 0\n    while True:\n        # Three pre-processors (0 API calls)\n        # Order: budget first, so large content is persisted before placeholders\n        messages[:] = tool_result_budget(messages)    # L3: persist large results\n        messages[:] = snip_compact(messages)          # L1: trim middle\n        messages[:] = micro_compact(messages)         # L2: old result placeholders\n\n        # Still too much? LLM summary (1 API call)\n        if estimate_token_count(messages) > THRESHOLD:\n            messages[:] = compact_history(messages)\n\n        try:\n            response = client.messages.create(...)\n        except PromptTooLongError:\n            if reactive_retries < MAX_REACTIVE_RETRIES:\n                messages[:] = reactive_compact(messages)  # Emergency\n                reactive_retries += 1\n                continue\n            raise  # retry limit exceeded, raise exception\n        # ... tool execution ...\n\n        # compact tool: when the model actively calls it, triggers compact_history\n        if block.name == \"compact\":\n            messages[:] = compact_history(messages)\n            results.append({..., \"content\": \"[Compacted. History summarized.]\"})\n            messages.append({\"role\": \"user\", \"content\": results})\n            break  # end current turn, start fresh with compacted context\n```\n\n**The order must not be swapped.** L3 (budget) runs before L2 (micro) because micro replaces old large tool_results with one-line placeholders, so budget must persist the full content first.\n\n---\n\n## Changes From s07\n\n| Component | Before (s07) | After (s08) |\n|-----------|-------------|-------------|\n| Context management | None (context grows unbounded) | Four-layer compression pipeline + emergency |\n| New functions | — | snip_compact, micro_compact, tool_result_budget, compact_history, reactive_compact |\n| Tools | bash, read_file, write_file, edit_file, glob, todo_write, task, load_skill (8) | 8 + compact (9) |\n| Loop | LLM call → tool execution | Three pre-processors before each turn + threshold-triggered compact_history |\n| Design principle | — | Cheap first, expensive last |\n\n---\n\n## Try It\n\n```sh\ncd learn-claude-code\npython s08_context_compact/code.py\n```\n\nTry these prompts:\n\n1. `Read the file README.md, then read code.py, then read s01_agent_loop/README.md` (read multiple files consecutively, observe L2 compressing old results)\n2. `Read every file in s08_context_compact/` (read a large amount of content at once, observe L3 persisting to disk)\n3. Chat for 20+ turns, observe whether `[auto compact]` or `[reactive compact]` appears\n\nWhat to watch for: After each tool execution, are old `tool_result` entries compressed? When tokens exceed the threshold after extended conversation, is summarization triggered automatically?\n\n---\n\n## What's Next\n\nContext compression lets an agent run for a long time without crashing. But after each compression, the preferences and constraints the user told it are also lost. Can we let the agent selectively remember important things?\n\ns09 Memory → three subsystems: choosing what to remember, extracting key information, consolidating and organizing. Across compressions, across sessions.\n\n\n<!-- translation-sync: zh@v2, en@v2, ja@v2 -->\n"
  },
  {
    "version": "s08",
    "locale": "zh",
    "title": "s08: Context Compact — 上下文总会满，要有办法腾地方",
    "content": "# s08: Context Compact — 上下文总会满，要有办法腾地方\n\ns01 → s02 → s03 → s04 → s05 → s06 → s07 → `s08` → [s09](/zh/s09) → s10 → ... → s20 → s21\n> *\"上下文总会满, 要有办法腾地方\"* — 四层压缩策略, 便宜的先跑贵的后跑。\n>\n> **Harness 层**: 压缩 — 干净的记忆, 无限的会话。\n\n---\n\n## 问题\n\nAgent 跑着跑着，不动了。\n\n手里有 bash、有 read、有 write，能力是够的。但它读了一个 1000 行的文件（~4000 token），又读了 30 个文件，跑了 20 条命令。每条命令的输出、每个文件的内容，全都堆在 `messages` 列表里。\n\n上下文窗口是有限的。满了之后，API 直接拒绝：`prompt_too_long`。\n\n不压缩，Agent 根本没法在大项目里干活。\n\n---\n\n## 解决方案\n\n![Compact Overview](/course-assets/s08_context_compact/compact-overview.svg)\n\n保留 s07 的 hook 结构、技能加载、子 Agent 等骨架，省略部分工具细节以聚焦压缩。核心变动：每轮 LLM 调用前插入三层预处理器（0 API），token 仍超阈值时触发 LLM 摘要（1 API），API 报错时应急裁剪。\n\n核心设计：便宜的先跑，贵的后跑。\n\n> **与 s09 的边界：** s08 管理当前会话有限的上下文，压缩时允许丢失细节；s09 另建持久存储，只保留需要跨压缩、跨会话存在的信息。两章解决的是不同故障，因此不合并。\n\n---\n\n## 工作原理\n\n![四层压缩管线](/course-assets/s08_context_compact/compaction-layers.svg)\n\n### L1: snip_compact — 裁掉无关的旧对话\n\nAgent 跑了 80 轮对话，`messages` 攒了 160 条。最前面的\"帮我创建 hello.py\"和当前工作几乎无关了，但全占着位置。\n\n消息数超过 50 条 → 保留头部 3 条（初始上下文）和尾部 47 条（当前工作），中间裁掉；唯一额外边界条件是，不能把 `assistant(tool_use)` 和后面的 `user(tool_result)` 拆开：\n\n```python\ndef snip_compact(messages, max_messages=50):\n    if len(messages) <= max_messages:\n        return messages\n    head_end, tail_start = 3, len(messages) - (max_messages - 3)\n    if head_end > 0 and _message_has_tool_use(messages[head_end - 1]):\n        while head_end < len(messages) and _is_tool_result_message(messages[head_end]):\n            head_end += 1\n    if (tail_start > 0 and tail_start < len(messages)\n            and _is_tool_result_message(messages[tail_start])\n            and _message_has_tool_use(messages[tail_start - 1])):\n        tail_start -= 1\n    snipped = tail_start - head_end\n    placeholder = {\"role\": \"user\", \"content\": f\"[snipped {snipped} messages from conversation middle]\"}\n    return messages[:head_end] + [placeholder] + messages[tail_start:]\n```\n\n裁掉的是消息本身，只是在切口处多做一步保护；剩下的消息里 `tool_result` 内容仍在累积——第 34 条消息里可能躺着 30KB 的旧文件内容。→ L2。\n\n### L2: micro_compact — 旧工具结果占位\n\n![旧结果占位](/course-assets/s08_context_compact/micro-compact.svg)\n\nAgent 连续读了 10 个文件。第 1-7 次的完整内容还躺在上下文里，早就不需要了，但占着大量空间。\n\n只保留最近 3 条 `tool_result` 的完整内容，更旧的替换为一行占位符：\n\n```python\nKEEP_RECENT_TOOL_RESULTS = 3\n\ndef micro_compact(messages):\n    tool_results = collect_tool_result_blocks(messages)\n    if len(tool_results) <= KEEP_RECENT_TOOL_RESULTS:\n        return messages\n    for _, _, block in tool_results[:-KEEP_RECENT_TOOL_RESULTS]:\n        if len(block.get(\"content\", \"\")) > 120:\n            block[\"content\"] = \"[Earlier tool result compacted. Re-run if needed.]\"\n    return messages\n```\n\n旧结果清掉了，但单条新结果可能就有 500KB——一个 `cat` 大文件的输出就能打满上下文。→ L3。\n\n### L3: tool_result_budget — 大结果落盘\n\n![大结果落盘](/course-assets/s08_context_compact/layer1-budget.svg)\n\n模型一次读了 5 个大文件，单条 user 消息里所有 `tool_result` 加起来 500KB。\n\n统计最后一条 user 消息里所有 `tool_result` 的总大小。超过 200KB → 按大小排序，从最大的开始落盘到 `.task_outputs/tool-results/`，上下文里只留 `<persisted-output>` 标记 + 前 2000 字符预览。模型看到标记后知道完整内容在磁盘上，需要时可以重新读。\n\n```python\ndef tool_result_budget(messages, max_bytes=200_000):\n    last = messages[-1]\n    blocks = [(i, b) for i, b in enumerate(last[\"content\"])\n              if b.get(\"type\") == \"tool_result\"]\n    total = sum(len(str(b.get(\"content\", \"\"))) for _, b in blocks)\n    if total <= max_bytes:\n        return messages\n    ranked = sorted(blocks, key=lambda p: len(str(p[1].get(\"content\", \"\"))), reverse=True)\n    for idx, block in ranked:\n        if total <= max_bytes:\n            break\n        block[\"content\"] = persist_large_output(block[\"tool_use_id\"], str(block[\"content\"]))\n        total = recalculate_total(blocks)\n    return messages\n```\n\n前三层都是纯文本/结构操作，0 API 调用，但也无法\"理解\"对话内容。上下文可能仍然太大。→ L4。\n\n### L4: compact_history — LLM 全量摘要\n\n![LLM 全量摘要](/course-assets/s08_context_compact/auto-compact.svg)\n\n前三层全跑完了，但在超大项目中连续工作 30 分钟后，token 仍然超过阈值。\n\n三步流程：\n\n1. **保存 transcript**：完整对话写入 `.transcripts/`，JSONL 格式。transcript 保留完整记录；消息列表只保留摘要，原始细节不再进入后续模型调用。\n2. **LLM 生成摘要**：把对话历史发给 LLM，要求保留当前目标、重要发现、已改文件、剩余工作、用户约束等关键信息。\n3. **替换消息列表**：所有旧消息被替换为一条摘要。\n\n```python\ndef compact_history(messages):\n    transcript_path = write_transcript(messages)  # 先保存完整对话\n    summary = summarize_history(messages)          # LLM 生成摘要\n    return [{\"role\": \"user\",\n             \"content\": f\"[Compacted]\\n\\n{summary}\"}]\n```\n\n**熔断器**：连续失败 3 次后停止重试，防止死循环浪费 API 调用。\n\n### 应急: reactive_compact\n\n有时候 API 还是返回 `prompt_too_long`（413），上下文增长速度快于压缩触发速度时。\n\n这时触发 **reactive_compact**：触发方式比 compact_history 更激进（API 报错后的应急手段），但压缩策略更温和，保留最近约 5 条原始消息，只总结较早历史。同样避免留下孤立 `tool_result`。\n\n```python\ndef reactive_compact(messages):\n    transcript = write_transcript(messages)\n    tail_start = max(0, len(messages) - 5)\n    if (tail_start > 0 and tail_start < len(messages)\n            and _is_tool_result_message(messages[tail_start])\n            and _message_has_tool_use(messages[tail_start - 1])):\n        tail_start -= 1\n    summary = summarize_history(messages[:tail_start])\n    return [{\"role\": \"user\",\n             \"content\": f\"[Reactive compact]\\n\\n{summary}\"}, *messages[tail_start:]]\n```\n\nreactive compact 有重试上限（默认 1 次）。再失败就抛出异常，不无限循环。完整的错误恢复逻辑留给 s11。\n\n### 合起来跑\n\n```python\ndef agent_loop(messages):\n    reactive_retries = 0\n    while True:\n        # 三个预处理器（0 API 调用）\n        # 顺序：budget 先跑，确保大内容落盘后再做占位和裁剪\n        messages[:] = tool_result_budget(messages)    # L3: 大结果落盘\n        messages[:] = snip_compact(messages)          # L1: 裁中间\n        messages[:] = micro_compact(messages)         # L2: 旧结果占位\n\n        # 还不够？LLM 摘要（1 API 调用）\n        if estimate_token_count(messages) > THRESHOLD:\n            messages[:] = compact_history(messages)\n\n        try:\n            response = client.messages.create(...)\n        except PromptTooLongError:\n            if reactive_retries < MAX_REACTIVE_RETRIES:\n                messages[:] = reactive_compact(messages)  # 应急\n                reactive_retries += 1\n                continue\n            raise  # 超过重试上限，抛出异常\n        # ... 工具执行 ...\n\n        # compact 工具：模型主动调用时触发 compact_history\n        if block.name == \"compact\":\n            messages[:] = compact_history(messages)\n            results.append({..., \"content\": \"[Compacted. History summarized.]\"})\n            messages.append({\"role\": \"user\", \"content\": results})\n            break  # 结束当前 turn，用压缩后的上下文开始新一轮\n```\n\n**顺序不能换。** L3（budget）在 L2（micro）前面，因为 micro 会把旧的大 `tool_result` 替换成一行占位符，budget 必须在那之前保存完整内容。\n\n---\n\n## 相对 s07 的变更\n\n| 组件 | 之前 (s07) | 之后 (s08) |\n|------|-----------|-----------|\n| 上下文管理 | 无（上下文无限膨胀） | 四层压缩管线 + 应急 |\n| 新函数 | — | snip_compact, micro_compact, tool_result_budget, compact_history, reactive_compact |\n| 工具 | bash, read, write, edit, glob, todo_write, task, load_skill (8) | 8 + compact (9) |\n| 循环 | LLM 调用 → 工具执行 | 每轮前跑三层预处理器 + 阈值触发 compact_history |\n| 设计原则 | — | 便宜的先跑，贵的后跑 |\n\n---\n\n## 试一下\n\n```sh\ncd learn-claude-code\npython s08_context_compact/code.py\n```\n\n试试这些 prompt：\n\n1. `Read the file README.md, then read code.py, then read s01_agent_loop/README.md`（连续读多个文件，观察 L2 压缩旧结果）\n2. `Read every file in s08_context_compact/`（一次性读大量内容，观察 L3 落盘）\n3. 反复对话 20+ 轮，观察是否出现 `[auto compact]` 或 `[reactive compact]`\n\n观察重点：每次工具执行后，旧 tool_result 是否被压缩？连续对话后 token 超阈值时，是否自动触发了摘要？\n\n---\n\n## 接下来\n\n上下文压缩让 Agent 能跑很久不会崩。但每次压缩后，用户之前告诉它的偏好、约束也跟着丢了。能不能让 Agent 有选择地记住重要的事？\n\ns09 Memory → 三个子系统：选择记什么、提取关键信息、整理巩固。跨压缩、跨会话。\n\n\n<!-- translation-sync: zh@v2, en@v2, ja@v2 -->\n"
  },
  {
    "version": "s08",
    "locale": "ja",
    "title": "s08: Context Compact — コンテキストはいつか満杯になる、場所を空ける方法が必要",
    "content": "# s08: Context Compact — コンテキストはいつか満杯になる、場所を空ける方法が必要\n\ns01 → s02 → s03 → s04 → s05 → s06 → s07 → `s08` → [s09](/ja/s09) → s10 → ... → s20 → s21\n> *\"Context will fill up — have a way to make room\"* — 4層圧縮戦略、安価なものを先に、高価なものを後に実行。\n>\n> **Harness レイヤー**: 圧縮 — クリーンな記憶、無限のセッション。\n\n---\n\n## 課題\n\nAgent が動いている途中で、止まってしまう。\n\nbash、read、write は揃っており、能力は十分。しかし 1000 行のファイル（~4000 token）を読み、さらに 30 のファイルを読み、20 のコマンドを実行したとします。各コマンドの出力、各ファイルの内容がすべて `messages` リストに蓄積されます。\n\nコンテキストウィンドウには上限があります。満杯になると、API は即座に拒否します：`prompt_too_long`。\n\n圧縮しなければ、Agent は大規模プロジェクトではまともに動けません。\n\n---\n\n## ソリューション\n\n![Compact Overview](/course-assets/s08_context_compact/compact-overview.ja.svg)\n\ns07 のフック構造、スキルロード、サブ Agent の骨格を維持し、圧縮に焦点を当てるため一部のツールは省略。コアの変更点：各 LLM 呼び出し前に 3 層のプリプロセッサ（0 API）を挿入し、token が閾値を超えた場合は LLM 要約（1 API）をトリガー、API エラー時には緊急トリムを実行。\n\nコア設計：安価なものを先に、高価なものを後に。\n\n> **s09 との境界：** s08 は現在のセッションの有限なコンテキストを管理し、圧縮では詳細を失うことがある。s09 は圧縮後や将来のセッションにも残す情報だけを別の永続ストアに保存する。異なる障害を解くため、別のセッションとして扱う。\n\n---\n\n## 仕組み\n\n![4層圧縮パイプライン](/course-assets/s08_context_compact/compaction-layers.ja.svg)\n\n### L1: snip_compact — 無関係な古い会話を切り捨て\n\nAgent が 80 ラウンドの会話を実行し、`messages` が 160 件まで溜まった。先頭の「hello.py を作って」は現在の作業とほぼ無関係だが、スペースを占有し続けている。\n\nメッセージ数が 50 を超えた場合 → 先頭 3 件（初期コンテキスト）と末尾 47 件（現在の作業）を保持して中間を切り詰める。ただし切れ目だけは調整し、`assistant(tool_use)` と後続の `user(tool_result)` を分断しない：\n\n```python\ndef snip_compact(messages, max_messages=50):\n    if len(messages) <= max_messages:\n        return messages\n    head_end, tail_start = 3, len(messages) - (max_messages - 3)\n    if head_end > 0 and _message_has_tool_use(messages[head_end - 1]):\n        while head_end < len(messages) and _is_tool_result_message(messages[head_end]):\n            head_end += 1\n    if (tail_start > 0 and tail_start < len(messages)\n            and _is_tool_result_message(messages[tail_start])\n            and _message_has_tool_use(messages[tail_start - 1])):\n        tail_start -= 1\n    snipped = tail_start - head_end\n    placeholder = {\"role\": \"user\", \"content\": f\"[snipped {snipped} messages from conversation middle]\"}\n    return messages[:head_end] + [placeholder] + messages[tail_start:]\n```\n\n切り捨て自体は単純なままで、境界だけを保護する。残ったメッセージ内の `tool_result` 内容はまだ蓄積され続けている。34 番目のメッセージに 30KB の古いファイル内容が残っているかもしれない。→ L2。\n\n### L2: micro_compact — 古いツール結果をプレースホルダに置換\n\n![古い結果のプレースホルダ](/course-assets/s08_context_compact/micro-compact.ja.svg)\n\nAgent が連続して 10 個のファイルを読んだ。1〜7 回目の完全な内容はまだコンテキストに残っており、もう不要だが、大量のスペースを占有している。\n\n直近 3 件の `tool_result` の完全な内容のみを保持し、それより古いものは 1 行のプレースホルダに置換：\n\n```python\nKEEP_RECENT_TOOL_RESULTS = 3\n\ndef micro_compact(messages):\n    tool_results = collect_tool_result_blocks(messages)\n    if len(tool_results) <= KEEP_RECENT_TOOL_RESULTS:\n        return messages\n    for _, _, block in tool_results[:-KEEP_RECENT_TOOL_RESULTS]:\n        if len(block.get(\"content\", \"\")) > 120:\n            block[\"content\"] = \"[Earlier tool result compacted. Re-run if needed.]\"\n    return messages\n```\n\n古い結果はクリーンアップされたが、1 件の新しい結果だけで 500KB の可能性がある。大きなファイルを `cat` するだけでコンテキストがいっぱいになる。→ L3。\n\n### L3: tool_result_budget — 大きな結果をディスクに退避\n\n![大きな結果のディスク退避](/course-assets/s08_context_compact/layer1-budget.ja.svg)\n\nモデルが一度に 5 つの大きなファイルを読み、1 つの user メッセージ内の全 `tool_result` の合計が 500KB に達した。\n\n最後の user メッセージ内のすべての `tool_result` の合計サイズを集計。200KB を超えた場合 → サイズ順にソートし、最大のものから順に `.task_outputs/tool-results/` に退避。コンテキストには `<persisted-output>` マーカー + 先頭 2000 文字のプレビューのみを残す。モデルはマーカーを見て完全な内容がディスク上にあることを認識し、必要に応じて再読み込みできる。\n\n```python\ndef tool_result_budget(messages, max_bytes=200_000):\n    last = messages[-1]\n    blocks = [(i, b) for i, b in enumerate(last[\"content\"])\n              if b.get(\"type\") == \"tool_result\"]\n    total = sum(len(str(b.get(\"content\", \"\"))) for _, b in blocks)\n    if total <= max_bytes:\n        return messages\n    ranked = sorted(blocks, key=lambda p: len(str(p[1].get(\"content\", \"\"))), reverse=True)\n    for idx, block in ranked:\n        if total <= max_bytes:\n            break\n        block[\"content\"] = persist_large_output(block[\"tool_use_id\"], str(block[\"content\"]))\n        total = recalculate_total(blocks)\n    return messages\n```\n\n最初の 3 層はすべて純粋なテキスト/構造操作（0 API 呼び出し）だが、会話内容を「理解」することはできない。コンテキストがまだ大きすぎる可能性がある。→ L4。\n\n### L4: compact_history — LLM 全量要約\n\n![LLM 全量要約](/course-assets/s08_context_compact/auto-compact.ja.svg)\n\n最初の 3 層がすべて実行されたが、超大規模プロジェクトで 30 分間連続作業すると、token がまだ閾値を超えている。\n\n3 ステップのフロー：\n\n1. **transcript を保存**：完全な会話を `.transcripts/` に JSONL 形式で書き出す。transcript は完全な記録を保持する。メッセージリストには要約だけが残り、元の詳細は以降のモデル呼び出しに入らない。\n2. **LLM で要約を生成**：会話履歴を LLM に送り、現在の目標、重要な発見、変更済みファイル、残りの作業、ユーザーの制約などの重要な情報を保持するよう指示。\n3. **メッセージリストを置換**：すべての古いメッセージを 1 件の要約に置き換える。\n\n```python\ndef compact_history(messages):\n    transcript_path = write_transcript(messages)  # 先に完全な会話を保存\n    summary = summarize_history(messages)          # LLM で要約を生成\n    return [{\"role\": \"user\",\n             \"content\": f\"[Compacted]\\n\\n{summary}\"}]\n```\n\n**サーキットブレーカー**：連続 3 回失敗したらリトライを停止し、無限ループによる API 呼び出しの浪費を防止。\n\n### 緊急: reactive_compact\n\nAPI がまだ `prompt_too_long`（413）を返すことがある。コンテキストの増加速度が圧縮のトリガー速度を上回る場合。\n\nこの時 **reactive_compact** がトリガーされる。トリガー方式は compact_history より積極的（413 エラー後の緊急対応）だが、圧縮方針はより温和で、末尾約 5 件のメッセージを保持し、早期の履歴だけを要約する。孤立した `tool_result` を残さないよう配慮する。\n\n```python\ndef reactive_compact(messages):\n    transcript = write_transcript(messages)\n    tail_start = max(0, len(messages) - 5)\n    if (tail_start > 0 and tail_start < len(messages)\n            and _is_tool_result_message(messages[tail_start])\n            and _message_has_tool_use(messages[tail_start - 1])):\n        tail_start -= 1\n    summary = summarize_history(messages[:tail_start])\n    return [{\"role\": \"user\",\n             \"content\": f\"[Reactive compact]\\n\\n{summary}\"}, *messages[tail_start:]]\n```\n\nreactive compact にはリトライ上限がある（デフォルト 1 回）。さらに失敗した場合は例外をスローし、無限ループしない。完全なエラー回復ロジックは s11 に委ねる。\n\n### 合わせて実行\n\n```python\ndef agent_loop(messages):\n    reactive_retries = 0\n    while True:\n        # 3 つのプリプロセッサ（0 API 呼び出し）\n        # 順序：budget を先に実行し、大きな内容をプレースホルダ化する前に退避\n        messages[:] = tool_result_budget(messages)    # L3: 大きな結果を退避\n        messages[:] = snip_compact(messages)          # L1: 中間を切り捨て\n        messages[:] = micro_compact(messages)         # L2: 古い結果をプレースホルダに\n\n        # まだ足りない？LLM 要約（1 API 呼び出し）\n        if estimate_token_count(messages) > THRESHOLD:\n            messages[:] = compact_history(messages)\n\n        try:\n            response = client.messages.create(...)\n        except PromptTooLongError:\n            if reactive_retries < MAX_REACTIVE_RETRIES:\n                messages[:] = reactive_compact(messages)  # 緊急対応\n                reactive_retries += 1\n                continue\n            raise  # リトライ上限超過、例外をスロー\n        # ... ツール実行 ...\n\n        # compact ツール：モデルが能動的に呼び出した場合、compact_history をトリガー\n        if block.name == \"compact\":\n            messages[:] = compact_history(messages)\n            results.append({..., \"content\": \"[Compacted. History summarized.]\"})\n            messages.append({\"role\": \"user\", \"content\": results})\n            break  # 現在のターンを終了し、圧縮後のコンテキストで新しく開始\n```\n\n**順序は変えられない。** L3（budget）は L2（micro）より先に実行する。micro が古い大きな `tool_result` を 1 行のプレースホルダに置き換える前に、budget が完全な内容を保存する必要があるためだ。\n\n---\n\n## s07 からの変更点\n\n| コンポーネント | 変更前 (s07) | 変更後 (s08) |\n|------|-----------|-----------|\n| コンテキスト管理 | なし（コンテキストが無限に膨張） | 4 層圧縮パイプライン + 緊急対応 |\n| 新規関数 | — | snip_compact, micro_compact, tool_result_budget, compact_history, reactive_compact |\n| ツール | bash, read_file, write_file, edit_file, glob, todo_write, task, load_skill (8) | 8 + compact (9) |\n| ループ | LLM 呼び出し → ツール実行 | 各ラウンド前に 3 層プリプロセッサを実行 + 閾値で compact_history をトリガー |\n| 設計原則 | — | 安価なものを先に、高価なものを後に |\n\n---\n\n## 試してみよう\n\n```sh\ncd learn-claude-code\npython s08_context_compact/code.py\n```\n\n以下のプロンプトを試してみてください：\n\n1. `Read the file README.md, then read code.py, then read s01_agent_loop/README.md`（連続して複数のファイルを読み、L2 の古い結果圧縮を観察）\n2. `Read every file in s08_context_compact/`（一度に大量の内容を読み込み、L3 のディスク退避を観察）\n3. 20+ ラウンドの対話を繰り返し、`[auto compact]` または `[reactive compact]` が表示されるか観察\n\n観察のポイント：ツール実行のたびに、古い tool_result は圧縮されているか？連続対話で token が閾値を超えたとき、要約が自動的にトリガーされたか？\n\n---\n\n## 次へ\n\nコンテキスト圧縮により、Agent は長時間クラッシュせずに動けるようになった。しかし、圧縮のたびにユーザーが以前に伝えた偏好や制約も一緒に失われてしまう。Agent が重要なことを選択的に記憶できるようにできないか？\n\ns09 Memory → 3 つのサブシステム：何を記憶するかの選択、重要情報の抽出、整理と統合。圧縮を越え、セッションを越えて。\n\n\n<!-- translation-sync: zh@v2, en@v2, ja@v2 -->\n"
  },
  {
    "version": "s09",
    "locale": "en",
    "title": "s09: Memory — Compression Loses Details, Keep a Layer That Doesn't",
    "content": "# s09: Memory — Compression Loses Details, Keep a Layer That Doesn't\n\ns01 → ... → s07 → s08 → `s09` → [s10](/en/s10) → s11 → ... → s20 → s21\n> *\"Compression loses details, keep a layer that doesn't\"* — File store + index + on-demand loading, across compactions, across sessions.\n>\n> **Harness Layer**: Memory — knowledge that survives compaction and sessions.\n\n---\n\n## The Problem\n\ns08's autoCompact preserves current goals, remaining work, and user constraints in the summary, but details get lost: \"use tabs not spaces\" might get simplified to \"user has code style preferences\". And when you start a new session, even the summary is gone.\n\nLLMs have no persistent state; all information lives in the context window. When context fills up, it gets compressed, and compression is lossy. What's needed is a storage layer that doesn't participate in compression and persists across sessions.\n\n---\n\n## The Solution\n\n![Memory Overview](/course-assets/s09_memory/memory-overview.en.svg)\n\nThe s08 compression pipeline is preserved, focusing on memory. Storage uses the filesystem: a `.memory/` directory where each memory is a `.md` file with YAML frontmatter (`name` / `description` / `type`). When files accumulate, an index is needed: `MEMORY.md` holds one link per line and gets injected into the SYSTEM.\n\nKey design: the index stays in SYSTEM prompt (cacheable by prompt cache), file content is injected on demand (matched by filename/description to the current conversation, without breaking the cache). Writing has two paths: the user explicitly says \"remember\", or extraction runs in the background after each turn. When files accumulate, periodic consolidation deduplicates.\n\n> **Boundary with s08:** compaction still owns the current transcript and token budget. Memory does not replace that pipeline; it selectively persists facts outside the transcript and recalls them later.\n\nFour memory types, each answering a different question:\n\n| Type | Answers | Example |\n|------|---------|---------|\n| user | Who you are | \"Use tabs not spaces\" |\n| feedback | How to work | \"Don't mock the database\" |\n| project | What's happening | \"Auth rewrite is compliance-driven\" |\n| reference | Where to find things | \"Pipeline bugs are in Linear INGEST\" |\n\n---\n\n## How It Works\n\n![Memory Subsystems](/course-assets/s09_memory/memory-subsystems.en.svg)\n\n### Storage: Markdown Files + Index\n\nEach memory is a `.md` file with YAML frontmatter for metadata:\n\n```markdown\n---\nname: user-preference-tabs\ndescription: User prefers tabs for indentation\ntype: user\n---\n\nUser prefers using tabs, not spaces, for indentation.\n**Why:** Consistency with existing codebase conventions.\n**How to apply:** Always use tabs when writing or editing files.\n```\n\n`MEMORY.md` is the index, one link per line:\n\n```markdown\n- [user-preference-tabs](user-preference-tabs.md) — User prefers tabs for indentation\n```\n\nWriting a new memory automatically rebuilds the index:\n\n```python\ndef write_memory_file(name, mem_type, description, body):\n    slug = name.lower().replace(\" \", \"-\")\n    filepath = MEMORY_DIR / f\"{slug}.md\"\n    filepath.write_text(\n        f\"---\\nname: {name}\\ndescription: {description}\\ntype: {mem_type}\\n---\\n\\n{body}\\n\"\n    )\n    _rebuild_index()\n```\n\n### Loading: Two Paths\n\n**Path 1: Index in SYSTEM.** `build_system()` reads `MEMORY.md` once at the start of each user request and injects the memory catalog into the SYSTEM prompt. Memory extraction and consolidation run only when the turn ends, so SYSTEM does not need to be rebuilt repeatedly within the same user request.\n\n**Path 2: Relevant memories on demand.** At the start of each user request, `load_memories()` sends the recent conversation and the memory catalog (name + description) to the LLM as a lightweight side-query, selects relevant filenames, then reads and injects their contents. Capped at 5 to control cost.\n\n```python\ndef select_relevant_memories(messages, max_items=5):\n    files = list_memory_files()\n    if not files:\n        return []\n\n    # Build catalog: \"0: user-preference-tabs — User prefers tabs...\"\n    catalog = \"\\n\".join(f\"{i}: {f['name']} — {f['description']}\" for i, f in enumerate(files))\n\n    response = client.messages.create(model=MODEL, messages=[{\"role\": \"user\",\n        \"content\": f\"Select relevant memory indices. Return JSON array.\\n\\n\"\n                   f\"Recent conversation:\\n{recent}\\n\\nMemory catalog:\\n{catalog}\"}],\n        max_tokens=200)\n    indices = json.loads(re.search(r'\\[.*?\\]', response.content[0].text).group())\n    return [files[i][\"filename\"] for i in indices if 0 <= i < len(files)]\n```\n\nIf the side-query fails (API error, JSON parse failure), it falls back to keyword matching on name + description.\n\n### Writing: Extraction After Each Turn\n\nUsers don't always say \"remember this\". Preferences are usually scattered across normal dialogue: \"tabs are better than spaces\", \"let's use single quotes from now on\".\n\n`extract_memories()` runs when each turn ends, triggered when the model stops without a tool_use (indicating the conversation has reached a natural break):\n\n```python\n# In agent_loop:\nif response.stop_reason != \"tool_use\":\n    extract_memories(messages)   # Extract new memories from recent dialogue\n    consolidate_memories()       # Check if consolidation is needed\n    return\n```\n\nBefore extraction, existing memories are checked to avoid duplicates. The extraction prompt asks the LLM to return a JSON array of `{name, type, description, body}`, writing files only when genuinely new information is found.\n\n```python\ndef extract_memories(messages):\n    dialogue = format_recent_messages(messages[-10:])\n    existing = \"\\n\".join(f\"- {m['name']}: {m['description']}\" for m in list_memory_files())\n\n    prompt = (\n        \"Extract user preferences, constraints, or project facts.\\n\"\n        \"Return JSON array: [{name, type, description, body}].\\n\"\n        \"If nothing new or already covered, return [].\\n\\n\"\n        f\"Existing memories:\\n{existing}\\n\\nDialogue:\\n{dialogue[:4000]}\"\n    )\n    # ... parse response, write files ...\n```\n\n### Consolidation: Low-Frequency Deduplication\n\nMemory files accumulate. `consolidate_memories()` triggers when the file count reaches a threshold (default 10), asking the LLM to deduplicate, merge contradictions, and prune stale memories:\n\n```python\nCONSOLIDATE_THRESHOLD = 10\n\ndef consolidate_memories():\n    files = list_memory_files()\n    if len(files) < CONSOLIDATE_THRESHOLD:\n        return  # Too few, not worth consolidating\n    # Send all memories to LLM, get back deduplicated list\n    # Replace all files with consolidated results\n```\n\n### What Memory Stores\n\nMemory stores information that remains useful across sessions: user preferences, recurring feedback, project background, common entry points, and investigation clues. It focuses on \"what will be useful later\" and brings that information back through an index plus on-demand loading.\n\nSession memory focuses on continuity inside one session: what context should survive after compaction. The two work together: Memory handles long-term knowledge; session memory handles the current session across compaction.\n\n---\n\n## Changes From s08\n\n| Component | Before (s08) | After (s09) |\n|-----------|-------------|-------------|\n| Memory capability | None (preferences degrade with compaction) | Storage + loading + extraction + consolidation |\n| New functions | — | write_memory_file, select_relevant_memories, load_memories, extract_memories, consolidate_memories |\n| Storage | — | .memory/MEMORY.md index + .memory/*.md files |\n| Tools | bash, read, write, edit, glob, todo_write, task, load_skill, compact (9) | bash, read_file, write_file, edit_file, glob, task (6) |\n| Loop | Only compression each turn | Memory injection + compression + post-turn extraction + periodic consolidation |\n\n---\n\n## Try It\n\n```sh\ncd learn-claude-code\npython s09_memory/code.py\n```\n\nTry these prompts (enter across multiple turns, observe memory accumulation and loading):\n\n1. `I prefer using tabs for indentation, not spaces. Remember that.`\n2. `Create a Python file called test.py` (observe whether the Agent uses tabs)\n3. `What did I tell you about my preferences?` (observe whether the Agent remembers)\n4. `I also prefer single quotes over double quotes for strings.`\n\nWhat to watch for: Does `[Memory: extracted N new memories]` appear after each turn? Are `.md` files generated in `.memory/`? Is `MEMORY.md` index updated? Does the Agent automatically load previous memories in new conversations?\n\n---\n\n## What's Next\n\nMemory, compression, and tools are all in place. But the system prompt is still a hardcoded string. Adding a new tool means manually adding a description; switching projects means rewriting the whole prompt. Prompts should be assembled at runtime.\n\ns10 System Prompt → segments + runtime assembly. Different projects, different tools, different prompts.\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s09",
    "locale": "zh",
    "title": "s09: Memory — 压缩会丢细节，要有一层不丢的",
    "content": "# s09: Memory — 压缩会丢细节，要有一层不丢的\n\ns01 → ... → s07 → s08 → `s09` → [s10](/zh/s10) → s11 → ... → s20 → s21\n> *\"压缩会丢细节, 要有一层不丢的\"* — 文件仓库 + 索引 + 按需加载，跨压缩、跨会话。\n>\n> **Harness 层**: 记忆 — 跨压缩、跨会话的知识积累。\n\n---\n\n## 问题\n\ns08 的 autoCompact 会把当前目标、剩余工作、用户约束写进摘要，但细节会丢失：\"用 tab 缩进不要用空格\"可能被简化成\"用户有代码风格偏好\"。而且新开一个会话，连摘要也没了。\n\nLLM 没有持久状态，所有信息都在上下文窗口里。上下文满了要压缩，压缩就有损。需要一层不参与压缩、跨会话保留的存储。\n\n---\n\n## 解决方案\n\n![Memory Overview](/course-assets/s09_memory/memory-overview.svg)\n\ns08 的压缩管线保留，聚焦记忆。存储选文件系统：`.memory/` 目录下，每个记忆一个 `.md` 文件，带 YAML frontmatter（`name` / `description` / `type`）。文件多了需要索引：`MEMORY.md` 一行一个链接，注入 SYSTEM。\n\n关键设计：索引常驻 SYSTEM prompt（可被 prompt cache 缓存），文件内容按需注入到当前 user turn（按 filename/description 匹配当前对话，不破坏 cache）。写入由每轮结束后的提取器完成：用户显式说\"记住\"或表达稳定偏好时，提取器会保存为记忆。文件积累多了，定期整理去重。\n\n> **与 s08 的边界：** 压缩仍负责当前对话和 token 预算；记忆不会取代压缩管线，而是把选中的事实存到对话之外，并在之后按需召回。\n\n四类记忆，各有用途：\n\n| 类型 | 回答什么 | 示例 |\n|------|---------|------|\n| user | 你是谁 | \"用 tab 不用空格\" |\n| feedback | 怎么做事 | \"别 mock 数据库\" |\n| project | 正在发生什么 | \"auth 重写是合规驱动\" |\n| reference | 东西在哪找 | \"pipeline bug 在 Linear INGEST\" |\n\n---\n\n## 工作原理\n\n![Memory Subsystems](/course-assets/s09_memory/memory-subsystems.svg)\n\n### 存储：Markdown 文件 + 索引\n\n每个记忆是一个 `.md` 文件，YAML frontmatter 记录元数据：\n\n```markdown\n---\nname: user-preference-tabs\ndescription: User prefers tabs for indentation\ntype: user\n---\n\nUser prefers using tabs, not spaces, for indentation.\n**Why:** Consistency with existing codebase conventions.\n**How to apply:** Always use tabs when writing or editing files.\n```\n\n`MEMORY.md` 是索引，一行一个链接：\n\n```markdown\n- [user-preference-tabs](user-preference-tabs.md) — User prefers tabs for indentation\n```\n\n写入新记忆时自动重建索引：\n\n```python\ndef write_memory_file(name, mem_type, description, body):\n    slug = name.lower().replace(\" \", \"-\")\n    filepath = MEMORY_DIR / f\"{slug}.md\"\n    filepath.write_text(\n        f\"---\\nname: {name}\\ndescription: {description}\\ntype: {mem_type}\\n---\\n\\n{body}\\n\"\n    )\n    _rebuild_index()\n```\n\n### 加载：两条路径\n\n**路径一：索引常驻 SYSTEM。** `build_system()` 在每次用户请求开始时读取 `MEMORY.md`，把记忆清单注入。记忆提取和整理只在本轮结束时触发，因此同一轮用户请求中不需要重复重建 SYSTEM。\n\n**路径二：相关记忆按需注入。** 每次用户请求开始时，`load_memories()` 把最近对话和记忆目录（name + description）一起发给 LLM 做一次轻量 side-query，选出相关的文件名，再读文件内容临时注入到当前 user turn。最多 5 条，控制开销。\n\n```python\ndef select_relevant_memories(messages, max_items=5):\n    files = list_memory_files()\n    if not files:\n        return []\n\n    # Build catalog: \"0: user-preference-tabs — User prefers tabs...\"\n    catalog = \"\\n\".join(f\"{i}: {f['name']} — {f['description']}\" for i, f in enumerate(files))\n\n    response = client.messages.create(model=MODEL, messages=[{\"role\": \"user\",\n        \"content\": f\"Select relevant memory indices. Return JSON array.\\n\\n\"\n                   f\"Recent conversation:\\n{recent}\\n\\nMemory catalog:\\n{catalog}\"}],\n        max_tokens=200)\n    text = extract_text(response.content).strip()\n    indices = json.loads(re.search(r'\\[.*?\\]', text).group())\n    return [files[i][\"filename\"] for i in indices if 0 <= i < len(files)]\n```\n\n如果 side-query 失败（API 错误、JSON 解析失败），降级到关键词匹配 name + description。\n\n### 写入：每轮结束后提取\n\n用户不会每次都说\"记住这个\"。偏好通常散落在正常对话中：\"用 tab 比空格好\"、\"以后都用单引号\"。\n\n`extract_memories()` 在每轮结束时运行，条件是模型停止且没有 tool_use（说明对话告一段落）：\n\n```python\n# In agent_loop:\nif response.stop_reason != \"tool_use\":\n    extract_memories(pre_compress)   # 从压缩前快照提取新记忆\n    consolidate_memories()       # 检查是否需要整理\n    return\n```\n\n提取前先检查已有记忆，避免重复。提取 prompt 要求 LLM 返回 `{name, type, description, body}` 的 JSON 数组，只有确实有新信息时才写文件。\n\n```python\ndef extract_memories(messages):\n    dialogue = format_recent_messages(messages[-10:])\n    existing = \"\\n\".join(f\"- {m['name']}: {m['description']}\" for m in list_memory_files())\n\n    prompt = (\n        \"Extract user preferences, constraints, or project facts.\\n\"\n        \"Return JSON array: [{name, type, description, body}].\\n\"\n        \"If nothing new or already covered, return [].\\n\\n\"\n        f\"Existing memories:\\n{existing}\\n\\nDialogue:\\n{dialogue[:4000]}\"\n    )\n    # ... parse response, write files ...\n```\n\n### 整理：低频合并去重\n\n记忆文件会积累。`consolidate_memories()` 在文件数达到阈值（默认 10）时触发，让 LLM 去重、合并矛盾、淘汰过时记忆：\n\n```python\nCONSOLIDATE_THRESHOLD = 10\n\ndef consolidate_memories():\n    files = list_memory_files()\n    if len(files) < CONSOLIDATE_THRESHOLD:\n        return  # 太少，不值得整理\n    # Send all memories to LLM, get back deduplicated list\n    # Replace all files with consolidated results\n```\n\n### Memory 适合保存什么\n\nMemory 保存跨会话仍然有用的信息：用户偏好、反复出现的反馈、项目背景、常用入口和排查线索。它关注“以后还会用到什么”，并通过索引 + 按需加载把这些信息带回当前对话。\n\nsession memory 关注同一会话内的连续性：compact 之后，当前会话还需要保留哪些上下文。两者配合使用：Memory 管长期知识，session memory 管当前会话的压缩续接。\n\n---\n\n## 相对 s08 的变更\n\n| 组件 | 之前 (s08) | 之后 (s09) |\n|------|-----------|-----------|\n| 记忆能力 | 无（压缩后偏好随摘要退化） | 存储 + 加载 + 提取 + 整理 |\n| 新函数 | — | write_memory_file, select_relevant_memories, load_memories, extract_memories, consolidate_memories |\n| 存储 | — | .memory/MEMORY.md 索引 + .memory/*.md 文件 |\n| 工具 | bash, read, write, edit, glob, todo_write, task, load_skill, compact (9) | bash, read_file, write_file, edit_file, glob, task (6) |\n| 循环 | 每轮只做压缩 | 每轮注入记忆 + 压缩 + 每轮结束后提取 + 定期整理 |\n\n---\n\n## 试一下\n\n```sh\ncd learn-claude-code\npython s09_memory/code.py\n```\n\n试试这些 prompt（分多轮输入，观察记忆的累积和加载）：\n\n1. `I prefer using tabs for indentation, not spaces. Remember that.`\n2. `Create a Python file called test.py`（观察 Agent 是否用了 tab）\n3. `What did I tell you about my preferences?`（观察 Agent 是否记得）\n4. `I also prefer single quotes over double quotes for strings.`\n\n观察重点：每轮结束后是否出现 `[Memory: extracted N new memories]`？`.memory/` 目录下是否生成了 `.md` 文件？`MEMORY.md` 索引是否更新？新一轮对话时 Agent 是否自动加载了之前的记忆？\n\n---\n\n## 接下来\n\n记忆、压缩、工具都已就绪。但 system prompt 还是硬编码的一大段字符串。加了新工具要手动加描述，换了项目要重写整个 prompt。prompt 应该运行时组装。\n\ns10 System Prompt → 分段 + 运行时组装。不同项目、不同工具，拼出不同的 prompt。\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s09",
    "locale": "ja",
    "title": "s09: Memory — 圧縮は詳細を失う、失わない層が必要",
    "content": "# s09: Memory — 圧縮は詳細を失う、失わない層が必要\n\ns01 → ... → s07 → s08 → `s09` → [s10](/ja/s10) → s11 → ... → s20 → s21\n> *\"圧縮は詳細を失う、失わない層が必要\"* — ファイルストア + インデックス + オンデマンド読み込み。圧縮を越え、セッションを越えて。\n>\n> **Harness レイヤー**: 記憶 — 圧縮とセッションを越える知識の蓄積。\n\n---\n\n## 課題\n\ns08 の autoCompact は現在の目標、残りの作業、ユーザーの制約をサマリに保持するが、詳細は失われる：「タブでインデント、スペース不可」が「ユーザーにコードスタイルの好みあり」と簡略化される。そして新しいセッションを開始すると、サマリすらない。\n\nLLM には永続状態がなく、すべての情報はコンテキストウィンドウ内にある。コンテキストが満杯になれば圧縮され、圧縮は非可逆。圧縮に参加せず、セッションを越えて保持されるストレージ層が必要。\n\n---\n\n## ソリューション\n\n![Memory Overview](/course-assets/s09_memory/memory-overview.ja.svg)\n\ns08 の圧縮パイプラインを維持し、記憶に焦点を当てる。ストレージにはファイルシステムを採用：`.memory/` ディレクトリに各記憶を `.md` ファイルとして保存、YAML frontmatter（`name` / `description` / `type`）付き。ファイルが増えたらインデックスが必要：`MEMORY.md` に 1 行 1 リンクを記録し、SYSTEM に注入。\n\n重要な設計：インデックスは SYSTEM prompt に常駐（prompt cache でキャッシュ可能）、ファイル内容はオンデマンド注入（filename/description で現在の会話にマッチ、cache を破壊しない）。書き込みは 2 つのパス：ユーザーが明示的に「覚えて」と言うか、毎ターン終了後にバックグラウンドで抽出。ファイルが蓄積されたら、定期的に整理して重複排除。\n\n> **s08 との境界：** 圧縮は引き続き現在の会話と token 予算を担当する。記憶は圧縮を置き換えず、選んだ事実を会話の外に保存し、後から必要に応じて呼び戻す。\n\n4 種類の記憶、それぞれ異なる質問に答える：\n\n| タイプ | 何に答えるか | 例 |\n|--------|-------------|-----|\n| user | あなたは誰か | \"タブでスペース不可\" |\n| feedback | どう作業するか | \"DB をモックしない\" |\n| project | 何が起きているか | \"auth 書き直しはコンプライアンス主導\" |\n| reference | どこで探すか | \"パイプラインのバグは Linear INGEST\" |\n\n---\n\n## 仕組み\n\n![Memory Subsystems](/course-assets/s09_memory/memory-subsystems.ja.svg)\n\n### ストレージ：Markdown ファイル + インデックス\n\n各記憶は `.md` ファイル、YAML frontmatter でメタデータを記録：\n\n```markdown\n---\nname: user-preference-tabs\ndescription: User prefers tabs for indentation\ntype: user\n---\n\nUser prefers using tabs, not spaces, for indentation.\n**Why:** Consistency with existing codebase conventions.\n**How to apply:** Always use tabs when writing or editing files.\n```\n\n`MEMORY.md` はインデックス、1 行に 1 リンク：\n\n```markdown\n- [user-preference-tabs](user-preference-tabs.md) — User prefers tabs for indentation\n```\n\n新しい記憶を書き込むとインデックスを自動再構築：\n\n```python\ndef write_memory_file(name, mem_type, description, body):\n    slug = name.lower().replace(\" \", \"-\")\n    filepath = MEMORY_DIR / f\"{slug}.md\"\n    filepath.write_text(\n        f\"---\\nname: {name}\\ndescription: {description}\\ntype: {mem_type}\\n---\\n\\n{body}\\n\"\n    )\n    _rebuild_index()\n```\n\n### 読み込み：2 つのパス\n\n**パス 1：インデックスを SYSTEM に常駐。** `build_system()` は各ユーザーリクエストの開始時に 1 回だけ `MEMORY.md` を読み込み、記憶カタログを SYSTEM prompt に注入。記憶の抽出と整理はターン終了時にだけ実行されるため、同じユーザーリクエスト内で SYSTEM を繰り返し再構築する必要はない。\n\n**パス 2：関連記憶をオンデマンド注入。** 各ユーザーリクエストの開始時に、`load_memories()` は最近の会話と記憶カタログ（name + description）を LLM に軽量 side-query として送信し、関連するファイル名を選択、ファイル内容を読み込んで注入。上限 5 件でコストを制御。\n\n```python\ndef select_relevant_memories(messages, max_items=5):\n    files = list_memory_files()\n    if not files:\n        return []\n\n    # Build catalog: \"0: user-preference-tabs — User prefers tabs...\"\n    catalog = \"\\n\".join(f\"{i}: {f['name']} — {f['description']}\" for i, f in enumerate(files))\n\n    response = client.messages.create(model=MODEL, messages=[{\"role\": \"user\",\n        \"content\": f\"Select relevant memory indices. Return JSON array.\\n\\n\"\n                   f\"Recent conversation:\\n{recent}\\n\\nMemory catalog:\\n{catalog}\"}],\n        max_tokens=200)\n    indices = json.loads(re.search(r'\\[.*?\\]', response.content[0].text).group())\n    return [files[i][\"filename\"] for i in indices if 0 <= i < len(files)]\n```\n\nside-query が失敗した場合（API エラー、JSON パース失敗）、name + description のキーワードマッチにフォールバック。\n\n### 書き込み：毎ターン終了後の抽出\n\nユーザーが毎回「これを覚えて」と言うわけではない。好みは通常、通常の会話の中に散らばっている：「タブの方がスペースより良い」「これからはシングルクォートにしよう」。\n\n`extract_memories()` は各ターン終了時に実行、モデルが tool_use なしで停止した場合にトリガー（会話が自然な区切りに達したことを示す）：\n\n```python\n# In agent_loop:\nif response.stop_reason != \"tool_use\":\n    extract_memories(messages)   # 最近の会話から新しい記憶を抽出\n    consolidate_memories()       # 整理が必要かチェック\n    return\n```\n\n抽出前に既存の記憶を確認し、重複を回避。抽出プロンプトは LLM に `{name, type, description, body}` の JSON 配列を要求、本当に新しい情報がある場合のみファイルに書き込む。\n\n```python\ndef extract_memories(messages):\n    dialogue = format_recent_messages(messages[-10:])\n    existing = \"\\n\".join(f\"- {m['name']}: {m['description']}\" for m in list_memory_files())\n\n    prompt = (\n        \"Extract user preferences, constraints, or project facts.\\n\"\n        \"Return JSON array: [{name, type, description, body}].\\n\"\n        \"If nothing new or already covered, return [].\\n\\n\"\n        f\"Existing memories:\\n{existing}\\n\\nDialogue:\\n{dialogue[:4000]}\"\n    )\n    # ... parse response, write files ...\n```\n\n### 整理：低頻度の重複排除\n\n記憶ファイルは蓄積される。`consolidate_memories()` はファイル数が閾値（デフォルト 10）に達した時にトリガー、LLM に重複排除、矛盾の統合、古い記憶の剪定を依頼：\n\n```python\nCONSOLIDATE_THRESHOLD = 10\n\ndef consolidate_memories():\n    files = list_memory_files()\n    if len(files) < CONSOLIDATE_THRESHOLD:\n        return  # 少なすぎる、整理する価値なし\n    # Send all memories to LLM, get back deduplicated list\n    # Replace all files with consolidated results\n```\n\n### Memory に保存するもの\n\nMemory はセッションを越えて有用な情報を保存する：ユーザーの好み、繰り返し出るフィードバック、プロジェクト背景、よく使う入口、調査の手がかりなど。「あとでまた使うもの」を対象にし、インデックス + オンデマンド読み込みで現在の会話に戻す。\n\nsession memory は 1 つのセッション内の連続性を扱う：compact 後も現在の会話に残すべき文脈を保持する。両者は役割が分かれている。Memory は長期知識を扱い、session memory は現在のセッションを compact 越しにつなぐ。\n\n---\n\n## s08 からの変更点\n\n| コンポーネント | 変更前 (s08) | 変更後 (s09) |\n|-----------|-------------|-------------|\n| 記憶能力 | なし（圧縮後、好みはサマリと共に劣化） | ストレージ + 読み込み + 抽出 + 整理 |\n| 新規関数 | — | write_memory_file, select_relevant_memories, load_memories, extract_memories, consolidate_memories |\n| ストレージ | — | .memory/MEMORY.md インデックス + .memory/*.md ファイル |\n| ツール | bash, read, write, edit, glob, todo_write, task, load_skill, compact (9) | bash, read_file, write_file, edit_file, glob, task (6) |\n| ループ | 毎ターン圧縮のみ | 記憶注入 + 圧縮 + ターン終了後の抽出 + 定期整理 |\n\n---\n\n## 試してみよう\n\n```sh\ncd learn-claude-code\npython s09_memory/code.py\n```\n\n以下のプロンプトを試してみてください（複数ターンに分けて入力し、記憶の蓄積と読み込みを観察）：\n\n1. `I prefer using tabs for indentation, not spaces. Remember that.`\n2. `Create a Python file called test.py`（Agent がタブを使用したか観察）\n3. `What did I tell you about my preferences?`（Agent が覚えているか観察）\n4. `I also prefer single quotes over double quotes for strings.`\n\n観察のポイント：各ターン終了後に `[Memory: extracted N new memories]` が表示されるか？`.memory/` ディレクトリに `.md` ファイルが生成されたか？`MEMORY.md` インデックスが更新されたか？新しい会話で Agent が以前の記憶を自動的に読み込んだか？\n\n---\n\n## 次へ\n\n記憶、圧縮、ツールはすべて揃った。しかし system prompt はまだハードコードされた文字列。新しいツールを追加するには手動で説明を書き、プロジェクトを変えるにはプロンプト全体を書き直す。プロンプトは実行時に組み立てられるべき。\n\ns10 System Prompt → セグメント + 実行時組み立て。異なるプロジェクト、異なるツール、異なるプロンプト。\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s10",
    "locale": "en",
    "title": "s10: Context Assembly — Build Model Input at Runtime",
    "content": "# s10: Context Assembly — Build Model Input at Runtime\n\ns01 → ... → s08 → s09 → `s10` → [s11](/en/s11) → s12 → ... → s20 → s21\n> *\"Model input is assembled, not hardcoded\"* — Stable sections + runtime state + caching.\n>\n> **Harness Layer**: Context assembly — turn stable instructions and dynamic state into model input.\n\n---\n\n## The Problem\n\nFrom s01 to s09, the system prompt was always one hardcoded line:\n\n```python\nSYSTEM = f\"You are a coding agent at {WORKDIR}. Use tools to solve tasks.\"\n```\n\nThat worked for s01 — only bash, read, write. But by s09, the agent has memory, compression, skill loading. The prompt needs to describe more and more capabilities:\n\n```python\nSYSTEM = (\n    f\"You are a coding agent at {WORKDIR}. \"\n    \"Use tools to solve tasks. Act, don't explain. \"\n    \"Before starting any multi-step task, use todo_write. \"\n    \"Skills are available via list_skills and load_skill. \"\n    \"Relevant memories are injected below when available. \"\n    # ... add a capability, add a line\n)\n```\n\nThree problems:\n\n1. **Switching projects requires rewriting the entire prompt** — no way to know what to change and what to keep\n2. **One change can break others** — adding a tool description might conflict with earlier instructions\n3. **Every request carries everything** — even when the current conversation doesn't need certain sections, they waste tokens\n\nThe system prompt should be a configuration assembled at runtime based on current state: which tools are enabled, which context is visible, which memories are relevant, and which content must remain stable to hit prompt cache.\n\n---\n\n## The Solution\n\n![System Prompt Overview](/course-assets/s10_system_prompt/system-prompt-overview.en.svg)\n\ns10 is a short bridge between context management and recovery. It does not add another storage system or merge s08 with s09. It shows where their outputs meet the model boundary: split the hardcoded `SYSTEM` into independent sections, assemble them from real runtime state, and cache the result.\n\nFour sections, two loading strategies:\n\n| Section | Strategy | Content | Condition |\n|---------|----------|---------|-----------|\n| identity | always | who you are, how to work | always present |\n| tools | always | available tool list | `enabled_tools` |\n| workspace | always | working directory | always present |\n| memory | on-demand | relevant memory content | whether `.memory/MEMORY.md` exists |\n\nKey design: whether a section loads depends on real state (tools exist, files exist), not keywords in messages.\n\n---\n\n## How It Works\n\n### PROMPT_SECTIONS: Topic-Keyed Fragments\n\nSplit the monolithic string into a dictionary, each key is a topic:\n\n```python\nPROMPT_SECTIONS = {\n    \"identity\": \"You are a coding agent. Act, don't explain.\",\n}\n```\n\nEach section is maintained independently. Changing `tools` doesn't affect `identity`; adding `memory` doesn't touch `workspace`.\n\n### assemble_system_prompt: On-Demand Assembly\n\nNot every section is needed every turn. No memory files? Loading the memory section just wastes tokens. Assembly is based on real state in context:\n\n```python\ndef assemble_system_prompt(context: dict) -> str:\n    sections = []\n\n    # Always loaded\n    sections.append(PROMPT_SECTIONS[\"identity\"])\n\n    # Dynamic — tools and workspace from context\n    tools = \", \".join(context.get(\"enabled_tools\", []))\n    if tools:\n        sections.append(f\"Available tools: {tools}.\")\n    sections.append(f\"Working directory: {context.get('workspace', WORKDIR)}\")\n\n    # On-demand — based on real state, not keywords\n    memories = context.get(\"memories\", \"\")\n    if memories:\n        sections.append(f\"Relevant memories:\\n{memories}\")\n\n    return \"\\n\\n\".join(sections)\n```\n\n\"Always loaded\" sections are needed every turn: identity, tools, workspace. \"On-demand\" sections are only useful under specific conditions.\n\nWhy not load everything? Tokens have cost (system prompt is billed every turn), and fewer instructions means more focused output (irrelevant instructions are noise).\n\n### get_system_prompt: Cache to Avoid Re-Assembly\n\nWhen context hasn't changed (multiple LLM calls in the same turn with the same context), re-assembling is wasteful. Use deterministic serialization to detect changes and return cached result:\n\n```python\ndef get_system_prompt(context: dict) -> str:\n    global _last_context_key, _last_prompt\n    key = json.dumps(context, sort_keys=True, ensure_ascii=False, default=str)\n    if key == _last_context_key and _last_prompt:\n        return _last_prompt\n    _last_context_key = key\n    _last_prompt = assemble_system_prompt(context)\n    return _last_prompt\n```\n\n`json.dumps` instead of `hash()`: Python's built-in `hash()` has process randomization (unsuitable for stable cache keys) and throws `unhashable type` on nested dicts/lists.\n\n### context: Real State, Not Keyword Guessing\n\nContext reflects the actual runtime state:\n\n```python\ndef update_context(context: dict, messages: list) -> dict:\n    memories = \"\"\n    if MEMORY_INDEX.exists():\n        content = MEMORY_INDEX.read_text().strip()\n        if content:\n            memories = content\n    return {\n        \"enabled_tools\": list(TOOL_HANDLERS.keys()),\n        \"workspace\": str(WORKDIR),\n        \"memories\": memories,\n    }\n```\n\n`enabled_tools` lists actually registered tools. `memories` checks whether `.memory/MEMORY.md` exists. Section loading is based on this real state, not searching for keywords in messages.\n\n### Putting It Together\n\n```python\ndef agent_loop(messages: list, context: dict):\n    system = get_system_prompt(context)\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=system, messages=messages,\n            tools=TOOLS, max_tokens=8000)\n        # ... tool execution ...\n        context = update_context(context, messages)\n        system = get_system_prompt(context)\n```\n\nAt the start of each loop iteration, get the system prompt. If context changed, re-assemble; if not, return cached version.\n\n---\n\n## Changes From s09\n\n| Component | Before (s09) | After (s10) |\n|-----------|-------------|-------------|\n| prompt | Hardcoded SYSTEM string | PROMPT_SECTIONS + assemble_system_prompt |\n| caching | None | get_system_prompt (json.dumps detection + cache) |\n| new functions | — | assemble_system_prompt, get_system_prompt, update_context |\n| tools | bash, read_file, write_file (3) | bash, read_file, write_file (3) — unchanged |\n| loop | Uses fixed SYSTEM | Uses get_system_prompt(context) |\n\n---\n\n## Try It\n\n```sh\ncd learn-claude-code\npython s10_system_prompt/code.py\n```\n\n**Safety note**: The script executes model-generated `bash` strings with `shell=True` and does not include the permission gate from s03. Run it only in a disposable workspace.\n\nWhat to watch for:\n\n1. Output shows which sections were loaded (`[assembled] sections: ...` label)\n2. Cache hits show `[cache hit]` during continued conversation\n3. Creating `.memory/MEMORY.md` makes the memory section appear on the next turn\n\nTry these prompts:\n\n1. `Read the file README.md` (observe the three always-loaded sections)\n2. `Create a file called .memory/MEMORY.md with content \"- [test](test.md) — test memory\"` (write a memory index)\n3. `Read the file code.py` (observe whether the memory section appears)\n\n---\n\n## What's Next\n\nThe model input can now be assembled at runtime. But the agent still crashes on errors. Network hiccups, API rate limits, truncated output, context overflow — these aren't bugs, they're normal.\n\ns11 Error Recovery → four recovery paths. Upgrade tokens, compress context, exponential backoff, switch models.\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s10",
    "locale": "zh",
    "title": "s10: Context Assembly — 在运行时组装模型输入",
    "content": "# s10: Context Assembly — 在运行时组装模型输入\n\ns01 → ... → s08 → s09 → `s10` → [s11](/zh/s11) → s12 → ... → s20 → s21\n> *\"模型输入是组装出来的，不是写死的\"* — 稳定分段 + 运行时状态 + 缓存。\n>\n> **Harness 层**: 上下文组装 — 把稳定指令和动态状态组成模型输入。\n\n---\n\n## 问题\n\n从 s01 到 s09，system prompt 都是一行硬编码：\n\n```python\nSYSTEM = f\"You are a coding agent at {WORKDIR}. Use tools to solve tasks.\"\n```\n\ns01 够用，只有 bash、read、write 三个工具。但到 s09，Agent 已经有记忆、有压缩、有技能加载。prompt 该提的能力越来越多：\n\n```python\nSYSTEM = (\n    f\"You are a coding agent at {WORKDIR}. \"\n    \"Use tools to solve tasks. Act, don't explain. \"\n    \"Before starting any multi-step task, use todo_write. \"\n    \"Skills are available via list_skills and load_skill. \"\n    \"Relevant memories are injected below when available. \"\n    # ... 加一个能力就多一段\n)\n```\n\n三个问题：\n\n1. **换项目要重写整个 prompt**，不知道哪些该改、哪些该留\n2. **修改一处可能影响全局**，加一段工具描述可能跟前面的指令冲突\n3. **每次请求都带全部内容**，即使当前对话用不到某些段落也浪费 token\n\nSystem prompt 应该是运行时根据当前状态组装的配置：哪些工具启用、哪些上下文可见、哪些记忆相关、哪些内容必须保持稳定以命中 prompt cache。\n\n---\n\n## 解决方案\n\n![System Prompt Overview](/course-assets/s10_system_prompt/system-prompt-overview.svg)\n\ns10 是上下文管理与错误恢复之间的一节短桥接课。它不增加新的存储系统，也不把 s08 与 s09 合并；它只展示两者的输出如何在模型边界汇合：把硬编码的 `SYSTEM` 拆成独立段落（section），运行时根据真实状态按需拼接，并缓存结果。\n\n四个 section，两种加载策略：\n\n| Section | 加载策略 | 内容 | 判断依据 |\n|---------|---------|------|---------|\n| identity | 始终 | 你是谁、怎么做事 | 始终存在 |\n| tools | 始终 | 可用工具列表 | `enabled_tools` |\n| workspace | 始终 | 工作目录 | 始终存在 |\n| memory | 按需 | 相关记忆内容 | `.memory/MEMORY.md` 是否存在 |\n\n关键设计：section 是否加载取决于真实状态（工具是否存在、文件是否存在），不是消息里的关键词。\n\n---\n\n## 工作原理\n\n### PROMPT_SECTIONS: 分段定义\n\n把一大段字符串拆成字典，每个 key 是一个主题：\n\n```python\nPROMPT_SECTIONS = {\n    \"identity\": \"You are a coding agent. Act, don't explain.\",\n}\n```\n\n每个 section 独立维护。修改 `tools` 不影响 `identity`，新增 `memory` 不动 `workspace`。\n\n### assemble_system_prompt: 按需拼接\n\n不是所有 section 每次都需要。当前没有记忆文件，加载 memory section 只是浪费 token。根据 context 的真实状态决定加载哪些：\n\n```python\ndef assemble_system_prompt(context: dict) -> str:\n    sections = []\n\n    # 始终加载\n    sections.append(PROMPT_SECTIONS[\"identity\"])\n\n    # 从 context 动态获取 tools 和 workspace\n    tools = \", \".join(context.get(\"enabled_tools\", []))\n    if tools:\n        sections.append(f\"Available tools: {tools}.\")\n    sections.append(f\"Working directory: {context.get('workspace', WORKDIR)}\")\n\n    # 按需加载 — 基于真实状态，不是关键词\n    memories = context.get(\"memories\", \"\")\n    if memories:\n        sections.append(f\"Relevant memories:\\n{memories}\")\n\n    return \"\\n\\n\".join(sections)\n```\n\n\"始终加载\"的是每轮都需要的：身份、工具、工作目录。\"按需加载\"的只在特定条件下才有用。\n\n为什么不全加载？token 有成本（system prompt 每轮计费），信息越少 LLM 越专注（无关指令是噪音）。\n\n### get_system_prompt: 缓存避免重复拼接\n\n上下文没变时（同一轮对话的多次 LLM 调用，context 相同），重新拼接是浪费。用确定性序列化检测变化，命中缓存直接返回：\n\n```python\ndef get_system_prompt(context: dict) -> str:\n    global _last_context_key, _last_prompt\n    key = json.dumps(context, sort_keys=True, ensure_ascii=False, default=str)\n    if key == _last_context_key and _last_prompt:\n        return _last_prompt\n    _last_context_key = key\n    _last_prompt = assemble_system_prompt(context)\n    return _last_prompt\n```\n\n用 `json.dumps` 而不是 `hash()`：Python 内置 `hash()` 有进程随机化，不适合做稳定 cache key，而且遇到 list/dict 会报 `unhashable type`。\n\n### context: 真实状态，不是关键词猜测\n\ncontext 反映当前运行态的真实状态：\n\n```python\ndef update_context(context: dict, messages: list) -> dict:\n    memories = \"\"\n    if MEMORY_INDEX.exists():\n        content = MEMORY_INDEX.read_text().strip()\n        if content:\n            memories = content\n    return {\n        \"enabled_tools\": list(TOOL_HANDLERS.keys()),\n        \"workspace\": str(WORKDIR),\n        \"memories\": memories,\n    }\n```\n\n`enabled_tools` 列出实际注册的工具。`memories` 检查 `.memory/MEMORY.md` 是否存在。section 加载基于这些真实状态，不在消息里搜关键词。\n\n### 合起来跑\n\n```python\ndef agent_loop(messages: list, context: dict):\n    system = get_system_prompt(context)\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=system, messages=messages,\n            tools=TOOLS, max_tokens=8000)\n        # ... 工具执行 ...\n        context = update_context(context, messages)\n        system = get_system_prompt(context)\n```\n\n每轮循环开头拿一次 system prompt。context 变了就重新组装，没变就返回缓存。\n\n---\n\n## 相对 s09 的变更\n\n| 组件 | 之前 (s09) | 之后 (s10) |\n|------|-----------|-----------|\n| prompt | 硬编码 SYSTEM 字符串 | PROMPT_SECTIONS + assemble_system_prompt |\n| 缓存 | 无 | get_system_prompt（json.dumps 检测 + 缓存） |\n| 新函数 | — | assemble_system_prompt, get_system_prompt, update_context |\n| 工具 | bash, read_file, write_file (3) | bash, read_file, write_file (3) — 不变 |\n| 循环 | 用固定 SYSTEM | 用 get_system_prompt(context) |\n\n---\n\n## 试一下\n\n```sh\ncd learn-claude-code\npython s10_system_prompt/code.py\n```\n\n**安全说明**：脚本使用 `shell=True` 执行模型生成的 `bash` 字符串，并未接入 s03 的权限闸门。请只在可丢弃的工作区中运行。\n\n观察重点：\n\n1. 输出中能看到哪些 section 被加载了（`[assembled] sections: ...` 标签）\n2. 连续对话时，缓存命中显示 `[cache hit]`\n3. 创建 `.memory/MEMORY.md` 文件后，下一轮 memory section 自动加载\n\n试试这些 prompt：\n\n1. `Read the file README.md`（观察始终加载的三个 section）\n2. `Create a file called .memory/MEMORY.md with content \"- [test](test.md) — test memory\"`（写入记忆索引）\n3. `Read the file code.py`（观察 memory section 是否出现）\n\n---\n\n## 接下来\n\n模型输入可以在运行时组装了，但 Agent 碰到错误还是会崩。网络抖动、API 限流、输出被截断、上下文超限，这些不是 bug，是常态。\n\ns11 Error Recovery → 四条恢复路径。升级 token、压缩上下文、指数退避、切换模型。\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s10",
    "locale": "ja",
    "title": "s10: Context Assembly — 実行時にモデル入力を組み立てる",
    "content": "# s10: Context Assembly — 実行時にモデル入力を組み立てる\n\ns01 → ... → s08 → s09 → `s10` → [s11](/ja/s11) → s12 → ... → s20 → s21\n> *\"モデル入力は組み立てるもの、固定するものではない\"* — 安定セクション + 実行時状態 + キャッシュ。\n>\n> **Harness レイヤー**: コンテキスト組み立て — 安定した指示と動的状態をモデル入力にまとめる。\n\n---\n\n## 課題\n\ns01 から s09 まで、system prompt は常に 1 行のハードコード：\n\n```python\nSYSTEM = f\"You are a coding agent at {WORKDIR}. Use tools to solve tasks.\"\n```\n\ns01 では十分だった。bash、read、write の 3 ツールのみ。しかし s09 では、Agent に記憶、圧縮、スキル読み込みがある。prompt が説明すべき能力が増え続ける：\n\n```python\nSYSTEM = (\n    f\"You are a coding agent at {WORKDIR}. \"\n    \"Use tools to solve tasks. Act, don't explain. \"\n    \"Before starting any multi-step task, use todo_write. \"\n    \"Skills are available via list_skills and load_skill. \"\n    \"Relevant memories are injected below when available. \"\n    # ... 能力を追加するたびに 1 行増える\n)\n```\n\n3 つの問題：\n\n1. **プロジェクトを変えるには prompt 全体を書き直す**必要がある。何を変え、何を残すべきか不明\n2. **一箇所の変更が全体に影響する**。ツール説明を追加すると、前の指示と矛盾する可能性\n3. **毎回のリクエストが全内容を送信する**。現在の会話で不要なセクションも token を無駄に消費\n\nSystem prompt は、実行時の現在状態に基づいて組み立てられる設定であるべき：どのツールが有効か、どのコンテキストが可視か、どの記憶が関連するか、どの内容を prompt cache に命中させるために安定させるべきか。\n\n---\n\n## ソリューション\n\n![System Prompt Overview](/course-assets/s10_system_prompt/system-prompt-overview.ja.svg)\n\ns10 はコンテキスト管理とエラー回復をつなぐ短い橋渡しセッションである。新しいストレージを追加せず、s08 と s09 も統合しない。両者の出力がモデル境界でどう合流するかを示す：ハードコードされた `SYSTEM` を独立セクションに分割し、実際の実行時状態から組み立て、結果をキャッシュする。\n\n4 つのセクション、2 つの読み込み戦略：\n\n| セクション | 戦略 | 内容 | 判断基準 |\n|-----------|------|------|---------|\n| identity | 常に | あなたは誰か、どう作業するか | 常に存在 |\n| tools | 常に | 利用可能ツール一覧 | `enabled_tools` |\n| workspace | 常に | 作業ディレクトリ | 常に存在 |\n| memory | オンデマンド | 関連記憶内容 | `.memory/MEMORY.md` が存在するか |\n\n重要な設計：セクションをロードするかどうかは実際の状態（ツールが存在するか、ファイルが存在するか）で決まり、メッセージ内のキーワードではない。\n\n---\n\n## 仕組み\n\n### PROMPT_SECTIONS: トピック別フラグメント\n\n単一の文字列を辞書に分割、各キーがトピック：\n\n```python\nPROMPT_SECTIONS = {\n    \"identity\": \"You are a coding agent. Act, don't explain.\",\n}\n```\n\n各セクションは独立して管理。`tools` を変更しても `identity` に影響しない。`memory` を追加しても `workspace` はそのまま。\n\n### assemble_system_prompt: オンデマンド組み立て\n\nすべてのセクションが毎ターン必要なわけではない。記憶ファイルがなければ、memory セクションをロードしても token の無駄。context の実際の状態に基づいて組み立てる：\n\n```python\ndef assemble_system_prompt(context: dict) -> str:\n    sections = []\n\n    # 常にロード\n    sections.append(PROMPT_SECTIONS[\"identity\"])\n\n    # context から動的に tools と workspace を取得\n    tools = \", \".join(context.get(\"enabled_tools\", []))\n    if tools:\n        sections.append(f\"Available tools: {tools}.\")\n    sections.append(f\"Working directory: {context.get('workspace', WORKDIR)}\")\n\n    # オンデマンド — 実際の状態に基づく、キーワードではない\n    memories = context.get(\"memories\", \"\")\n    if memories:\n        sections.append(f\"Relevant memories:\\n{memories}\")\n\n    return \"\\n\\n\".join(sections)\n```\n\n「常にロード」は毎ターン必要なもの：アイデンティティ、ツール、作業ディレクトリ。「オンデマンド」は特定条件下でのみ有用。\n\nなぜ全部ロードしないのか？token にはコストがあり（system prompt は毎ターン課金）、情報が少ないほど LLM は集中する（無関係な指示はノイズ）。\n\n### get_system_prompt: キャッシュで再組み立てを回避\n\nコンテキストが変わっていない時（同じターン内で複数の LLM 呼び出し、context が同じ）、再組み立ては無駄。確定的シリアライズで変化を検出し、キャッシュヒット時は即座に返却：\n\n```python\ndef get_system_prompt(context: dict) -> str:\n    global _last_context_key, _last_prompt\n    key = json.dumps(context, sort_keys=True, ensure_ascii=False, default=str)\n    if key == _last_context_key and _last_prompt:\n        return _last_prompt\n    _last_context_key = key\n    _last_prompt = assemble_system_prompt(context)\n    return _last_prompt\n```\n\n`hash()` ではなく `json.dumps` を使用：Python 組み込みの `hash()` にはプロセスランダム化があり（安定したキャッシュキーに不適切）、list/dict で `unhashable type` エラーになる。\n\n### context: 実際の状態、キーワード推測ではない\n\ncontext は現在の実行時状態の実際の状態を反映：\n\n```python\ndef update_context(context: dict, messages: list) -> dict:\n    memories = \"\"\n    if MEMORY_INDEX.exists():\n        content = MEMORY_INDEX.read_text().strip()\n        if content:\n            memories = content\n    return {\n        \"enabled_tools\": list(TOOL_HANDLERS.keys()),\n        \"workspace\": str(WORKDIR),\n        \"memories\": memories,\n    }\n```\n\n`enabled_tools` は実際に登録されたツールを一覧。`memories` は `.memory/MEMORY.md` が存在するかを確認。セクションの読み込みはこの実際の状態に基づき、メッセージ内のキーワード検索ではない。\n\n### 組み合わせて実行\n\n```python\ndef agent_loop(messages: list, context: dict):\n    system = get_system_prompt(context)\n    while True:\n        response = client.messages.create(\n            model=MODEL, system=system, messages=messages,\n            tools=TOOLS, max_tokens=8000)\n        # ... ツール実行 ...\n        context = update_context(context, messages)\n        system = get_system_prompt(context)\n```\n\n各ループ反復の開始時に system prompt を取得。context が変わっていれば再組み立て、変わっていなければキャッシュを返却。\n\n---\n\n## s09 からの変更点\n\n| コンポーネント | 変更前 (s09) | 変更後 (s10) |\n|-----------|-------------|-------------|\n| prompt | ハードコード SYSTEM 文字列 | PROMPT_SECTIONS + assemble_system_prompt |\n| キャッシュ | なし | get_system_prompt（json.dumps 検出 + キャッシュ） |\n| 新規関数 | — | assemble_system_prompt, get_system_prompt, update_context |\n| ツール | bash, read_file, write_file (3) | bash, read_file, write_file (3) — 変更なし |\n| ループ | 固定 SYSTEM を使用 | get_system_prompt(context) を使用 |\n\n---\n\n## 試してみよう\n\n```sh\ncd learn-claude-code\npython s10_system_prompt/code.py\n```\n\n**安全上の注意**：このスクリプトはモデルが生成した `bash` 文字列を `shell=True` で実行し、s03 の permission gate を含まない。破棄可能な workspace でのみ実行すること。\n\n観察のポイント：\n\n1. 出力にロードされたセクションが表示される（`[assembled] sections: ...` ラベル）\n2. 継続会話でキャッシュヒット時は `[cache hit]` と表示\n3. `.memory/MEMORY.md` を作成すると、次のターンで memory セクションが自動ロード\n\n以下のプロンプトを試してみてください：\n\n1. `Read the file README.md`（常にロードされる 3 つのセクションを観察）\n2. `Create a file called .memory/MEMORY.md with content \"- [test](test.md) — test memory\"`（記憶インデックスを書き込み）\n3. `Read the file code.py`（memory セクションが表示されるか観察）\n\n---\n\n## 次へ\n\nモデル入力を実行時に組み立てられるようになった。しかし Agent はエラーでまだクラッシュする。ネットワークの不安定性、API レート制限、出力の切り詰め、コンテキスト超過、これらはバグではなく日常。\n\ns11 Error Recovery → 4 つのリカバリパス。token のアップグレード、コンテキスト圧縮、指数バックオフ、モデル切り替え。\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s11",
    "locale": "en",
    "title": "s11: Error Recovery — Errors aren't the end, they're the start of a retry",
    "content": "# s11: Error Recovery — Errors aren't the end, they're the start of a retry\n\ns01 → ... → s09 → s10 → `s11` → [s12](/en/s12) → s13 → ... → s20 → s21\n> *\"Errors aren't the end, they're the start of a retry\"* — escalate tokens, compact context, switch models.\n>\n> **Harness layer**: Resilience — classify and recover when the main loop hits errors.\n\n---\n\n## The Problem\n\nThe Agent is running along and then errors out:\n\n```\nError: 529 overloaded\n```\n\nThe Agent crashes. It doesn't retry, doesn't switch models, doesn't reduce context — it just crashes.\n\nLLM API calls can fail. This chapter handles three cases: truncated output, context overflow, and transient failures (429/529).\n\n---\n\n## Solution\n\n![Error Recovery Overview](/course-assets/s11_error_recovery/error-recovery-overview.en.svg)\n\nThe loop and prompt assembly from s10 are fully preserved. The only change: the LLM call is wrapped in try/except, with different recovery paths based on error type. After recovery, `continue` loops back to the top to call the LLM again.\n\nThis chapter implements three recovery patterns:\n\n| Pattern | Trigger | Recovery Action |\n|----------|---------|-----------------|\n| Output truncated | `max_tokens` | Escalate 8K→64K / continuation prompt |\n| Context overflow | `prompt_too_long` | Reactive compact → retry |\n| Transient failure | 429 / 529 | Exponential backoff + jitter, fallback model on consecutive 529 |\n\n---\n\n## How It Works\n\n### Path 1: Output Truncated\n\nThe model runs out of tokens mid-sentence — `max_tokens` is exhausted. The default 8000 tokens isn't enough for a complete response.\n\nOn the first occurrence, escalate `max_tokens` from 8K to 64K (8x the space) and retry the same request — the truncated output is NOT appended to messages, keeping the original request intact. If 64K is still not enough, save the truncated output and inject a continuation prompt telling the model to pick up where it left off, up to 3 times:\n\n```python\nif response.stop_reason == \"max_tokens\":\n    # First escalation: don't append truncated output, retry same request\n    if not state.has_escalated:\n        max_tokens = ESCALATED_MAX_TOKENS\n        state.has_escalated = True\n        continue  # messages unchanged, same request with more tokens\n    # 64K still truncated: save output + continuation prompt\n    messages.append({\"role\": \"assistant\", \"content\": response.content})\n    if state.recovery_count < MAX_RECOVERY_RETRIES:\n        messages.append({\"role\": \"user\", \"content\":\n            \"Output token limit hit. Resume directly — \"\n            \"no apology, no recap. Pick up mid-thought.\"})\n        state.recovery_count += 1\n        continue\n    return  # still truncated after 3 continuations\n# Normal: append after max_tokens check\nmessages.append({\"role\": \"assistant\", \"content\": response.content})\n```\n\nEscalation gets one chance; continuation gets up to 3. After that, exit — further continuations won't produce meaningful output.\n\n### Path 2: Context Overflow\n\nThe LLM says \"your context is too long\" (`prompt_too_long`). All four compaction layers from s08 have already run, and it's still over the limit.\n\nTrigger reactive compact: keep the last 5 messages and retry once. If the context is still over the limit, exit:\n\n```python\nexcept PromptTooLongError:\n    if not state.has_attempted_reactive_compact:\n        messages[:] = reactive_compact(messages)\n        state.has_attempted_reactive_compact = True\n        continue\n    return  # Already compacted and still over limit — must exit\n```\n\n### Path 3: Transient Failures\n\nNetwork blips, 429 rate limiting, 529 overload — these aren't bugs, they're normal in distributed systems.\n\nBoth 429 and 529 use exponential backoff + jitter: wait 0.5 seconds on the first attempt, 1 second on the second, 2 seconds on the third, up to 10 retries. Random jitter prevents concurrent requests from all retrying at the same instant. Three consecutive 529 overload errors → switch to the fallback model (if `FALLBACK_MODEL_ID` environment variable is configured):\n\n```python\ndef retry_delay(attempt, retry_after=None):\n    if retry_after:\n        return retry_after\n    base = min(500 * (2 ** attempt), 32000) / 1000\n    return base + random.uniform(0, base * 0.25)\n\ndef with_retry(fn, state, max_retries=10):\n    for attempt in range(max_retries):\n        try:\n            return fn()\n        except (RateLimitError, OverloadedError):\n            delay = retry_delay(attempt)\n            time.sleep(delay)\n            if is_overloaded:\n                state.consecutive_529 += 1\n                if state.consecutive_529 >= 3 and FALLBACK_MODEL:\n                    state.current_model = FALLBACK_MODEL\n    raise MaxRetriesExceeded()\n```\n\nBackoff formula: `min(500 × 2^attempt, 32000) + random(0~25%)`. If the server returns a `Retry-After` header, that value takes priority.\n\n### Putting It All Together\n\n```python\ndef agent_loop(messages, context):\n    system = get_system_prompt(context)\n    state = RecoveryState()\n    max_tokens = 8000\n\n    while True:\n        try:\n            response = with_retry(\n                lambda: client.messages.create(\n                    model=state.current_model, system=system,\n                    messages=messages, tools=TOOLS,\n                    max_tokens=max_tokens),\n                state)\n        except Exception as e:\n            if is_prompt_too_long_error(e):\n                if not state.has_attempted_reactive_compact:\n                    messages[:] = reactive_compact(messages)\n                    state.has_attempted_reactive_compact = True\n                    continue\n                return\n            log_error(e)\n            return\n\n        # max_tokens check BEFORE appending to messages\n        if response.stop_reason == \"max_tokens\":\n            if not state.has_escalated:\n                max_tokens = 64000\n                state.has_escalated = True\n                continue  # retry same request, messages unchanged\n            # save truncated output + continuation prompt\n            messages.append({\"role\": \"assistant\", \"content\": response.content})\n            messages.append({\"role\": \"user\", \"content\": CONTINUATION_PROMPT})\n            continue\n        # Normal completion\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n        # ... tool execution ...\n```\n\nThe outer try/except catches API exceptions (prompt_too_long, etc.), `with_retry` handles transient errors (429/529), and `stop_reason` checks handle truncation. Three recovery mechanisms, each handling its own error type.\n\n---\n\n## Changes from s10\n\n| Component | Before (s10) | After (s11) |\n|-----------|-------------|-------------|\n| Error handling | None (crashes on any error) | Three recovery patterns + exponential backoff |\n| New constants | — | ESCALATED_MAX_TOKENS=64000, MAX_RETRIES=10, BASE_DELAY_MS=500, FALLBACK_MODEL |\n| New functions | — | with_retry, retry_delay, reactive_compact, is_prompt_too_long_error, RecoveryState |\n| Tools | bash, read_file, write_file (3) | bash, read_file, write_file (3) — unchanged |\n| Loop | Bare LLM call | Wrapped in try/except + continue retry |\n\n---\n\n## Try It\n\n```sh\ncd learn-claude-code\npython s11_error_recovery/code.py\n```\n\nTry these prompts:\n\n1. Ask the Agent to generate a very long piece of code, and observe whether it automatically continues after truncation (look for the `[max_tokens] escalating` log)\n2. Read many files consecutively to bloat the context, and observe reactive compact\n3. If you encounter 429/529, observe the exponential backoff log output\n\n---\n\n## What's Next\n\nThe Agent can now automatically recover from errors. But the tasks it handles are still one-shot — you give it a task, it finishes, it's done.\n\nWhat if the Agent could manage a **task list** — with dependencies, persisted to disk, resumable across sessions? A TODO list is not a task system.\n\ns12 Task System → Tasks form a dependency graph with state and persistence. This is the foundation for multi-Agent collaboration.\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s11",
    "locale": "zh",
    "title": "s11: Error Recovery — 错误不是结束，是重试的开始",
    "content": "# s11: Error Recovery — 错误不是结束，是重试的开始\n\ns01 → ... → s09 → s10 → `s11` → [s12](/zh/s12) → s13 → ... → s20 → s21\n> *\"错误不是终点, 是重试的起点\"* — 升级 token、压缩上下文、切换模型。\n>\n> **Harness 层**: 韧性 — 主循环遇到错误时分类并恢复。\n\n---\n\n## 问题\n\nAgent 跑着跑着报错了：\n\n```\nError: 529 overloaded\n```\n\nAgent 崩溃了。它没有重试，没有换模型，没有减少上下文——直接崩溃。\n\nLLM API 调用可能失败。本章处理三种情况：输出截断、上下文超限和临时故障（429/529）。\n\n---\n\n## 解决方案\n\n![Error Recovery Overview](/course-assets/s11_error_recovery/error-recovery-overview.svg)\n\ns10 的循环、prompt 组装全部保留。唯一的变动：LLM 调用包裹在 try/except 里，根据错误类型走不同的恢复路径。恢复后 `continue` 回到循环开头重新调用 LLM。\n\n本章实现三种恢复模式：\n\n| 模式 | 触发 | 恢复动作 |\n|------|------|---------|\n| 输出截断 | `max_tokens` | 升级 8K→64K / 续写提示 |\n| 上下文超限 | `prompt_too_long` | reactive compact → 重试 |\n| 临时故障 | 429 / 529 | 指数退避 + 抖动，连续 529 可切换备用模型 |\n\n---\n\n## 工作原理\n\n### 路径 1: 输出被截断\n\n模型话说一半，`max_tokens` 用完了。默认 8000 token 不够它输出完整回答。\n\n第一次发生时，直接把 `max_tokens` 从 8K 升级到 64K（8 倍空间），重试同一请求——此时不追加截断输出到 messages，保持原始请求不变。如果 64K 还是不够，才保存截断输出并注入续写提示让模型接着刚才的话继续说，最多 3 次：\n\n```python\nif response.stop_reason == \"max_tokens\":\n    # First escalation: don't append truncated output, retry same request\n    if not state.has_escalated:\n        max_tokens = ESCALATED_MAX_TOKENS\n        state.has_escalated = True\n        continue  # messages unchanged, same request with more tokens\n    # 64K still truncated: save output + continuation prompt\n    messages.append({\"role\": \"assistant\", \"content\": response.content})\n    if state.recovery_count < MAX_RECOVERY_RETRIES:\n        messages.append({\"role\": \"user\", \"content\":\n            \"Output token limit hit. Resume directly — \"\n            \"no apology, no recap. Pick up mid-thought.\"})\n        state.recovery_count += 1\n        continue\n    return  # still truncated after 3 continuations\n# Normal: append after max_tokens check\nmessages.append({\"role\": \"assistant\", \"content\": response.content})\n```\n\n升级只有一次机会，续写最多 3 次。超过就退出——继续续写也不会有实质产出。\n\n### 路径 2: 上下文超限\n\nLLM 说\"你的上下文太长了\"（`prompt_too_long`）。s08 的四层压缩全跑过了，还是超。\n\n触发 reactive compact：保留最后 5 条消息后重试一次。如果仍然超限，则退出：\n\n```python\nexcept PromptTooLongError:\n    if not state.has_attempted_reactive_compact:\n        messages[:] = reactive_compact(messages)\n        state.has_attempted_reactive_compact = True\n        continue\n    return  # 压缩过了还是超限，只能退出\n```\n\n### 路径 3: 临时故障\n\n网络抖动、429 限流、529 过载——这些不是 bug，是分布式系统的常态。\n\n429 和 529 统一走指数退避 + 抖动：第一次等 0.5 秒，第二次等 1 秒，第三次等 2 秒，最多 10 次。加随机抖动让并发请求不在同一时刻重试。连续 3 次 529 过载 → 切换到备用模型（若配置了 `FALLBACK_MODEL_ID` 环境变量）：\n\n```python\ndef retry_delay(attempt, retry_after=None):\n    if retry_after:\n        return retry_after\n    base = min(500 * (2 ** attempt), 32000) / 1000\n    return base + random.uniform(0, base * 0.25)\n\ndef with_retry(fn, state, max_retries=10):\n    for attempt in range(max_retries):\n        try:\n            return fn()\n        except (RateLimitError, OverloadedError):\n            delay = retry_delay(attempt)\n            time.sleep(delay)\n            if is_overloaded:\n                state.consecutive_529 += 1\n                if state.consecutive_529 >= 3 and FALLBACK_MODEL:\n                    state.current_model = FALLBACK_MODEL\n    raise MaxRetriesExceeded()\n```\n\n退避公式：`min(500 × 2^attempt, 32000) + random(0~25%)`。如果服务器返回 `Retry-After` header，优先用那个值。\n\n### 合起来跑\n\n```python\ndef agent_loop(messages, context):\n    system = get_system_prompt(context)\n    state = RecoveryState()\n    max_tokens = 8000\n\n    while True:\n        try:\n            response = with_retry(\n                lambda: client.messages.create(\n                    model=state.current_model, system=system,\n                    messages=messages, tools=TOOLS,\n                    max_tokens=max_tokens),\n                state)\n        except Exception as e:\n            if is_prompt_too_long_error(e):\n                if not state.has_attempted_reactive_compact:\n                    messages[:] = reactive_compact(messages)\n                    state.has_attempted_reactive_compact = True\n                    continue\n                return\n            log_error(e)\n            return\n\n        # max_tokens check BEFORE appending to messages\n        if response.stop_reason == \"max_tokens\":\n            if not state.has_escalated:\n                max_tokens = 64000\n                state.has_escalated = True\n                continue  # retry same request, messages unchanged\n            # save truncated output + continuation prompt\n            messages.append({\"role\": \"assistant\", \"content\": response.content})\n            messages.append({\"role\": \"user\", \"content\": CONTINUATION_PROMPT})\n            continue\n        # Normal completion\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n        # ... tool execution ...\n```\n\n外层 try/except 捕获 API 异常（prompt_too_long 等），`with_retry` 处理瞬态错误（429/529），`stop_reason` 检查处理截断。三种恢复机制各管各的错误类型。\n\n---\n\n## 相对 s10 的变更\n\n| 组件 | 之前 (s10) | 之后 (s11) |\n|------|-----------|-----------|\n| 错误处理 | 无（一碰就崩溃） | 三种恢复模式 + 指数退避 |\n| 新常量 | — | ESCALATED_MAX_TOKENS=64000, MAX_RETRIES=10, BASE_DELAY_MS=500, FALLBACK_MODEL |\n| 新函数 | — | with_retry, retry_delay, reactive_compact, is_prompt_too_long_error, RecoveryState |\n| 工具 | bash, read_file, write_file (3) | bash, read_file, write_file (3) — 不变 |\n| 循环 | 裸调用 LLM | try/except 包裹 + continue 重试 |\n\n---\n\n## 试一下\n\n```sh\ncd learn-claude-code\npython s11_error_recovery/code.py\n```\n\n试试这些 prompt：\n\n1. 让 Agent 生成一段很长的代码，观察截断后是否自动续写（看 `[max_tokens] escalating` 日志）\n2. 连续读取大量文件撑大上下文，观察 reactive compact\n3. 如果遇到 429/529，观察指数退避的日志输出\n\n---\n\n## 接下来\n\nAgent 现在能在错误中自动恢复了。但它处理的任务仍然是\"一次性\"的——你给它一个任务，它做完，结束。\n\n能不能让 Agent 管理一个**任务列表**——有依赖关系、持久化到磁盘、跨会话能恢复？TODO 列表不是任务系统。\n\ns12 Task System → 任务是有依赖、有状态、持久化的图。这是多 Agent 协作的基础。\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s11",
    "locale": "ja",
    "title": "s11: Error Recovery — エラーは終わりではなく、リトライの始まり",
    "content": "# s11: Error Recovery — エラーは終わりではなく、リトライの始まり\n\ns01 → ... → s09 → s10 → `s11` → [s12](/ja/s12) → s13 → ... → s20 → s21\n> *\"エラーは終わりではなく、リトライの始まり\"* — トークン拡張、コンテキスト圧縮、モデル切り替え。\n>\n> **Harness 層**: 耐障害性 — メインループのエラーを分類し復旧。\n\n---\n\n## 課題\n\nAgent が動いている途中でエラーが出た：\n\n```\nError: 529 overloaded\n```\n\nAgent がクラッシュした。リトライもしない、モデルも切り替えない、コンテキストも減らさない——そのままクラッシュ。\n\nLLM API の呼び出しは失敗することがある。この章では、出力の切り詰め、コンテキスト超過、一時的障害（429/529）の 3 つを扱う。\n\n---\n\n## 解決策\n\n![Error Recovery Overview](/course-assets/s11_error_recovery/error-recovery-overview.ja.svg)\n\ns10 のループ、prompt 組み立てはすべてそのまま。唯一の変更点：LLM 呼び出しを try/except で包み、エラータイプに応じて異なる復旧パスに振り分ける。復旧後は `continue` でループ先頭に戻り、再度 LLM を呼び出す。\n\nこの章では 3 つの復旧パターンを実装する：\n\n| パターン | トリガー | 復旧アクション |\n|----------|----------|---------------|\n| 出力切り詰め | `max_tokens` | 8K→64K に拡張 / 続きのプロンプト注入 |\n| コンテキスト超過 | `prompt_too_long` | reactive compact → リトライ |\n| 一時的障害 | 429 / 529 | 指数バックオフ + ジッター、連続 529 でフォールバックモデルに切り替え可能 |\n\n---\n\n## 仕組み\n\n### パス 1: 出力が切り詰められた\n\nモデルが途中まで出力して、`max_tokens` に達した。デフォルトの 8000 token では完全な回答を出力しきれない。\n\n初回発生時、`max_tokens` を 8K から 64K に拡張（8 倍の空間）し、同じリクエストをリトライする——この時、切り詰められた出力は messages に追加せず、元のリクエストをそのまま維持する。64K でも足りない場合にのみ、切り詰められた出力を保存し、続きのプロンプトを注入してモデルに先ほどの続きを出力させる。最大 3 回まで：\n\n```python\nif response.stop_reason == \"max_tokens\":\n    # First escalation: don't append truncated output, retry same request\n    if not state.has_escalated:\n        max_tokens = ESCALATED_MAX_TOKENS\n        state.has_escalated = True\n        continue  # messages unchanged, same request with more tokens\n    # 64K still truncated: save output + continuation prompt\n    messages.append({\"role\": \"assistant\", \"content\": response.content})\n    if state.recovery_count < MAX_RECOVERY_RETRIES:\n        messages.append({\"role\": \"user\", \"content\":\n            \"Output token limit hit. Resume directly — \"\n            \"no apology, no recap. Pick up mid-thought.\"})\n        state.recovery_count += 1\n        continue\n    return  # still truncated after 3 continuations\n# Normal: append after max_tokens check\nmessages.append({\"role\": \"assistant\", \"content\": response.content})\n```\n\n拡張は 1 回だけ、続きの出力は最大 3 回。超過したら終了——これ以上続けても実質的な出力は得られない。\n\n### パス 2: コンテキスト超過\n\nLLM が「コンテキストが長すぎる」と返す（`prompt_too_long`）。s08 の 4 層圧縮をすべて実行したのに、まだ超えている。\n\nreactive compact を実行し、最後の 5 メッセージを残して 1 回だけ再試行する。それでも上限を超える場合は終了する：\n\n```python\nexcept PromptTooLongError:\n    if not state.has_attempted_reactive_compact:\n        messages[:] = reactive_compact(messages)\n        state.has_attempted_reactive_compact = True\n        continue\n    return  # 圧縮済みでも超過、終了するしかない\n```\n\n### パス 3: 一時的障害\n\nネットワークの揺らぎ、429 レート制限、529 過負荷——これらはバグではなく、分散システムの日常だ。\n\n429 と 529 は統一して指数バックオフ + ジッターを使用：1 回目は 0.5 秒待機、2 回目は 1 秒、3 回目は 2 秒、最大 10 回。ランダムジッターを加えることで、並行リクエストが同時にリトライするのを防ぐ。3 回連続で 529 過負荷 → フォールバックモデルに切り替え（`FALLBACK_MODEL_ID` 環境変数が設定されている場合）：\n\n```python\ndef retry_delay(attempt, retry_after=None):\n    if retry_after:\n        return retry_after\n    base = min(500 * (2 ** attempt), 32000) / 1000\n    return base + random.uniform(0, base * 0.25)\n\ndef with_retry(fn, state, max_retries=10):\n    for attempt in range(max_retries):\n        try:\n            return fn()\n        except (RateLimitError, OverloadedError):\n            delay = retry_delay(attempt)\n            time.sleep(delay)\n            if is_overloaded:\n                state.consecutive_529 += 1\n                if state.consecutive_529 >= 3 and FALLBACK_MODEL:\n                    state.current_model = FALLBACK_MODEL\n    raise MaxRetriesExceeded()\n```\n\nバックオフの公式：`min(500 × 2^attempt, 32000) + random(0~25%)`。サーバーが `Retry-After` ヘッダーを返した場合、その値を優先して使用する。\n\n### 統合して実行\n\n```python\ndef agent_loop(messages, context):\n    system = get_system_prompt(context)\n    state = RecoveryState()\n    max_tokens = 8000\n\n    while True:\n        try:\n            response = with_retry(\n                lambda: client.messages.create(\n                    model=state.current_model, system=system,\n                    messages=messages, tools=TOOLS,\n                    max_tokens=max_tokens),\n                state)\n        except Exception as e:\n            if is_prompt_too_long_error(e):\n                if not state.has_attempted_reactive_compact:\n                    messages[:] = reactive_compact(messages)\n                    state.has_attempted_reactive_compact = True\n                    continue\n                return\n            log_error(e)\n            return\n\n        # max_tokens check BEFORE appending to messages\n        if response.stop_reason == \"max_tokens\":\n            if not state.has_escalated:\n                max_tokens = 64000\n                state.has_escalated = True\n                continue  # retry same request, messages unchanged\n            # save truncated output + continuation prompt\n            messages.append({\"role\": \"assistant\", \"content\": response.content})\n            messages.append({\"role\": \"user\", \"content\": CONTINUATION_PROMPT})\n            continue\n        # Normal completion\n        messages.append({\"role\": \"assistant\", \"content\": response.content})\n\n        if response.stop_reason != \"tool_use\":\n            return\n        # ... tool execution ...\n```\n\n外側の try/except が API 例外（prompt_too_long 等）を捕捉し、`with_retry` が一時的エラー（429/529）を処理し、`stop_reason` のチェックが切り詰めを処理する。3 つの復旧メカニズムがそれぞれ異なるエラータイプを担当する。\n\n---\n\n## s10 からの変更点\n\n| コンポーネント | 変更前 (s10) | 変更後 (s11) |\n|---------------|-------------|-------------|\n| エラー処理 | なし（エラーで即クラッシュ） | 3 つの復旧パターン + 指数バックオフ |\n| 新規定数 | — | ESCALATED_MAX_TOKENS=64000, MAX_RETRIES=10, BASE_DELAY_MS=500, FALLBACK_MODEL |\n| 新規関数 | — | with_retry, retry_delay, reactive_compact, is_prompt_too_long_error, RecoveryState |\n| ツール | bash, read_file, write_file (3) | bash, read_file, write_file (3) — 変更なし |\n| ループ | LLM を直接呼び出し | try/except で包み + continue でリトライ |\n\n---\n\n## 試してみる\n\n```sh\ncd learn-claude-code\npython s11_error_recovery/code.py\n```\n\n以下の prompt を試してみよう：\n\n1. Agent に長いコードを生成させ、切り詰め後に自動で続きが出力されるか観察する（`[max_tokens] escalating` ログを確認）\n2. 連続して大量のファイルを読み込みコンテキストを肥大化させ、reactive compact の動作を観察する\n3. 429/529 が発生した場合、指数バックオフのログ出力を観察する\n\n---\n\n## 次のステップ\n\nAgent はエラーから自動的に復旧できるようになった。しかし、まだ処理するタスクは「使い捨て」だ——タスクを与えると実行し、終わる。\n\nAgent に**タスクリスト**を管理させられないだろうか——依存関係があり、ディスクに永続化され、セッションをまたいで復旧できる？TODO リストはタスクシステムではない。\n\ns12 Task System → タスクとは依存関係があり、状態があり、永続化されたグラフだ。これはマルチ Agent 協調の基盤となる。\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s12",
    "locale": "en",
    "title": "s12: Task System — Break Big Goals into Small Tasks",
    "content": "# s12: Task System — Break Big Goals into Small Tasks\n\ns01 → ... → s10 → s11 → `s12` → [s13](/en/s13) → s14 → ... → s20 → s21\n\n> *\"Break big goals into small tasks, order them, persist\"* — File-persisted task graph, the foundation for multi-agent collaboration.\n>\n> **Harness Layer**: Tasks — Persisted goals, recoverable progress.\n\n---\n\n## The Problem\n\nThe agent receives a project: set up a database, write APIs, add tests. It uses s05's TodoWrite to create a checklist, then starts writing the API first, gets halfway through and realizes there are no database tables, goes back to fix them; when adding tests, discovers the API interface signatures have changed again...\n\nYou can't build the roof before laying the foundation. Tasks have ordering. Task prerequisites can be represented as a Directed Acyclic Graph (DAG); this chapter records them with `blockedBy`.\n\ns05's TodoWrite is an execution checklist for the current task, kept in session memory. What you need here is a **task system**: each task is a JSON file, tasks have `blockedBy` dependencies, and they persist across sessions on disk.\n\n---\n\n## The Solution\n\n![Task System Overview](/course-assets/s12_task_system/task-system-overview.en.svg)\n\nThis chapter adds 5 task tools, persistence in the `.tasks/` directory, and `blockedBy` dependency checks.\n\nTodoWrite vs Task System:\n\n| | TodoWrite (s05) | Task System (s12) |\n|---|---|---|\n| Role | Execution checklist for the current task | Recoverable task system |\n| Storage | In-process / session state | `.tasks/{id}.json` |\n| Dependencies | None | `blockedBy` / `blocks` graph |\n| Lifecycle | Current session / current task | Cross-session |\n| Coordination | No task claiming | `owner` / claim |\n| Status | pending / in_progress / completed | pending / in_progress / completed |\n| Granularity | The agent's own steps | Tasks that can be claimed, tracked, and unblocked |\n| Update contract | Replace the whole checklist | Create/get/update/list individual records |\n\n---\n\n## How It Works\n\n![Task DAG](/course-assets/s12_task_system/task-dag.en.svg)\n\n### Task: Data Structure\n\nEach task is a JSON file, stored in the `.tasks/` directory:\n\n```python\n@dataclass\nclass Task:\n    id: str\n    subject: str\n    description: str\n    status: str          # pending | in_progress | completed\n    owner: str | None    # Agent name (multi-agent scenarios)\n    blockedBy: list[str] # List of dependency task IDs\n```\n\nIDs are generated with `timestamp + random hex`.\n\n### create_task: Create Tasks\n\n```python\ndef create_task(subject: str, description: str = \"\",\n                blockedBy: list[str] | None = None) -> Task:\n    task = Task(\n        id=f\"task_{int(time.time())}_{random_hex(4)}\",\n        subject=subject, description=description,\n        status=\"pending\", owner=None,\n        blockedBy=blockedBy or [],\n    )\n    save_task(task)\n    return task\n```\n\nAutomatically calls `save_task` on creation to write `.tasks/{id}.json`. `blockedBy` declares dependencies, for example \"write API\" has `blockedBy: [\"task_schema\"]`.\n\n### can_start: Dependency Check\n\nA task can only start after all its `blockedBy` dependencies are **completed**:\n\n```python\ndef can_start(task_id: str) -> bool:\n    task = load_task(task_id)\n    for dep_id in task.blockedBy:\n        if not _task_path(dep_id).exists():\n            return False  # missing dependency = blocked\n        dep = load_task(dep_id)\n        if dep.status != \"completed\":\n            return False\n    return True\n```\n\n`can_start` is a prerequisite check for `claim_task`: if any `blockedBy` dependency is not completed, the task cannot be claimed. Missing dependencies are treated as blocked, avoiding crashes from referencing wrong IDs.\n\n### claim_task: Claim a Task\n\nWhen the agent starts working on a task, it calls `claim_task`: sets `owner`, changes status from `pending` → `in_progress`. The `owner` field records who is working on the task, preventing duplicate claims in multi-agent scenarios:\n\n```python\ndef claim_task(task_id: str, owner: str = \"agent\") -> str:\n    task = load_task(task_id)\n    if task.status != \"pending\":\n        return f\"Task {task_id} is {task.status}, cannot claim\"\n    if not can_start(task_id):\n        deps = [d for d in task.blockedBy\n                if load_task(d).status != \"completed\"]\n        return f\"Blocked by: {deps}\"\n    task.owner = owner\n    task.status = \"in_progress\"\n    save_task(task)\n    return f\"Claimed {task_id} ({task.subject})\"\n```\n\nIf the task is already claimed by someone else (`status != \"pending\"`), or dependencies aren't met (`can_start` returns False), the claim is rejected.\n\n### complete_task: Complete and Unblock\n\nWhen a task is done, set it to `completed`. Simultaneously scan all other tasks to find downstream tasks that were **just unblocked**:\n\n```python\ndef complete_task(task_id: str) -> str:\n    task = load_task(task_id)\n    task.status = \"completed\"\n    save_task(task)\n    # Find newly unblocked downstream tasks\n    unblocked = [t.subject for t in list_tasks()\n                 if t.status == \"pending\" and t.blockedBy\n                 and can_start(t.id)]\n    msg = f\"Completed {task_id} ({task.subject})\"\n    if unblocked:\n        msg += f\"\\nUnblocked: {', '.join(unblocked)}\"\n    return msg\n```\n\nAfter completing \"schema\", `can_start` returns True for \"endpoints\" and \"docs\"; they can begin.\n\n### get_task: View Full Details\n\n`list_tasks` only shows a one-line summary. `get_task` returns the full task JSON, including description and dependency details. When recovering across sessions, the agent needs to read the full description to continue work:\n\n```python\ndef get_task(task_id: str) -> str:\n    task = load_task(task_id)\n    return json.dumps(asdict(task), indent=2)\n```\n\n### State Machine: Two Actions, Three States\n\n```\npending ──claim──→ in_progress ──complete──→ completed\n```\n\nHere `claim` / `complete` are actions, while `pending` / `in_progress` / `completed` are states:\n\n- **claim_task**: `pending` → `in_progress`. Sets owner, begins work.\n- **complete_task**: `in_progress` → `completed`. Marks the task done and unblocks downstream.\n\n### Putting It Together\n\n```python\n# Create tasks with dependencies\nschema = create_task(\"setup database schema\")\nendpoints = create_task(\"create API endpoints\", blockedBy=[schema.id])\ntests = create_task(\"write tests\", blockedBy=[endpoints.id])\ndocs = create_task(\"write docs\", blockedBy=[schema.id])\n\n# Agent claims the first available task\nclaim_task(schema.id)       # ✓ Claimed (no dependencies)\ncomplete_task(schema.id)    # ✓ Completed → unblocks endpoints, docs\n\nclaim_task(endpoints.id)    # ✓ Claimed (schema completed)\ncomplete_task(endpoints.id) # ✓ Completed → unblocks tests\n\nclaim_task(docs.id)         # ✓ Claimed (schema completed)\ncomplete_task(docs.id)      # ✓ Completed\n\nclaim_task(tests.id)        # ✓ Claimed (endpoints completed)\ncomplete_task(tests.id)     # ✓ Completed\n```\n\nEach `create_task` writes a JSON file, each `claim_task` / `complete_task` updates the file. Across sessions, the `.tasks/` directory persists — the agent reads the files to recover progress.\n\n---\n\n## Changes from s11\n\n| Component | Before (s11) | After (s12) |\n|-----------|-------------|-------------|\n| Task management | None | Task dataclass + 5 tools |\n| New types | — | Task (id, subject, description, status, owner, blockedBy) |\n| Storage | No persistence | `.tasks/{id}.json` cross-session |\n| Dependencies | None | `blockedBy` graph + `can_start` check |\n| Tools | bash, read_file, write_file (3) | + create_task, list_tasks, get_task, claim_task, complete_task (8) |\n| Lifecycle | — | pending → in_progress → completed (no release rollback) |\n\n---\n\n## Try It\n\n```sh\ncd learn-claude-code\npython s12_task_system/code.py\n```\n\nTry these prompts:\n\n1. `Create tasks: setup database schema, create API endpoints (depends on schema), write tests (depends on endpoints), write docs (depends on schema)`\n2. `List all tasks and their statuses`\n3. `Claim the first unblocked task and complete it`\n4. `List tasks again — which ones are now unblocked?`\n\nWhat to observe: Are JSON files generated in the `.tasks/` directory? After completing a task, are the blocked tasks unblocked?\n\n---\n\n## What's Next\n\nThe task graph is in place. But some tasks take a long time — like running full test suites or deploying to a server. The agent calls the LLM billed by token, it can't afford to wait on a slow operation.\n\ns13 Background Tasks → Slow operations go to the background. The agent continues processing other tasks, and gets notified when the background work is done.\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s12",
    "locale": "zh",
    "title": "s12: Task System — 目标太大，拆成小任务",
    "content": "# s12: Task System — 目标太大，拆成小任务\n\ns01 → ... → s10 → s11 → `s12` → [s13](/zh/s13) → s14 → ... → s20 → s21\n\n> *\"大目标拆成小任务, 排好序, 持久化\"* — 文件持久化的任务图, 多 agent 协作的基础。\n>\n> **Harness 层**: 任务 — 持久化的目标, 可恢复的进度。\n\n---\n\n## 问题\n\nAgent 接到一个项目：搭数据库、写 API、加测试。它用 s05 的 TodoWrite 列了一张清单，然后开始写 API，写到一半发现没数据库表，回头补；加测试时发现 API 接口签名又变了...\n\n盖房子不能先盖屋顶再打地基。任务之间有先后。任务之间的前置依赖可以表示为有向无环图（DAG），本章用 `blockedBy` 记录这些依赖。\n\ns05 的 TodoWrite 是当前任务的执行清单，保存在会话内存中。这里需要的是**任务系统**：每个任务是一个 JSON 文件，任务之间有 `blockedBy` 依赖，跨会话持久化在磁盘上。\n\n---\n\n## 解决方案\n\n![Task System Overview](/course-assets/s12_task_system/task-system-overview.svg)\n\n本章新增 5 个任务工具、`.tasks/` 目录持久化和 `blockedBy` 依赖检查。\n\nTodoWrite vs Task System：\n\n| | TodoWrite (s05) | Task System (s12) |\n|---|---|---|\n| 定位 | 当前任务的执行清单 | 可恢复的任务系统 |\n| 存储 | 进程内 / 会话状态 | `.tasks/{id}.json` |\n| 依赖 | 无 | `blockedBy` / `blocks` 依赖图 |\n| 生命周期 | 当前会话 / 当前任务 | 跨会话保留 |\n| 分工 | 不负责任务认领 | `owner` / claim |\n| 状态 | pending / in_progress / completed | pending / in_progress / completed |\n| 粒度 | Agent 自己的步骤 | 可被认领、追踪、解锁的任务 |\n| 更新契约 | 整表替换 | 对单条记录执行创建、读取、更新、列举 |\n\n---\n\n## 工作原理\n\n![Task DAG](/course-assets/s12_task_system/task-dag.svg)\n\n### Task: 数据结构\n\n每个任务是一个 JSON 文件，存于 `.tasks/` 目录：\n\n```python\n@dataclass\nclass Task:\n    id: str\n    subject: str\n    description: str\n    status: str          # pending | in_progress | completed\n    owner: str | None    # Agent 名（多 Agent 场景）\n    blockedBy: list[str] # 依赖的任务 ID 列表\n```\n\nID 使用 `timestamp + random hex` 生成。\n\n### create_task: 创建任务\n\n```python\ndef create_task(subject: str, description: str = \"\",\n                blockedBy: list[str] | None = None) -> Task:\n    task = Task(\n        id=f\"task_{int(time.time())}_{random_hex(4)}\",\n        subject=subject, description=description,\n        status=\"pending\", owner=None,\n        blockedBy=blockedBy or [],\n    )\n    save_task(task)\n    return task\n```\n\n创建时自动 `save_task` 到 `.tasks/{id}.json`。`blockedBy` 声明依赖，比如 \"写 API\" 的 `blockedBy` 是 `[\"task_schema\"]`。\n\n### can_start: 依赖检查\n\n一个任务只能在它的 `blockedBy` **全部 completed** 之后才能开始：\n\n```python\ndef can_start(task_id: str) -> bool:\n    task = load_task(task_id)\n    for dep_id in task.blockedBy:\n        if not _task_path(dep_id).exists():\n            return False  # missing dependency = blocked\n        dep = load_task(dep_id)\n        if dep.status != \"completed\":\n            return False\n    return True\n```\n\n`can_start` 是 `claim_task` 的前置检查：`blockedBy` 里有任何一个不是 completed，就不能认领。不存在的依赖视为 blocked，避免引用错误 ID 时崩溃。\n\n### claim_task: 认领任务\n\nAgent 开始做一个任务时，调用 `claim_task`：设置 `owner`，状态从 `pending` → `in_progress`。`owner` 字段记录谁在做这个任务，多 Agent 场景下防止重复认领：\n\n```python\ndef claim_task(task_id: str, owner: str = \"agent\") -> str:\n    task = load_task(task_id)\n    if task.status != \"pending\":\n        return f\"Task {task_id} is {task.status}, cannot claim\"\n    if not can_start(task_id):\n        deps = [d for d in task.blockedBy\n                if load_task(d).status != \"completed\"]\n        return f\"Blocked by: {deps}\"\n    task.owner = owner\n    task.status = \"in_progress\"\n    save_task(task)\n    return f\"Claimed {task_id} ({task.subject})\"\n```\n\n如果任务已被别人认领（`status != \"pending\"`），或者依赖没完成（`can_start` 返回 False），拒绝认领。\n\n### complete_task: 完成与解锁\n\n任务做完后，设为 `completed`。同时扫描所有其他任务，找出**刚刚被解锁**的下游任务：\n\n```python\ndef complete_task(task_id: str) -> str:\n    task = load_task(task_id)\n    task.status = \"completed\"\n    save_task(task)\n    # 找出被解锁的下游任务\n    unblocked = [t.subject for t in list_tasks()\n                 if t.status == \"pending\" and t.blockedBy\n                 and can_start(t.id)]\n    msg = f\"Completed {task_id} ({task.subject})\"\n    if unblocked:\n        msg += f\"\\nUnblocked: {', '.join(unblocked)}\"\n    return msg\n```\n\n完成 \"schema\" 后，\"endpoints\" 和 \"docs\" 的 `can_start` 返回 True，它们可以开始。\n\n### get_task: 查看完整细节\n\n`list_tasks` 只显示一行摘要。`get_task` 返回完整的任务 JSON，包括 description 和依赖细节。跨会话恢复时，Agent 需要读取完整描述才能继续工作：\n\n```python\ndef get_task(task_id: str) -> str:\n    task = load_task(task_id)\n    return json.dumps(asdict(task), indent=2)\n```\n\n### 状态机: 两个动作，三个状态\n\n```\npending ──claim──→ in_progress ──complete──→ completed\n```\n\n这里的 `claim` / `complete` 是动作，`pending` / `in_progress` / `completed` 是状态：\n\n- **claim_task**: `pending` → `in_progress`。设置 owner，开始工作。\n- **complete_task**: `in_progress` → `completed`。把任务标记为完成，并解锁下游。\n\n### 合起来跑\n\n```python\n# 创建有依赖的任务\nschema = create_task(\"setup database schema\")\nendpoints = create_task(\"create API endpoints\", blockedBy=[schema.id])\ntests = create_task(\"write tests\", blockedBy=[endpoints.id])\ndocs = create_task(\"write docs\", blockedBy=[schema.id])\n\n# Agent 认领第一个可做的任务\nclaim_task(schema.id)       # ✓ Claimed (无依赖)\ncomplete_task(schema.id)    # ✓ Completed → 解锁 endpoints, docs\n\nclaim_task(endpoints.id)    # ✓ Claimed (schema 已完成)\ncomplete_task(endpoints.id) # ✓ Completed → 解锁 tests\n\nclaim_task(docs.id)         # ✓ Claimed (schema 已完成)\ncomplete_task(docs.id)      # ✓ Completed\n\nclaim_task(tests.id)        # ✓ Claimed (endpoints 已完成)\ncomplete_task(tests.id)     # ✓ Completed\n```\n\n每个 `create_task` 写一个 JSON 文件，每个 `claim_task` / `complete_task` 更新文件。跨会话时，`.tasks/` 目录还在，Agent 读文件就能恢复进度。\n\n---\n\n## 相对 s11 的变更\n\n| 组件 | 之前 (s11) | 之后 (s12) |\n|------|-----------|-----------|\n| 任务管理 | 无 | Task dataclass + 5 个工具 |\n| 新类型 | — | Task（id, subject, description, status, owner, blockedBy） |\n| 存储 | 无持久化 | `.tasks/{id}.json` 跨会话 |\n| 依赖 | 无 | `blockedBy` 图 + `can_start` 检查 |\n| 工具 | bash, read_file, write_file (3) | + create_task, list_tasks, get_task, claim_task, complete_task (8) |\n| 生命周期 | — | pending → in_progress → completed（无 release 回退） |\n\n---\n\n## 试一下\n\n```sh\ncd learn-claude-code\npython s12_task_system/code.py\n```\n\n试试这些 prompt：\n\n1. `Create tasks: setup database schema, create API endpoints (depends on schema), write tests (depends on endpoints), write docs (depends on schema)`\n2. `List all tasks and their statuses`\n3. `Claim the first unblocked task and complete it`\n4. `List tasks again — which ones are now unblocked?`\n\n观察重点：`.tasks/` 目录下是否生成了 JSON 文件？完成任务后，被阻塞的任务是否解锁？\n\n---\n\n## 接下来\n\n任务图有了。但有些任务要跑很久——比如全量测试、部署到服务器。Agent 调 LLM 按量计费，不能干等一个慢操作。\n\ns13 Background Tasks → 慢操作放后台。Agent 继续处理其他任务，后台跑完了通知它。\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s12",
    "locale": "ja",
    "title": "s12: Task System — 大きな目標を小さなタスクに分割",
    "content": "# s12: Task System — 大きな目標を小さなタスクに分割\n\ns01 → ... → s10 → s11 → `s12` → [s13](/ja/s13) → s14 → ... → s20 → s21\n\n> *\"大きな目標を小さなタスクに分け、順序付け、永続化\"* — ファイル永続化タスクグラフ、マルチ Agent 協調の基盤。\n>\n> **Harness 層**: タスク — 永続化された目標、復旧可能な進捗。\n\n---\n\n## 課題\n\nAgent がプロジェクトを受けた：データベース構築、API 実装、テスト追加。s05 の TodoWrite でリストを作り、まず API を書き始め、途中でデータベーステーブルがないことに気づいて戻る。テスト追加時に API インターフェースのシグネチャがまた変わっている...\n\n屋根を先に建てて基礎を後から打つことはできない。タスクには順序がある。タスク間の前提依存関係は有向非巡回グラフ（DAG）として表現でき、この章では `blockedBy` でそれらを記録する。\n\ns05 の TodoWrite は現在のタスクの実行チェックリストで、セッションメモリに保持される。ここで必要なのは**タスクシステム**：各タスクは JSON ファイル、タスク間に `blockedBy` 依存関係、ディスク上でセッションをまたいで永続化。\n\n---\n\n## ソリューション\n\n![Task System Overview](/course-assets/s12_task_system/task-system-overview.ja.svg)\n\nこの章では、5 つのタスクツール、`.tasks/` ディレクトリへの永続化、`blockedBy` の依存チェックを追加する。\n\nTodoWrite vs Task System：\n\n| | TodoWrite (s05) | Task System (s12) |\n|---|---|---|\n| 位置づけ | 現在のタスクの実行チェックリスト | 復旧可能なタスクシステム |\n| ストレージ | プロセス内 / セッション状態 | `.tasks/{id}.json` |\n| 依存関係 | なし | `blockedBy` / `blocks` グラフ |\n| ライフサイクル | 現在のセッション / 現在のタスク | セッション横断 |\n| 分担 | タスク認識を扱わない | `owner` / claim |\n| ステータス | pending / in_progress / completed | pending / in_progress / completed |\n| 粒度 | Agent 自身の手順 | 認識・追跡・アンロックできるタスク |\n| 更新契約 | リスト全体を置換 | 個別レコードを作成・取得・更新・一覧 |\n\n---\n\n## 仕組み\n\n![Task DAG](/course-assets/s12_task_system/task-dag.ja.svg)\n\n### Task: データ構造\n\n各タスクは JSON ファイル、`.tasks/` ディレクトリに保存：\n\n```python\n@dataclass\nclass Task:\n    id: str\n    subject: str\n    description: str\n    status: str          # pending | in_progress | completed\n    owner: str | None    # Agent 名（マルチ Agent シナリオ）\n    blockedBy: list[str] # 依存タスク ID のリスト\n```\n\nID は `timestamp + random hex` で生成する。\n\n### create_task: タスク作成\n\n```python\ndef create_task(subject: str, description: str = \"\",\n                blockedBy: list[str] | None = None) -> Task:\n    task = Task(\n        id=f\"task_{int(time.time())}_{random_hex(4)}\",\n        subject=subject, description=description,\n        status=\"pending\", owner=None,\n        blockedBy=blockedBy or [],\n    )\n    save_task(task)\n    return task\n```\n\n作成時に自動的に `save_task` で `.tasks/{id}.json` に書き込み。`blockedBy` で依存を宣言、例えば \"API を書く\" の `blockedBy` は `[\"task_schema\"]`。\n\n### can_start: 依存チェック\n\nタスクは `blockedBy` が**すべて completed** になってからでないと開始できない：\n\n```python\ndef can_start(task_id: str) -> bool:\n    task = load_task(task_id)\n    for dep_id in task.blockedBy:\n        if not _task_path(dep_id).exists():\n            return False  # missing dependency = blocked\n        dep = load_task(dep_id)\n        if dep.status != \"completed\":\n            return False\n    return True\n```\n\n`can_start` は `claim_task` の事前チェック：`blockedBy` に一つでも completed でないものがあれば、認識不可。存在しない依存は blocked として扱い、誤った ID 参照時のクラッシュを防ぐ。\n\n### claim_task: タスク認識\n\nAgent がタスクに取り掛かる時、`claim_task` を呼び出し：`owner` を設定、ステータスを `pending` → `in_progress` に変更。`owner` フィールドは誰が作業中かを記録し、マルチ Agent シナリオで重複認識を防止：\n\n```python\ndef claim_task(task_id: str, owner: str = \"agent\") -> str:\n    task = load_task(task_id)\n    if task.status != \"pending\":\n        return f\"Task {task_id} is {task.status}, cannot claim\"\n    if not can_start(task_id):\n        deps = [d for d in task.blockedBy\n                if load_task(d).status != \"completed\"]\n        return f\"Blocked by: {deps}\"\n    task.owner = owner\n    task.status = \"in_progress\"\n    save_task(task)\n    return f\"Claimed {task_id} ({task.subject})\"\n```\n\nタスクが既に他者に認識されている（`status != \"pending\"`）、または依存が未完了（`can_start` が False）の場合、認識を拒否。\n\n### complete_task: 完了とアンロック\n\nタスク完了後、`completed` に設定。同時に他の全タスクを走査し、**直前にアンロックされた**下流タスクを特定：\n\n```python\ndef complete_task(task_id: str) -> str:\n    task = load_task(task_id)\n    task.status = \"completed\"\n    save_task(task)\n    # アンロックされた下流タスクを検索\n    unblocked = [t.subject for t in list_tasks()\n                 if t.status == \"pending\" and t.blockedBy\n                 and can_start(t.id)]\n    msg = f\"Completed {task_id} ({task.subject})\"\n    if unblocked:\n        msg += f\"\\nUnblocked: {', '.join(unblocked)}\"\n    return msg\n```\n\n\"schema\" 完了後、\"endpoints\" と \"docs\" の `can_start` が True を返し、開始可能になる。\n\n### get_task: 完全な詳細を確認\n\n`list_tasks` は 1 行サマリのみ表示。`get_task` は description と依存関係の詳細を含む完全なタスク JSON を返す。セッションをまたいで復旧する際、Agent は完全な説明を読んで作業を継続する必要がある：\n\n```python\ndef get_task(task_id: str) -> str:\n    task = load_task(task_id)\n    return json.dumps(asdict(task), indent=2)\n```\n\n### 状態マシン: 2 つのアクション、3 つの状態\n\n```\npending ──claim──→ in_progress ──complete──→ completed\n```\n\nここで `claim` / `complete` はアクション、`pending` / `in_progress` / `completed` は状態：\n\n- **claim_task**: `pending` → `in_progress`。owner を設定し、作業を開始。\n- **complete_task**: `in_progress` → `completed`。タスクを完了済みにし、下流をアンロック。\n\n### 組み合わせて実行\n\n```python\n# 依存関係のあるタスクを作成\nschema = create_task(\"setup database schema\")\nendpoints = create_task(\"create API endpoints\", blockedBy=[schema.id])\ntests = create_task(\"write tests\", blockedBy=[endpoints.id])\ndocs = create_task(\"write docs\", blockedBy=[schema.id])\n\n# Agent が最初に実行可能なタスクを認識\nclaim_task(schema.id)       # ✓ Claimed（依存なし）\ncomplete_task(schema.id)    # ✓ Completed → endpoints, docs をアンロック\n\nclaim_task(endpoints.id)    # ✓ Claimed（schema 完了済み）\ncomplete_task(endpoints.id) # ✓ Completed → tests をアンロック\n\nclaim_task(docs.id)         # ✓ Claimed（schema 完了済み）\ncomplete_task(docs.id)      # ✓ Completed\n\nclaim_task(tests.id)        # ✓ Claimed（endpoints 完了済み）\ncomplete_task(tests.id)     # ✓ Completed\n```\n\n各 `create_task` が JSON ファイルを書き込み、各 `claim_task` / `complete_task` がファイルを更新。セッションをまたいでも `.tasks/` ディレクトリが残り、Agent はファイルを読んで進捗を復旧。\n\n---\n\n## s11 からの変更\n\n| コンポーネント | 変更前 (s11) | 変更後 (s12) |\n|--------------|------------|------------|\n| タスク管理 | なし | Task dataclass + 5 ツール |\n| 新規型 | — | Task（id, subject, description, status, owner, blockedBy） |\n| ストレージ | 永続化なし | `.tasks/{id}.json` セッション横断 |\n| 依存関係 | なし | `blockedBy` グラフ + `can_start` チェック |\n| ツール | bash, read_file, write_file (3) | + create_task, list_tasks, get_task, claim_task, complete_task (8) |\n| ライフサイクル | — | pending → in_progress → completed（release ロールバックなし） |\n\n---\n\n## 試してみる\n\n```sh\ncd learn-claude-code\npython s12_task_system/code.py\n```\n\n以下のプロンプトを試してください：\n\n1. `Create tasks: setup database schema, create API endpoints (depends on schema), write tests (depends on endpoints), write docs (depends on schema)`\n2. `List all tasks and their statuses`\n3. `Claim the first unblocked task and complete it`\n4. `List tasks again — which ones are now unblocked?`\n\n観察ポイント：`.tasks/` ディレクトリに JSON ファイルが生成されているか？タスク完了後、ブロックされていたタスクがアンロックされているか？\n\n---\n\n## 次の章\n\nタスクグラフができた。しかし、一部のタスクは長時間かかる — 全テスト実行やサーバーデプロイなど。Agent は LLM をトークン課金で呼び出しており、遅い操作を待つ余裕はない。\n\ns13 Background Tasks → 遅い操作はバックグラウンドへ。Agent は他のタスクの処理を続け、バックグラウンドの完了を通知で受け取る。\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s13",
    "locale": "en",
    "title": "s13: Background Tasks — Slow Operations Go to the Background",
    "content": "# s13: Background Tasks — Slow Operations Go to the Background\n\ns01 → ... → s11 → s12 → `s13` → [s14](/en/s14) → s15 → ... → s20 → s21\n\n> *\"Slow operations go to the background, agent continues processing\"* — Background threads run commands, inject notifications when done.\n>\n> **Harness Layer**: Background — Async execution, doesn't block the main loop.\n\n---\n\n## The Problem\n\nEver used a washing machine? Throw clothes in, press start, then go do other things — cook, reply to messages, read papers. 30 minutes later the machine beeps: done. You don't stand there waiting for 30 minutes.\n\nThe agent's bash tool is the same. `pip install torch` takes 10 minutes, `npm run build` takes 3 minutes. While these commands run, the agent waits for bash to return, unable to use that time to process other tasks.\n\nReading files is milliseconds, no wait. `git status` returns in under a second, no wait. But `npm install`? Minutes. The agent waits 10 minutes doing nothing, and LLM calls are billed by token — idle time is waste.\n\n---\n\n## The Solution\n\n![Background Tasks Overview](/course-assets/s13_background_tasks/background-tasks-overview.en.svg)\n\nThis chapter sends slow operations to background threads so the agent can keep running the loop. When a task finishes, its result is injected as a notification.\n\nSync vs Background:\n\n| | Sync (s12) | Background (s13) |\n|---|---|---|\n| Slow operations | Agent waits | Background thread executes |\n| Agent idle | Yes | No, continues processing |\n| Result | Immediate return | Notification injected next turn |\n| Decision criteria | — | `run_in_background` param (model explicit request), heuristic fallback |\n\n---\n\n## How It Works\n\n### should_run_background: Explicit Request First, Heuristic Fallback\n\nThe model explicitly requests background execution via the bash tool's `run_in_background` parameter. If the model does not specify it, keyword heuristics decide:\n\n```python\ndef is_slow_operation(tool_name: str, tool_input: dict) -> bool:\n    \"\"\"Fallback heuristic: commands likely to take > 30s.\"\"\"\n    if tool_name != \"bash\":\n        return False\n    cmd = tool_input.get(\"command\", \"\").lower()\n    slow_keywords = [\"install\", \"build\", \"test\", \"deploy\", \"compile\",\n                     \"docker build\", \"pip install\", \"npm install\",\n                     \"cargo build\", \"pytest\", \"make\"]\n    return any(kw in cmd for kw in slow_keywords)\n\ndef should_run_background(tool_name: str, tool_input: dict) -> bool:\n    \"\"\"Model explicit request takes priority; fallback to heuristic.\"\"\"\n    if tool_input.get(\"run_in_background\"):\n        return True\n    return is_slow_operation(tool_name, tool_input)\n```\n\n### start_background_task: Background Execution and Lifecycle\n\nWraps the tool call in a worker function, dispatches to a daemon thread. Each background task gets a unique ID, with state tracked in the `background_tasks` dict:\n\n```python\n_bg_counter = 0\nbackground_tasks: dict[str, dict] = {}   # bg_id → {tool_use_id, command, status}\nbackground_results: dict[str, str] = {}   # bg_id → output\nbackground_lock = threading.Lock()\n\ndef start_background_task(block) -> str:\n    \"\"\"Run tool in a daemon thread. Returns background task ID.\"\"\"\n    global _bg_counter\n    _bg_counter += 1\n    bg_id = f\"bg_{_bg_counter:04d}\"\n\n    def worker():\n        result = execute_tool(block)\n        with background_lock:\n            background_tasks[bg_id][\"status\"] = \"completed\"\n            background_results[bg_id] = result\n\n    with background_lock:\n        background_tasks[bg_id] = {\n            \"tool_use_id\": block.id,\n            \"command\": block.input.get(\"command\", \"\"),\n            \"status\": \"running\",\n        }\n    thread = threading.Thread(target=worker, daemon=True)\n    thread.start()\n    return bg_id\n```\n\n`start_background_task()` returns `bg_id`. `daemon=True` ensures the thread exits with the agent process.\n\n### collect_background_results: Notification Collection\n\nWhen background tasks complete, results are collected and formatted as `<task_notification>` messages:\n\n```python\ndef collect_background_results() -> list[str]:\n    \"\"\"Collect completed results as task_notification messages.\"\"\"\n    with background_lock:\n        ready_ids = [bid for bid, task in background_tasks.items()\n                     if task[\"status\"] == \"completed\"]\n    notifications = []\n    for bg_id in ready_ids:\n        with background_lock:\n            task = background_tasks.pop(bg_id)\n            output = background_results.pop(bg_id, \"\")\n        notifications.append(\n            f\"<task_notification>\\n\"\n            f\"  <task_id>{bg_id}</task_id>\\n\"\n            f\"  <status>completed</status>\\n\"\n            f\"  <command>{task['command']}</command>\\n\"\n            f\"  <summary>{output[:200]}</summary>\\n\"\n            f\"</task_notification>\")\n    return notifications\n```\n\nNotifications don't reuse the original `tool_use_id`. The original tool call was already answered with a placeholder `tool_result`; background completion is an independent event, injected in `task_notification` format. This respects Messages API tool pairing: one `tool_use` gets exactly one `tool_result`.\n\n### Loop Integration\n\nIn the agent loop, tool execution splits into two paths. Notifications and results merge into a single user message:\n\n```python\nresults = []\nfor block in response.content:\n    if block.type != \"tool_use\":\n        continue\n    if should_run_background(block.name, block.input):\n        bg_id = start_background_task(block)\n        results.append({\"type\": \"tool_result\",\n            \"tool_use_id\": block.id,\n            \"content\": f\"[Background task {bg_id} started] \"\n                       f\"Result will be available when complete.\"})\n    else:\n        output = execute_tool(block)\n        results.append({\"type\": \"tool_result\",\n            \"tool_use_id\": block.id, \"content\": output})\n\n# Merge notifications and tool results into one user message\nuser_content = []\nbg_notifications = collect_background_results()\nif bg_notifications:\n    for notif in bg_notifications:\n        user_content.append({\"type\": \"text\", \"text\": notif})\nuser_content.extend(results)\nmessages.append({\"role\": \"user\", \"content\": user_content})\n```\n\nSlow operations get a placeholder tool_result with `bg_id`, so the LLM knows this command is still running and can do other things first. When background completes, the notification is injected as an independent text block alongside the current turn's tool_results in one user message.\n\n### Putting It Together\n\n```\nTurn 1:\n  LLM → bash \"npm install\" (run_in_background=true)\n  → start_background_task → bg_0001\n  → tool_result: \"[Background task bg_0001 started]...\"\n  → LLM: \"OK, I'll check later. Let me also read the config.\"\n\nTurn 2:\n  LLM → read_file \"package.json\" (fast, sync)\n  → tool_result: file content\n  → collect: bg_0001 done! inject <task_notification>\n  → LLM sees: config file + install notification in one message\n```\n\nThe agent didn't wait — while npm install ran in the background, it read the config file.\n\n---\n\n## Changes from s12\n\n| Component | Before (s12) | After (s13) |\n|-----------|-------------|-------------|\n| Execution model | All synchronous | Slow ops to background thread + notification injection |\n| bash schema | `command` | `command` + `run_in_background` |\n| New functions | — | `should_run_background`, `is_slow_operation`, `start_background_task`, `collect_background_results` |\n| New types | — | `background_tasks: dict`, `background_results: dict`, `background_lock: Lock` |\n| Notification format | — | `<task_notification>` (doesn't reuse tool_use_id) |\n| Loop behavior | Tools execute serially | Slow ops async, fast ops sync, notifications collected each turn |\n| Tools | 8 (s12) | 8 (unchanged, execution strategy changed) |\n\n---\n\n## Try It\n\n```sh\ncd learn-claude-code\npython s13_background_tasks/code.py\n```\n\nTry these prompts:\n\n1. `Run pip list in the background and find all Python files in this directory`\n2. `Run npm install (use run_in_background) and while waiting, read package.json`\n3. `Create a task to setup the project, then run pip list in the background`\n\nWhat to observe: Are slow operations dispatched to background? Is a `bg_id` returned? Are background notifications injected in `<task_notification>` format?\n\n---\n\n## What's Next\n\nBackground tasks solved \"slow operations don't block.\" But what if you want to do something on a schedule? Like \"run tests every morning at 9am\" or \"check server status every 5 minutes.\"\n\ns14 Cron Scheduler → Give the agent an alarm clock.\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s13",
    "locale": "zh",
    "title": "s13: Background Tasks — 慢操作放后台",
    "content": "# s13: Background Tasks — 慢操作放后台\n\ns01 → ... → s11 → s12 → `s13` → [s14](/zh/s14) → s15 → ... → s20 → s21\n\n> *\"慢操作丢后台, agent 继续处理\"* — 后台线程跑命令, 完成后注入通知。\n>\n> **Harness 层**: 后台 — 异步执行, 不阻塞主循环。\n\n---\n\n## 问题\n\n你用过洗衣机吗？把衣服扔进去，按下启动，然后去干别的——做饭、回消息、看论文。30 分钟后洗衣机\"滴滴滴\"提醒你：好了。你不会站在洗衣机前面干等 30 分钟。\n\nAgent 的 bash 工具也一样。`pip install torch` 要 10 分钟，`npm run build` 要 3 分钟。这些命令一跑，Agent 就在等 bash 工具返回，没法利用这段时间处理别的任务。\n\n读文件是毫秒级，不等。`git status` 一秒内返回，不等。但 `npm install`？分钟级。Agent 等 10 分钟什么都不做，而 LLM 按 token 计费，空转就是浪费。\n\n---\n\n## 解决方案\n\n![Background Tasks Overview](/course-assets/s13_background_tasks/background-tasks-overview.svg)\n\n本章把慢操作放入后台线程，Agent 继续运行循环；任务完成后，结果以通知形式注入对话。\n\n同步 vs 后台：\n\n| | 同步 (s12) | 后台 (s13) |\n|---|---|---|\n| 慢操作 | Agent 干等 | 后台线程执行 |\n| Agent 空闲 | 是 | 否，继续处理 |\n| 结果 | 立即返回 | 下轮注入通知 |\n| 判断标准 | — | `run_in_background` 参数（模型显式请求），启发式兜底 |\n\n---\n\n## 工作原理\n\n### should_run_background: 显式请求优先，启发式兜底\n\n模型通过 bash 工具的 `run_in_background` 参数显式请求后台执行。如果模型没有指定，则使用关键词启发式判断：\n\n```python\ndef is_slow_operation(tool_name: str, tool_input: dict) -> bool:\n    \"\"\"Fallback heuristic: commands likely to take > 30s.\"\"\"\n    if tool_name != \"bash\":\n        return False\n    cmd = tool_input.get(\"command\", \"\").lower()\n    slow_keywords = [\"install\", \"build\", \"test\", \"deploy\", \"compile\",\n                     \"docker build\", \"pip install\", \"npm install\",\n                     \"cargo build\", \"pytest\", \"make\"]\n    return any(kw in cmd for kw in slow_keywords)\n\ndef should_run_background(tool_name: str, tool_input: dict) -> bool:\n    \"\"\"Model explicit request takes priority; fallback to heuristic.\"\"\"\n    if tool_input.get(\"run_in_background\"):\n        return True\n    return is_slow_operation(tool_name, tool_input)\n```\n\n### start_background_task: 后台执行与生命周期\n\n把工具调用包装成 worker 函数，扔到 daemon 线程里执行。每个后台任务有唯一 ID，状态存在 `background_tasks` 字典里：\n\n```python\n_bg_counter = 0\nbackground_tasks: dict[str, dict] = {}   # bg_id → {tool_use_id, command, status}\nbackground_results: dict[str, str] = {}   # bg_id → output\nbackground_lock = threading.Lock()\n\ndef start_background_task(block) -> str:\n    \"\"\"Run tool in a daemon thread. Returns background task ID.\"\"\"\n    global _bg_counter\n    _bg_counter += 1\n    bg_id = f\"bg_{_bg_counter:04d}\"\n\n    def worker():\n        result = execute_tool(block)\n        with background_lock:\n            background_tasks[bg_id][\"status\"] = \"completed\"\n            background_results[bg_id] = result\n\n    with background_lock:\n        background_tasks[bg_id] = {\n            \"tool_use_id\": block.id,\n            \"command\": block.input.get(\"command\", \"\"),\n            \"status\": \"running\",\n        }\n    thread = threading.Thread(target=worker, daemon=True)\n    thread.start()\n    return bg_id\n```\n\n`start_background_task()` 返回 `bg_id`。`daemon=True` 确保 Agent 进程退出时线程一起退出。\n\n### collect_background_results: 通知收集\n\n后台任务完成后，收集结果并格式化为 `<task_notification>` 通知：\n\n```python\ndef collect_background_results() -> list[str]:\n    \"\"\"Collect completed results as task_notification messages.\"\"\"\n    with background_lock:\n        ready_ids = [bid for bid, task in background_tasks.items()\n                     if task[\"status\"] == \"completed\"]\n    notifications = []\n    for bg_id in ready_ids:\n        with background_lock:\n            task = background_tasks.pop(bg_id)\n            output = background_results.pop(bg_id, \"\")\n        notifications.append(\n            f\"<task_notification>\\n\"\n            f\"  <task_id>{bg_id}</task_id>\\n\"\n            f\"  <status>completed</status>\\n\"\n            f\"  <command>{task['command']}</command>\\n\"\n            f\"  <summary>{output[:200]}</summary>\\n\"\n            f\"</task_notification>\")\n    return notifications\n```\n\n通知不复用原始 `tool_use_id`。原始 tool call 已经用占位 `tool_result` 回复了，后台完成是独立事件，用 `task_notification` 格式注入。这符合 Messages API 的工具配对语义：一个 `tool_use` 只对应一个 `tool_result`。\n\n### 循环中的集成\n\nagent_loop 里，工具执行分两条路，通知和结果合并为一条 user 消息：\n\n```python\nresults = []\nfor block in response.content:\n    if block.type != \"tool_use\":\n        continue\n    if should_run_background(block.name, block.input):\n        bg_id = start_background_task(block)\n        results.append({\"type\": \"tool_result\",\n            \"tool_use_id\": block.id,\n            \"content\": f\"[Background task {bg_id} started] \"\n                       f\"Result will be available when complete.\"})\n    else:\n        output = execute_tool(block)\n        results.append({\"type\": \"tool_result\",\n            \"tool_use_id\": block.id, \"content\": output})\n\n# 通知和工具结果合入同一条 user 消息\nuser_content = []\nbg_notifications = collect_background_results()\nif bg_notifications:\n    for notif in bg_notifications:\n        user_content.append({\"type\": \"text\", \"text\": notif})\nuser_content.extend(results)\nmessages.append({\"role\": \"user\", \"content\": user_content})\n```\n\n慢操作先回一个带 `bg_id` 的占位 tool_result，LLM 知道这个命令还在跑，可以先做别的事。后台完成后，通知作为独立 text block 和当前轮的 tool_result 一起组成 user 消息。\n\n### 合起来跑\n\n```\nTurn 1:\n  LLM → bash \"npm install\" (run_in_background=true)\n  → start_background_task → bg_0001\n  → tool_result: \"[Background task bg_0001 started]...\"\n  → LLM: \"OK, I'll check later. Let me also read the config.\"\n\nTurn 2:\n  LLM → read_file \"package.json\" (fast, sync)\n  → tool_result: file content\n  → collect: bg_0001 done! inject <task_notification>\n  → LLM sees: config file + install notification in one message\n```\n\nAgent 没干等，npm install 跑后台的时候，它去读了配置文件。\n\n---\n\n## 相对 s12 的变更\n\n| 组件 | 之前 (s12) | 之后 (s13) |\n|------|-----------|-----------|\n| 执行模型 | 全部同步 | 慢操作后台线程 + 通知注入 |\n| bash schema | `command` | `command` + `run_in_background` |\n| 新函数 | — | `should_run_background`, `is_slow_operation`, `start_background_task`, `collect_background_results` |\n| 新类型 | — | `background_tasks: dict`, `background_results: dict`, `background_lock: Lock` |\n| 通知格式 | — | `<task_notification>`（不复用 tool_use_id） |\n| 循环行为 | 工具串行执行 | 慢操作异步，快操作同步，通知每轮收集 |\n| 工具 | 8 (s12) | 8（不变，执行策略变了） |\n\n---\n\n## 试一下\n\n```sh\ncd learn-claude-code\npython s13_background_tasks/code.py\n```\n\n试试这些 prompt：\n\n1. `Run pip list in the background and find all Python files in this directory`\n2. `Run npm install (use run_in_background) and while waiting, read package.json`\n3. `Create a task to setup the project, then run pip list in the background`\n\n观察重点：慢操作有没有被送到后台？`bg_id` 是否返回？后台通知有没有以 `<task_notification>` 格式注入？\n\n---\n\n## 接下来\n\n后台任务解决了\"慢操作不阻塞\"。但如果想定时做某件事呢？比如\"每天早上 9 点跑测试\"、\"每 5 分钟检查一次服务器状态\"。\n\ns14 Cron Scheduler → 给 Agent 装一个闹钟。\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s13",
    "locale": "ja",
    "title": "s13: Background Tasks — 遅い操作はバックグラウンドへ",
    "content": "# s13: Background Tasks — 遅い操作はバックグラウンドへ\n\ns01 → ... → s11 → s12 → `s13` → [s14](/ja/s14) → s15 → ... → s20 → s21\n\n> *\"遅い操作はバックグラウンドへ、agent は処理を継続\"* — バックグラウンドスレッドでコマンドを実行、完了時に通知を注入。\n>\n> **Harness 層**: バックグラウンド — 非同期実行、メインループをブロックしない。\n\n---\n\n## 課題\n\n洗濯機を使ったことがあるか？衣類を入れ、スタートを押し、他のことをする——料理、メッセージ返信、論文読み。30 分後に洗濯機が「ピッピッ」と知らせる：完了。30 分間立って待つ人はいない。\n\nAgent の bash ツールも同じ。`pip install torch` は 10 分、`npm run build` は 3 分かかる。これらのコマンドが実行中、Agent は bash の戻りを待ち、その時間を他のタスクの処理に使えない。\n\nファイル読み込みはミリ秒、待たない。`git status` は 1 秒以内に戻る、待たない。しかし `npm install` は？分単位。Agent は 10 分間何もせず待ち、LLM 呼び出しはトークン課金、アイドル時間は無駄。\n\n---\n\n## ソリューション\n\n![Background Tasks Overview](/course-assets/s13_background_tasks/background-tasks-overview.ja.svg)\n\nこの章では、時間のかかる操作をバックグラウンドスレッドに送り、Agent はループを続行する。タスクが完了すると、結果が通知として会話に注入される。\n\n同期 vs バックグラウンド：\n\n| | 同期 (s12) | バックグラウンド (s13) |\n|---|---|---|\n| 遅い操作 | Agent が待機 | バックグラウンドスレッドで実行 |\n| Agent アイドル | はい | いいえ、処理を継続 |\n| 結果 | 即時返却 | 次ターンで通知を注入 |\n| 判断基準 | — | `run_in_background` パラメータ（モデル明示的リクエスト）、ヒューリスティックフォールバック |\n\n---\n\n## 仕組み\n\n### should_run_background: 明示的リクエスト優先、ヒューリスティックフォールバック\n\nモデルは bash ツールの `run_in_background` パラメータで明示的にバックグラウンド実行をリクエストする。指定がない場合は、キーワードヒューリスティックで判断する：\n\n```python\ndef is_slow_operation(tool_name: str, tool_input: dict) -> bool:\n    \"\"\"Fallback heuristic: commands likely to take > 30s.\"\"\"\n    if tool_name != \"bash\":\n        return False\n    cmd = tool_input.get(\"command\", \"\").lower()\n    slow_keywords = [\"install\", \"build\", \"test\", \"deploy\", \"compile\",\n                     \"docker build\", \"pip install\", \"npm install\",\n                     \"cargo build\", \"pytest\", \"make\"]\n    return any(kw in cmd for kw in slow_keywords)\n\ndef should_run_background(tool_name: str, tool_input: dict) -> bool:\n    \"\"\"Model explicit request takes priority; fallback to heuristic.\"\"\"\n    if tool_input.get(\"run_in_background\"):\n        return True\n    return is_slow_operation(tool_name, tool_input)\n```\n\n### start_background_task: バックグラウンド実行とライフサイクル\n\nツール呼び出しをワーカー関数にラップし、daemon スレッドにディスパッチ。各バックグラウンドタスクは一意 ID を持ち、`background_tasks` 辞書で状態を追跡：\n\n```python\n_bg_counter = 0\nbackground_tasks: dict[str, dict] = {}   # bg_id → {tool_use_id, command, status}\nbackground_results: dict[str, str] = {}   # bg_id → output\nbackground_lock = threading.Lock()\n\ndef start_background_task(block) -> str:\n    \"\"\"Run tool in a daemon thread. Returns background task ID.\"\"\"\n    global _bg_counter\n    _bg_counter += 1\n    bg_id = f\"bg_{_bg_counter:04d}\"\n\n    def worker():\n        result = execute_tool(block)\n        with background_lock:\n            background_tasks[bg_id][\"status\"] = \"completed\"\n            background_results[bg_id] = result\n\n    with background_lock:\n        background_tasks[bg_id] = {\n            \"tool_use_id\": block.id,\n            \"command\": block.input.get(\"command\", \"\"),\n            \"status\": \"running\",\n        }\n    thread = threading.Thread(target=worker, daemon=True)\n    thread.start()\n    return bg_id\n```\n\n`start_background_task()` は `bg_id` を返す。`daemon=True` により、Agent プロセスの終了時にスレッドも終了する。\n\n### collect_background_results: 通知収集\n\nバックグラウンドタスク完了時、結果を収集して `<task_notification>` メッセージとしてフォーマット：\n\n```python\ndef collect_background_results() -> list[str]:\n    \"\"\"Collect completed results as task_notification messages.\"\"\"\n    with background_lock:\n        ready_ids = [bid for bid, task in background_tasks.items()\n                     if task[\"status\"] == \"completed\"]\n    notifications = []\n    for bg_id in ready_ids:\n        with background_lock:\n            task = background_tasks.pop(bg_id)\n            output = background_results.pop(bg_id, \"\")\n        notifications.append(\n            f\"<task_notification>\\n\"\n            f\"  <task_id>{bg_id}</task_id>\\n\"\n            f\"  <status>completed</status>\\n\"\n            f\"  <command>{task['command']}</command>\\n\"\n            f\"  <summary>{output[:200]}</summary>\\n\"\n            f\"</task_notification>\")\n    return notifications\n```\n\n通知は元の `tool_use_id` を再利用しない。元のツール呼び出しはプレースホルダー `tool_result` で応答済み。バックグラウンド完了は独立したイベントで、`task_notification` 形式で注入する。これは Messages API のツールペアリングに従う：1 つの `tool_use` に対して正確に 1 つの `tool_result`。\n\n### ループ統合\n\nagent_loop でツール実行は 2 つのパスに分かれる。通知と結果は 1 つの user メッセージに統合：\n\n```python\nresults = []\nfor block in response.content:\n    if block.type != \"tool_use\":\n        continue\n    if should_run_background(block.name, block.input):\n        bg_id = start_background_task(block)\n        results.append({\"type\": \"tool_result\",\n            \"tool_use_id\": block.id,\n            \"content\": f\"[Background task {bg_id} started] \"\n                       f\"Result will be available when complete.\"})\n    else:\n        output = execute_tool(block)\n        results.append({\"type\": \"tool_result\",\n            \"tool_use_id\": block.id, \"content\": output})\n\n# 通知とツール結果を 1 つの user メッセージに統合\nuser_content = []\nbg_notifications = collect_background_results()\nif bg_notifications:\n    for notif in bg_notifications:\n        user_content.append({\"type\": \"text\", \"text\": notif})\nuser_content.extend(results)\nmessages.append({\"role\": \"user\", \"content\": user_content})\n```\n\n遅い操作は `bg_id` 付きプレースホルダー tool_result を返し、LLM はコマンドがまだ実行中だと知り、先に他のことをできる。バックグラウンド完了時、通知は独立した text block として現在のターンの tool_result と一緒に 1 つの user メッセージを構成する。\n\n### 組み合わせて実行\n\n```\nTurn 1:\n  LLM → bash \"npm install\" (run_in_background=true)\n  → start_background_task → bg_0001\n  → tool_result: \"[Background task bg_0001 started]...\"\n  → LLM: \"OK, I'll check later. Let me also read the config.\"\n\nTurn 2:\n  LLM → read_file \"package.json\" (fast, sync)\n  → tool_result: file content\n  → collect: bg_0001 done! inject <task_notification>\n  → LLM sees: config file + install notification in one message\n```\n\nAgent は待たなかった。npm install がバックグラウンドで実行中に、設定ファイルを読んだ。\n\n---\n\n## s12 からの変更\n\n| コンポーネント | 変更前 (s12) | 変更後 (s13) |\n|--------------|------------|------------|\n| 実行モデル | すべて同期 | 遅い操作はバックグラウンドスレッド + 通知注入 |\n| bash スキーマ | `command` | `command` + `run_in_background` |\n| 新規関数 | — | `should_run_background`, `is_slow_operation`, `start_background_task`, `collect_background_results` |\n| 新規型 | — | `background_tasks: dict`, `background_results: dict`, `background_lock: Lock` |\n| 通知形式 | — | `<task_notification>`（tool_use_id を再利用しない） |\n| ループ動作 | ツール直列実行 | 遅い操作は非同期、速い操作は同期、通知は毎ターン収集 |\n| ツール | 8 (s12) | 8（変更なし、実行戦略が変更） |\n\n---\n\n## 試してみる\n\n```sh\ncd learn-claude-code\npython s13_background_tasks/code.py\n```\n\n以下のプロンプトを試してください：\n\n1. `Run pip list in the background and find all Python files in this directory`\n2. `Run npm install (use run_in_background) and while waiting, read package.json`\n3. `Create a task to setup the project, then run pip list in the background`\n\n観察ポイント：遅い操作はバックグラウンドにディスパッチされているか？`bg_id` は返されているか？バックグラウンド通知は `<task_notification>` 形式で注入されているか？\n\n---\n\n## 次の章\n\nバックグラウンドタスクは「遅い操作がブロックしない」を解決した。しかし、定期的に何かをしたい場合は？例えば「毎朝 9 時にテストを実行」「5 分ごとにサーバーステータスを確認」。\n\ns14 Cron Scheduler → Agent にアラームクロックを付ける。\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s14",
    "locale": "en",
    "title": "s14: Cron Scheduler — Producing Work on a Schedule",
    "content": "# s14: Cron Scheduler — Producing Work on a Schedule\n\ns01 → ... → s12 → s13 → `s14` → [s15](/en/s15) → s16 → ... → s20 → s21\n> *\"Produce work on a schedule, decouple scheduling from execution\"* — Cron scheduling, durable or session-level.\n>\n> **Harness Layer**: Scheduling — Independent thread checks time, queue delivers triggers.\n\n---\n\n## The Problem\n\nAn alarm clock doesn't need you to watch it. You set 7:00, it rings at 7:00 — you could be sleeping, showering, cooking, it rings regardless.\n\ns13 lets the agent run slow operations in the background, but every operation is still triggered manually. You say something, the agent acts. \"Run tests every morning at 9am\", \"Check CI status every 30 minutes\" — these recurring tasks shouldn't need a human to push them each time.\n\n---\n\n## The Solution\n\n![Cron Scheduler Overview](/course-assets/s14_cron_scheduler/cron-scheduler-overview.en.svg)\n\nThis chapter adds an independent cron scheduler thread: it checks once per second, writes due jobs to `cron_queue`, and a queue processor delivers them when the agent is idle.\n\nManual vs Scheduled:\n\n| | Manual (s13) | Scheduled (s14) |\n|---|---|---|\n| Triggered by | User input | Scheduler thread |\n| Trigger timing | Anytime | Specified by cron expression |\n| Human involvement | Yes | No (scheduler auto-enqueues, idle agent auto-delivers) |\n| Persistence | — | Durable survives restart |\n\n---\n\n## How It Works\n\n### Four-Layer Model\n\nCron scheduling has four layers:\n\n1. **Scheduler**: daemon thread, polls every second, checks if it's time\n2. **Queue**: `cron_queue`, scheduler writes fired jobs\n3. **Queue Processor**: sees non-empty queue and idle agent, starts one agent_loop turn\n4. **Consumer**: agent_loop consumes queue and injects into messages\n\n### CronJob: Data Structure\n\nEach cron task is a `CronJob` object:\n\n```python\n@dataclass\nclass CronJob:\n    id: str\n    cron: str        # \"0 9 * * *\" (5-field cron expression)\n    prompt: str      # Message injected to the agent when fired\n    recurring: bool  # True=recurring, False=one-shot\n    durable: bool    # True=write to disk, survives sessions\n```\n\nCron expression, 5 fields, used by Unix for 50 years:\n\n```\nmin  hour  dom  month  dow\n *    *     *     *     *      Every minute\n 0    9     *     *     *      Every day at 9:00\n*/5    *     *     *     *      Every 5 minutes\n 0    9     *     *    1-5     Weekdays at 9:00\n```\n\nSupports `*`, `*/N`, `N`, `N-M`, `N,M,...`.\n\n### cron_matches: 5-Field Matching\n\nStandard cron semantics: minute, hour, month must all match; day-of-month (DOM) and day-of-week (DOW) use OR when both are constrained:\n\n```python\ndef cron_matches(cron_expr: str, dt: datetime) -> bool:\n    fields = cron_expr.strip().split()\n    if len(fields) != 5:\n        return False\n    minute, hour, dom, month, dow = fields\n    dow_val = (dt.weekday() + 1) % 7  # Python Monday=0 → cron Sunday=0\n\n    m = _cron_field_matches(minute, dt.minute)\n    h = _cron_field_matches(hour, dt.hour)\n    dom_ok = _cron_field_matches(dom, dt.day)\n    month_ok = _cron_field_matches(month, dt.month)\n    dow_ok = _cron_field_matches(dow, dow_val)\n\n    if not (m and h and month_ok):\n        return False\n    # DOM and DOW: both constrained → either matching is enough (OR)\n    dom_unconstrained = dom == \"*\"\n    dow_unconstrained = dow == \"*\"\n    if dom_unconstrained and dow_unconstrained:\n        return True\n    if dom_unconstrained:\n        return dow_ok\n    if dow_unconstrained:\n        return dom_ok\n    return dom_ok or dow_ok\n```\n\n### Independent Scheduler Thread: 1-Second Polling\n\nThe scheduler runs in an independent daemon thread, not dependent on whether agent_loop is executing. Individual job errors don't kill the entire thread:\n\n```python\ndef cron_scheduler_loop():\n    while True:\n        time.sleep(1)\n        now = datetime.now()\n        minute_marker = now.strftime(\"%Y-%m-%d %H:%M\")\n        with cron_lock:\n            for job in list(scheduled_jobs.values()):\n                try:\n                    if cron_matches(job.cron, now):\n                        if _last_fired.get(job.id) != minute_marker:\n                            cron_queue.append(job)\n                            _last_fired[job.id] = minute_marker\n                        if not job.recurring:\n                            scheduled_jobs.pop(job.id, None)\n                            if job.durable:\n                                save_durable_jobs()\n                except Exception as e:\n                    print(f\"[cron error] {job.id}: {e}\")\n```\n\nKey design:\n- **Independent of agent_loop**: scheduler checks time in background even when agent_loop isn't running\n- **Date-aware minute_marker**: uses `\"YYYY-MM-DD HH:MM\"` to prevent same-minute double-fire while not skipping on the next day\n- **Per-job try/except**: one bad job doesn't crash the scheduler thread\n- **One-shot jobs**: auto-removed from scheduled_jobs after firing\n\n### Queue Processor + agent_loop: Delivery\n\nThe queue processor does not check time. It only starts a turn when queued work exists and the agent is idle:\n\n```python\ndef queue_processor_loop():\n    while True:\n        time.sleep(0.2)\n        if not has_cron_queue():\n            continue\n        if not agent_lock.acquire(blocking=False):\n            continue\n        try:\n            if has_cron_queue():\n                run_agent_turn_locked()\n        finally:\n            agent_lock.release()\n```\n\nagent_loop also doesn't check time. It only takes fired tasks from `cron_queue` and injects them into messages:\n\n```python\nfired = consume_cron_queue()\nfor job in fired:\n    messages.append({\"role\": \"user\",\n                     \"content\": f\"[Scheduled] {job.prompt}\"})\n```\n\nProducer (scheduler thread), deliverer (queue processor), and consumer (agent_loop) are decoupled via `cron_queue`, `cron_lock`, and `agent_lock`.\n\n### Validation: Prevent Bad Cron from Killing the Scheduler\n\n`schedule_job` validates the cron expression before registering, returning an error for invalid input:\n\n```python\ndef schedule_job(cron, prompt, recurring=True, durable=True):\n    err = validate_cron(cron)\n    if err:\n        return err\n    # ... register job\n```\n\nLoading durable jobs from disk also skips invalid expressions, preventing a single bad task from breaking startup.\n\n### Durable vs Session-only\n\n- **Durable**: Task definition written to `.scheduled_tasks.json`. Loaded on agent restart.\n- **Session-only**: In-memory only. Gone when the agent closes.\n\n> **Important caveat**: The cron scheduler must run inside the agent process. Process exits, scheduler stops. Durable only means the task definition survives restarts — next time the agent starts, the scheduler discovers \"it should fire\" and fires. If you need \"run even when the app is closed\", use system crontab or systemd timer.\n\n### Putting It Together\n\n```\n1. On startup:\n   load_durable_jobs() → restore durable tasks from .scheduled_tasks.json\n   Thread(cron_scheduler_loop, daemon=True).start() → scheduler begins polling\n   Thread(queue_processor_loop, daemon=True).start() → processor waits to deliver\n\n2. Register a task:\n   schedule_cron(cron=\"*/2 * * * *\", prompt=\"run date\", durable=True)\n   → CronJob written to scheduled_jobs + .scheduled_tasks.json\n\n3. Every 2 minutes:\n   Scheduler checks → cron_matches returns True → cron_queue.append(job)\n   → queue processor sees idle agent → agent_loop consume_cron_queue\n   → injects \"[Scheduled] run date\"\n   → LLM receives message, runs date command\n\n4. Process shutdown:\n   Scheduler thread stops (daemon=True)\n   .scheduled_tasks.json stays on disk\n   Next startup → load_durable_jobs → tasks restored\n```\n\n---\n\n## Changes from s13\n\n| Component | Before (s13) | After (s14) |\n|-----------|-------------|-------------|\n| Trigger method | User manual trigger | Scheduler thread auto-enqueues |\n| New types | — | CronJob dataclass (id, cron, prompt, recurring, durable) |\n| New functions | — | cron_matches, validate_cron, schedule_job, cancel_job, cron_scheduler_loop, queue_processor_loop |\n| New storage | — | .scheduled_tasks.json (durable) + memory (session-only) |\n| Threads | Background execution thread | + Scheduler thread (daemon, 1s polling) + queue processor thread |\n| Queue | background_results | + cron_queue (scheduler writes, queue processor delivers, agent_loop consumes) |\n| Tools | 8 (s12/s13) | + schedule_cron, list_crons, cancel_cron (11) |\n\n---\n\n## Try It\n\n```sh\ncd learn-claude-code\npython s14_cron_scheduler/code.py\n```\n\nTry these prompts:\n\n1. `Schedule a task to print the current date every 2 minutes`\n2. `List all cron jobs`\n3. `Create a one-shot reminder in 1 minute to check the build status`\n4. `Cancel the recurring job and verify with list_crons`\n\nWhat to observe: Is the scheduler thread running independently? Do cron tasks fire at the correct time? Without a new prompt, do you see `[queue processor]` and automatic execution? Is the durable job written to `.scheduled_tasks.json`?\n\n---\n\n## What's Next\n\nOne agent can do a lot now: plan, compress, background, schedule. But some tasks are too big for one agent.\n\n\"Refactor the entire backend\" — overhaul auth, database layer, API routes, and tests. One agent's attention is limited. This needs a team.\n\ns15 Agent Teams → One agent isn't enough, form a team. Persistent teammates + async inboxes.\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s14",
    "locale": "zh",
    "title": "s14: Cron Scheduler — 按时间表生产工作",
    "content": "# s14: Cron Scheduler — 按时间表生产工作\n\ns01 → ... → s12 → s13 → `s14` → [s15](/zh/s15) → s16 → ... → s20 → s21\n> *\"按时间表生产工作, 调度与执行解耦\"* — cron 调度, 持久化或会话级。\n>\n> **Harness 层**: 调度 — 独立线程判断时间, 队列传递触发。\n\n---\n\n## 问题\n\n闹钟不需要你盯着它才会响。你设好 7:00，到点它自己响，你在睡觉、在洗澡、在做饭，它都照响不误。\n\ns13 让 Agent 能后台执行慢操作，但所有操作仍然是你手动触发的。你说一句，Agent 动一下。\"每天早上 9 点跑测试\"、\"每 30 分钟检查 CI 状态\"，这些周期性任务不该需要人每次来推。\n\n---\n\n## 解决方案\n\n![Cron Scheduler Overview](/course-assets/s14_cron_scheduler/cron-scheduler-overview.svg)\n\n本章新增独立的 cron 调度线程：每秒检查一次，把到期任务写入 `cron_queue`，再由 queue processor 在 Agent 空闲时自动交付。\n\n手动 vs 定时：\n\n| | 手动触发 (s13) | 定时触发 (s14) |\n|---|---|---|\n| 触发者 | 用户输入 | 调度线程 |\n| 触发时机 | 随时 | cron 表达式指定 |\n| 需要人参与 | 是 | 否（调度器自动入队，空闲时自动交付） |\n| 持久性 | — | durable 跨重启 |\n\n---\n\n## 工作原理\n\n### 四层模型\n\nCron 调度分四层：\n\n1. **Scheduler**：daemon 线程，每秒轮询，判断时间到了没有\n2. **Queue**：`cron_queue`，调度线程写入已触发任务\n3. **Queue Processor**：发现队列非空且 Agent 空闲，启动一轮 agent_loop\n4. **Consumer**：agent_loop 从队列消费，注入到 messages\n\n### CronJob: 数据结构\n\n每个 cron 任务是一个 `CronJob` 对象：\n\n```python\n@dataclass\nclass CronJob:\n    id: str\n    cron: str        # \"0 9 * * *\" (五段式 cron 表达式)\n    prompt: str      # 触发时注入给 Agent 的消息\n    recurring: bool  # True=周期性，False=一次性\n    durable: bool    # True=写磁盘，跨会话保留\n```\n\nCron 表达式，五段式，Unix 用了 50 年：\n\n```\n分钟  小时  日  月  星期\n  *    *   *   *   *      每分钟\n  0    9   *   *   *      每天早上 9:00\n */5    *   *   *   *      每 5 分钟\n  0    9   *   *  1-5     工作日早上 9:00\n```\n\n支持 `*`、`*/N`、`N`、`N-M`、`N,M,...`。\n\n### cron_matches: 五段式匹配\n\n标准 cron 语义：分钟、小时、月必须全部匹配；日（DOM）和星期（DOW）同时被约束时任一匹配即可（OR）：\n\n```python\ndef cron_matches(cron_expr: str, dt: datetime) -> bool:\n    fields = cron_expr.strip().split()\n    if len(fields) != 5:\n        return False\n    minute, hour, dom, month, dow = fields\n    dow_val = (dt.weekday() + 1) % 7  # Python Monday=0 → cron Sunday=0\n\n    m = _cron_field_matches(minute, dt.minute)\n    h = _cron_field_matches(hour, dt.hour)\n    dom_ok = _cron_field_matches(dom, dt.day)\n    month_ok = _cron_field_matches(month, dt.month)\n    dow_ok = _cron_field_matches(dow, dow_val)\n\n    if not (m and h and month_ok):\n        return False\n    # DOM and DOW: both constrained → either matching is enough (OR)\n    dom_unconstrained = dom == \"*\"\n    dow_unconstrained = dow == \"*\"\n    if dom_unconstrained and dow_unconstrained:\n        return True\n    if dom_unconstrained:\n        return dow_ok\n    if dow_unconstrained:\n        return dom_ok\n    return dom_ok or dow_ok\n```\n\n### 独立调度线程: 每秒轮询\n\n调度器跑在独立的 daemon 线程里，不依赖 agent_loop 是否在执行。单个 job 异常不会杀掉整个线程：\n\n```python\ndef cron_scheduler_loop():\n    while True:\n        time.sleep(1)\n        now = datetime.now()\n        minute_marker = now.strftime(\"%Y-%m-%d %H:%M\")\n        with cron_lock:\n            for job in list(scheduled_jobs.values()):\n                try:\n                    if cron_matches(job.cron, now):\n                        if _last_fired.get(job.id) != minute_marker:\n                            cron_queue.append(job)\n                            _last_fired[job.id] = minute_marker\n                        if not job.recurring:\n                            scheduled_jobs.pop(job.id, None)\n                            if job.durable:\n                                save_durable_jobs()\n                except Exception as e:\n                    print(f\"[cron error] {job.id}: {e}\")\n```\n\n关键设计：\n- **独立于 agent_loop**：即使 agent_loop 没在跑，调度器也在后台检查时间\n- **date-aware minute_marker**：用 `\"YYYY-MM-DD HH:MM\"` 防止同一分钟重复触发，同时不会在第二天跳过\n- **单 job try/except**：一个坏 job 不会拖垮整个调度线程\n- **一次性任务**：触发后自动从 scheduled_jobs 里删除\n\n### Queue Processor + agent_loop: 交付端\n\nqueue processor 不检查时间，只负责在队列有任务且 Agent 空闲时拉起一轮执行：\n\n```python\ndef queue_processor_loop():\n    while True:\n        time.sleep(0.2)\n        if not has_cron_queue():\n            continue\n        if not agent_lock.acquire(blocking=False):\n            continue\n        try:\n            if has_cron_queue():\n                run_agent_turn_locked()\n        finally:\n            agent_lock.release()\n```\n\nagent_loop 也不负责检查时间，它只从 `cron_queue` 里拿已触发的任务，注入到 messages 里：\n\n```python\nfired = consume_cron_queue()\nfor job in fired:\n    messages.append({\"role\": \"user\",\n                     \"content\": f\"[Scheduled] {job.prompt}\"})\n```\n\n生产者（调度线程）、交付者（queue processor）和消费者（agent_loop）通过 `cron_queue`、`cron_lock`、`agent_lock` 解耦。\n\n### 校验：防止坏 cron 杀掉调度器\n\n`schedule_job` 在注册前校验 cron 表达式，非法的直接返回错误：\n\n```python\ndef schedule_job(cron, prompt, recurring=True, durable=True):\n    err = validate_cron(cron)\n    if err:\n        return err\n    # ... register job\n```\n\n从磁盘加载 durable job 时也会跳过非法表达式，避免单个坏任务拖垮启动。\n\n### Durable vs Session-only\n\n- **Durable**：任务定义写进 `.scheduled_tasks.json`。Agent 重启后加载文件，恢复任务。\n- **Session-only**：只在内存里。Agent 关闭就没了。\n\n> **重要前提**：cron 调度器必须在 Agent 进程内跑。进程关闭，调度也停。Durable 只意味着任务定义跨重启保留，下次 Agent 启动时调度器才会发现\"该触发了\"并触发。如果需要\"即使应用关闭也能定时跑\"，请用系统 crontab 或 systemd timer。\n\n### 合起来跑\n\n```\n1. 启动时：\n   load_durable_jobs() → 从 .scheduled_tasks.json 恢复持久化任务\n   Thread(cron_scheduler_loop, daemon=True).start() → 调度线程开始轮询\n   Thread(queue_processor_loop, daemon=True).start() → 队列处理器等待交付\n\n2. 注册任务：\n   schedule_cron(cron=\"*/2 * * * *\", prompt=\"run date\", durable=True)\n   → CronJob 写入 scheduled_jobs + .scheduled_tasks.json\n\n3. 每 2 分钟：\n   调度线程检查 → cron_matches 返回 True → cron_queue.append(job)\n   → queue processor 发现 Agent 空闲 → agent_loop consume_cron_queue\n   → 注入 \"[Scheduled] run date\"\n   → LLM 收到消息，执行 date 命令\n\n4. 关闭进程：\n   调度线程跟着停（daemon=True）\n   .scheduled_tasks.json 还在磁盘上\n   下次启动 → load_durable_jobs → 任务恢复\n```\n\n---\n\n## 相对 s13 的变更\n\n| 组件 | 之前 (s13) | 之后 (s14) |\n|------|-----------|-----------|\n| 触发方式 | 用户手动触发 | 调度线程自动入队 |\n| 新类型 | — | CronJob dataclass (id, cron, prompt, recurring, durable) |\n| 新函数 | — | cron_matches, validate_cron, schedule_job, cancel_job, cron_scheduler_loop, queue_processor_loop |\n| 新存储 | — | .scheduled_tasks.json (durable) + 内存 (session-only) |\n| 线程 | 后台执行线程 | + 调度线程 (daemon, 1s 轮询) + queue processor 线程 |\n| 队列 | background_results | + cron_queue (调度线程写, queue processor 交付, agent_loop 消费) |\n| 工具 | 8 (s12/s13) | + schedule_cron, list_crons, cancel_cron (11) |\n\n---\n\n## 试一下\n\n```sh\ncd learn-claude-code\npython s14_cron_scheduler/code.py\n```\n\n试试这些 prompt：\n\n1. `Schedule a task to print the current date every 2 minutes`\n2. `List all cron jobs`\n3. `Create a one-shot reminder in 1 minute to check the build status`\n4. `Cancel the recurring job and verify with list_crons`\n\n观察重点：调度线程是否在独立运行？cron 任务是否在正确的时间点触发？不输入新 prompt 时，是否也出现 `[queue processor]` 并自动执行？durable job 是否写入了 `.scheduled_tasks.json`？\n\n---\n\n## 接下来\n\n一个 Agent 能做很多事了，能计划、能压缩、能后台、能定时。但有些任务太大了，不是一个 Agent 能搞定的。\n\n\"重构整个后端\"，把认证模块、数据库层、API 路由、测试全部翻新。一个 Agent 的注意力是有限的，这需要一个团队。\n\ns15 Agent Teams → 一个 Agent 不够，组队吧。持久队友 + 异步收件箱。\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s14",
    "locale": "ja",
    "title": "s14: Cron Scheduler — スケジュールに従って作業を生産",
    "content": "# s14: Cron Scheduler — スケジュールに従って作業を生産\n\ns01 → ... → s12 → s13 → `s14` → [s15](/ja/s15) → s16 → ... → s20 → s21\n> *\"スケジュールに従って作業を生産、スケジューリングと実行を分離\"* — cron スケジューリング、永続またはセッションレベル。\n>\n> **Harness 層**: スケジューリング — 独立スレッドが時刻を判定、キューがトリガーを配信。\n\n---\n\n## 課題\n\n目覚まし時計はあなたが見ていないと鳴らないわけではない。7:00 にセットすれば、7:00 に鳴る。寝ていても、シャワーを浴びていても、料理をしていても、鳴る。\n\ns13 で Agent は遅い操作をバックグラウンドで実行できるようになった。しかし、すべての操作は手動でトリガーされる。一言言えば、Agent が動く。「毎朝 9 時にテストを実行」「30 分ごとに CI ステータスを確認」、これらの定期的なタスクに人が毎回押す必要はないはずだ。\n\n---\n\n## ソリューション\n\n![Cron Scheduler Overview](/course-assets/s14_cron_scheduler/cron-scheduler-overview.ja.svg)\n\nこの章では独立した cron スケジューラスレッドを追加する。1 秒ごとに確認し、期限に達したジョブを `cron_queue` に書き込み、queue processor が Agent のアイドル時に自動配信する。\n\n手動 vs スケジュール：\n\n| | 手動 (s13) | スケジュール (s14) |\n|---|---|---|\n| トリガー | ユーザー入力 | スケジューラスレッド |\n| トリガー時刻 | いつでも | cron 式で指定 |\n| 人の関与 | あり | なし（スケジューラが自動キュー投入、アイドル時に自動配信） |\n| 永続性 | — | durable は再起動後も保持 |\n\n---\n\n## 仕組み\n\n### 4 層モデル\n\ncron スケジューリングは 4 層に分かれる：\n\n1. **Scheduler**：daemon スレッド、1 秒ごとにポーリング、時刻が来たか判定\n2. **Queue**：`cron_queue`、スケジューラが発火済みタスクを書き込み\n3. **Queue Processor**：キューが空でなく Agent がアイドルなら、一回の agent_loop を開始\n4. **Consumer**：agent_loop がキューから消費、messages に注入\n\n### CronJob: データ構造\n\n各 cron タスクは `CronJob` オブジェクト：\n\n```python\n@dataclass\nclass CronJob:\n    id: str\n    cron: str        # \"0 9 * * *\"（5 フィールド cron 式）\n    prompt: str      # 発火時に Agent に注入するメッセージ\n    recurring: bool  # True=定期的、False=一回限り\n    durable: bool    # True=ディスク書き込み、セッション横断\n```\n\ncron 式、5 フィールド、Unix で 50 年使われている：\n\n```\n分  時  日  月  曜日\n *   *   *   *   *      毎分\n 0   9   *   *   *      毎日 9:00\n*/5   *   *   *   *      5 分ごと\n 0   9   *   *  1-5     平日 9:00\n```\n\n`*`、`*/N`、`N`、`N-M`、`N,M,...` をサポート。\n\n### cron_matches: 5 フィールドマッチング\n\n標準 cron セマンティクス：分、時、月はすべてマッチ必須。日（DOM）と曜日（DOW）が両方制約されている場合は、いずれかのマッチで十分（OR）：\n\n```python\ndef cron_matches(cron_expr: str, dt: datetime) -> bool:\n    fields = cron_expr.strip().split()\n    if len(fields) != 5:\n        return False\n    minute, hour, dom, month, dow = fields\n    dow_val = (dt.weekday() + 1) % 7  # Python Monday=0 → cron Sunday=0\n\n    m = _cron_field_matches(minute, dt.minute)\n    h = _cron_field_matches(hour, dt.hour)\n    dom_ok = _cron_field_matches(dom, dt.day)\n    month_ok = _cron_field_matches(month, dt.month)\n    dow_ok = _cron_field_matches(dow, dow_val)\n\n    if not (m and h and month_ok):\n        return False\n    # DOM and DOW: both constrained → either matching is enough (OR)\n    dom_unconstrained = dom == \"*\"\n    dow_unconstrained = dow == \"*\"\n    if dom_unconstrained and dow_unconstrained:\n        return True\n    if dom_unconstrained:\n        return dow_ok\n    if dow_unconstrained:\n        return dom_ok\n    return dom_ok or dow_ok\n```\n\n### 独立スケジューラスレッド：1 秒ポーリング\n\nスケジューラは独立した daemon スレッドで動作、agent_loop が実行中かどうかに依存しない。個々のジョブエラーはスレッド全体を殺さない：\n\n```python\ndef cron_scheduler_loop():\n    while True:\n        time.sleep(1)\n        now = datetime.now()\n        minute_marker = now.strftime(\"%Y-%m-%d %H:%M\")\n        with cron_lock:\n            for job in list(scheduled_jobs.values()):\n                try:\n                    if cron_matches(job.cron, now):\n                        if _last_fired.get(job.id) != minute_marker:\n                            cron_queue.append(job)\n                            _last_fired[job.id] = minute_marker\n                        if not job.recurring:\n                            scheduled_jobs.pop(job.id, None)\n                            if job.durable:\n                                save_durable_jobs()\n                except Exception as e:\n                    print(f\"[cron error] {job.id}: {e}\")\n```\n\n重要な設計：\n- **agent_loop から独立**：agent_loop が動いていなくても、スケジューラはバックグラウンドで時刻をチェック\n- **日付認識 minute_marker**：`\"YYYY-MM-DD HH:MM\"` を使用、同じ分の重複発火を防ぎつつ翌日のスキップも防止\n- **ジョブ単位の try/except**：一つの悪いジョブがスケジューラスレッド全体をクラッシュさせない\n- **一回限りジョブ**：発火後、scheduled_jobs から自動削除\n\n### Queue Processor + agent_loop: 配信側\n\nqueue processor は時刻をチェックしない。キューに作業があり、Agent がアイドルの時だけ一回の実行を開始する：\n\n```python\ndef queue_processor_loop():\n    while True:\n        time.sleep(0.2)\n        if not has_cron_queue():\n            continue\n        if not agent_lock.acquire(blocking=False):\n            continue\n        try:\n            if has_cron_queue():\n                run_agent_turn_locked()\n        finally:\n            agent_lock.release()\n```\n\nagent_loop も時刻をチェックしない。`cron_queue` から発火済みタスクを取り出し、messages に注入するだけ：\n\n```python\nfired = consume_cron_queue()\nfor job in fired:\n    messages.append({\"role\": \"user\",\n                     \"content\": f\"[Scheduled] {job.prompt}\"})\n```\n\n生産者（スケジューラスレッド）、配信者（queue processor）、消費者（agent_loop）は `cron_queue`、`cron_lock`、`agent_lock` で分離されている。\n\n### バリデーション：不正 cron がスケジューラを殺すのを防止\n\n`schedule_job` は登録前に cron 式をバリデーションし、不正な場合はエラーを返す：\n\n```python\ndef schedule_job(cron, prompt, recurring=True, durable=True):\n    err = validate_cron(cron)\n    if err:\n        return err\n    # ... ジョブ登録\n```\n\nディスクから durable ジョブを読み込む際も不正な式をスキップし、一つの悪いタスクが起動を妨げない。\n\n### Durable vs Session-only\n\n- **Durable**：タスク定義を `.scheduled_tasks.json` に書き込み。Agent 再起動後にファイルから復元。\n- **Session-only**：メモリ内のみ。Agent 終了で消失。\n\n> **重要な前提**：cron スケジューラは Agent プロセス内で実行される必要がある。プロセスが終了するとスケジューラも停止。Durable はタスク定義が再起動後も保持されることを意味するだけで、次回 Agent 起動時にスケジューラが「発火すべき」と判定して初めて発火する。「アプリケーションが閉じていても定期的に実行」が必要な場合は、システム crontab または systemd timer を使用。\n\n### 組み合わせて実行\n\n```\n1. 起動時：\n   load_durable_jobs() → .scheduled_tasks.json から永続タスクを復元\n   Thread(cron_scheduler_loop, daemon=True).start() → スケジューラスレッドがポーリング開始\n   Thread(queue_processor_loop, daemon=True).start() → processor が配信待機\n\n2. タスク登録：\n   schedule_cron(cron=\"*/2 * * * *\", prompt=\"run date\", durable=True)\n   → CronJob を scheduled_jobs + .scheduled_tasks.json に書き込み\n\n3. 2 分ごと：\n   スケジューラチェック → cron_matches が True → cron_queue.append(job)\n   → queue processor がアイドル状態を検知 → agent_loop consume_cron_queue\n   → \"[Scheduled] run date\" を注入\n   → LLM がメッセージを受信、date コマンドを実行\n\n4. プロセス終了：\n   スケジューラスレッドも停止（daemon=True）\n   .scheduled_tasks.json はディスクに残存\n   次回起動 → load_durable_jobs → タスク復元\n```\n\n---\n\n## s13 からの変更\n\n| コンポーネント | 変更前 (s13) | 変更後 (s14) |\n|--------------|------------|------------|\n| トリガー方式 | ユーザー手動トリガー | スケジューラスレッドが自動キュー投入 |\n| 新規型 | — | CronJob データクラス (id, cron, prompt, recurring, durable) |\n| 新規関数 | — | cron_matches, validate_cron, schedule_job, cancel_job, cron_scheduler_loop, queue_processor_loop |\n| 新規ストレージ | — | .scheduled_tasks.json (durable) + メモリ (session-only) |\n| スレッド | バックグラウンド実行スレッド | + スケジューラスレッド (daemon, 1s ポーリング) + queue processor スレッド |\n| キュー | background_results | + cron_queue（スケジューラ書き込み、queue processor 配信、agent_loop 消費） |\n| ツール | 8 (s12/s13) | + schedule_cron, list_crons, cancel_cron (11) |\n\n---\n\n## 試してみる\n\n```sh\ncd learn-claude-code\npython s14_cron_scheduler/code.py\n```\n\n以下のプロンプトを試してください：\n\n1. `Schedule a task to print the current date every 2 minutes`\n2. `List all cron jobs`\n3. `Create a one-shot reminder in 1 minute to check the build status`\n4. `Cancel the recurring job and verify with list_crons`\n\n観察ポイント：スケジューラスレッドが独立して動いているか？cron タスクが正しい時刻に発火しているか？新しい prompt を入力しなくても `[queue processor]` が出て自動実行されるか？durable ジョブが `.scheduled_tasks.json` に書き込まれているか？\n\n---\n\n## 次の章\n\n一つの Agent でできることは増えた。計画、圧縮、バックグラウンド、スケジューリング。しかし、一部のタスクは一つの Agent では大きすぎる。\n\n「バックエンド全体をリファクタリング」、認証モジュール、データベース層、API ルート、テストを全面的に刷新。一つの Agent の注意力には限界がある。これにはチームが必要だ。\n\ns15 Agent Teams → 一人の Agent では足りない、チームを組もう。永続的なチームメイト + 非同期受信箱。\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s15",
    "locale": "en",
    "title": "s15: Agent Teams — Runtime and Coordination Protocols",
    "content": "# s15: Agent Teams — Runtime and Coordination Protocols\n\ns01 → ... → s13 → s14 → `s15` → [s16](/en/s16) → s17 → s18 → s19 → s20 → s21\n\n> *\"When one agent cannot hold the whole job, let teammates divide the work.\"* — Persistent teammates, message delivery, and coordination protocols.\n>\n> **Harness layer**: Team — how multiple agents work in parallel without losing control.\n\n---\n\n## The Problem\n\nSuppose we ask an agent to refactor an entire backend. The work may cover configuration loading, authentication, and tests. One agent can process those areas sequentially, but it takes longer and earlier details gradually leave its context.\n\nThis is a good candidate for parallel work, yet users normally describe the goal rather than design the team:\n\n```text\nRefactor this sample backend. Clean up configuration loading,\nauthentication, and tests, preserve the existing interfaces,\nand make sure the tests pass.\n```\n\nThe harness therefore has to solve four connected problems:\n\n1. Who decides that parallel work is useful, and who confirms the extra agents?\n2. How does each teammate keep its identity and context across assignments?\n3. How do results return to Lead automatically, without asking the model to poll an inbox?\n4. How do shutdown and plan approval become traceable, enforceable protocols?\n\n---\n\n## The Solution\n\n![Agent Teams Overview](/course-assets/s15_agent_teams/agent-teams-overview.en.svg)\n\ns15 adds a Lead-managed team runtime around the single-agent harness:\n\n- **Lead** owns the user conversation, proposes a division of work, and waits for confirmation.\n- **Teammates** run independent agent loops in background threads and become idle after an assignment.\n- **MessageBus** carries ordinary messages, results, and control events through file-backed mailboxes.\n- **Runtime delivery** consumes Lead's mailbox and injects team events into the next turn.\n- **Coordination protocols** use `type`, `request_id`, and state transitions for shutdown and plan approval.\n- **A plan gate** blocks teammate `bash` and `write_file` calls until a required plan is approved.\n\nThe model understands tasks and chooses a useful division of work. Code owns delivery, lifecycle, and protocol constraints.\n\n---\n\n## How It Works\n\n### 1. Lead proposes a team and waits for confirmation\n\nStarting teammates changes cost, concurrency, and the set of actors that may edit the workspace. That boundary should not be hidden inside an ordinary tool call. Lead's system prompt says:\n\n```python\n\"When parallel work would help, first propose a small team with clear \"\n\"responsibilities and wait for the user's confirmation. Do not call \"\n\"spawn_teammate before the user confirms.\"\n```\n\nFor the first request, Lead only proposes a split:\n\n```text\nI suggest three parallel areas:\n- config: clean up configuration loading\n- auth: refactor authentication\n- tests: add regression coverage\n\nI will start the teammates after you confirm.\n```\n\nAfter the user says \"Go ahead,\" Lead can call `spawn_teammate`. The user states the goal, Lead designs the team, and the user confirms the execution boundary.\n\n### 2. Every teammate owns an independent loop\n\nAn s06 subagent is a one-shot call. A teammate is a persistent execution unit:\n\n| | s06 Subagent | s15 Teammate |\n|---|---|---|\n| Lifecycle | Ends after one call | `WORK → IDLE → WORK` until shutdown |\n| Context | Exists for one task | Persists across assignments |\n| Communication | Returns one result | Receives messages and emits events |\n| Coordination | One-way delegation | Two-way collaboration with Lead |\n\n`spawn_teammate_thread()` gives each teammate its own system prompt, messages, and tools, then runs its loop in a daemon thread. Lead can keep coordinating while teammates work.\n\n### 3. MessageBus keeps communication outside model context\n\nLead and teammates cannot share one messages array. Otherwise one teammate's tool results would leak into another teammate's reasoning. `MessageBus` gives each agent a `.mailboxes/<name>.jsonl` inbox:\n\n```python\nclass MessageBus:\n    def send(self, from_agent, to_agent, content,\n             msg_type=\"message\", metadata=None):\n        msg = {\n            \"from\": from_agent,\n            \"to\": to_agent,\n            \"content\": content,\n            \"type\": msg_type,\n            \"metadata\": metadata or {},\n        }\n        with self._changed:\n            append_jsonl(self._path(to_agent), msg)\n            self._changed.notify_all()\n\n    def wait_for_messages(self, agent):\n        with self._changed:\n            while not self.peek(agent):\n                self._changed.wait()\n            return self._read_unlocked(agent)\n```\n\nA lock protects mailbox files from concurrent teammate access. A `Condition` lets idle teammates sleep until an event arrives instead of polling continuously.\n\n### 4. The runtime delivers inbox events automatically\n\n`read_inbox()` consumes messages by reading and deleting the mailbox file, so Lead keeps a single consumer, `consume_lead_inbox()`:\n\n```python\ndef consume_lead_inbox():\n    messages = BUS.read_inbox(\"lead\")\n    for message in messages:\n        if message[\"type\"].endswith(\"_response\"):\n            match_response(...)\n    return messages\n```\n\nAn event thread beside the main loop wakes Lead when a new message arrives:\n\n```text\nMessageBus → consume_lead_inbox\n           → update protocol state\n           → inject [Team events] into history\n           → start another Lead turn\n```\n\n`check_inbox` is not a model tool. Message arrival belongs to the runtime; the model only handles events that have already been delivered into its context.\n\n### 5. Result and idle are separate events\n\nWhen a teammate finishes one assignment, the runtime sends two events in order:\n\n```text\nresult:            \"Authentication refactored; related tests pass.\"\nidle_notification: \"Waiting for more work.\"\n```\n\n`result` answers \"What did this assignment produce?\" `idle_notification` answers \"Can this teammate accept more work?\" A single vague \"done\" cannot represent both facts.\n\nAn idle teammate does not exit. An ordinary message returns it to WORK; a `shutdown_request` starts a graceful shutdown handshake.\n\n### 6. Control messages use types and request IDs\n\nFree-form text is fine for ordinary collaboration, but shutdown and approval should not depend on guessing intent. They use structured messages:\n\n![Team Protocols](/course-assets/s15_agent_teams/team-protocols-overview.en.svg)\n\n```python\n@dataclass\nclass ProtocolState:\n    request_id: str\n    type: str\n    sender: str\n    target: str\n    status: str\n    payload: str\n\n\npending_requests: dict[str, ProtocolState] = {}\n```\n\nThe shutdown path is:\n\n```text\nLead creates a pending shutdown request\n  → shutdown_request(request_id) enters the teammate inbox\n  → the teammate finishes its current step\n  → shutdown_response(request_id) returns to Lead\n  → request_id locates the original request\n  → pending becomes approved and the teammate loop exits\n```\n\nThe ID correlates one reply with one request, the type prevents a mismatched reply from changing state, and the status prevents duplicate responses from being applied twice.\n\n### 7. Plan approval constrains execution\n\nThe plan protocol runs in the opposite direction:\n\n```text\nLead → plan_request\nteammate → plan_approval_request(request_id, plan)\nLead → plan_approval_response(request_id, approve, feedback)\n```\n\nMerely telling a teammate to wait is not a reliable gate, so tool dispatch checks the plan state:\n\n```python\ndef _run_teammate_tool(name, block, handlers):\n    gate = plan_gates.get(name, \"not_required\")\n    if block.name in {\"bash\", \"write_file\"} and gate not in {\n        \"not_required\", \"approved\"\n    }:\n        return f\"Blocked: plan status is {gate}.\"\n    return handlers[block.name](**block.input)\n```\n\nWhile the state is `required`, `pending`, or `rejected`, the teammate can read files and submit or revise a plan, but it cannot run Shell commands or write files. The tools are released only after an approval response changes the state to `approved`.\n\n---\n\n## One Complete Run\n\n```text\ns15 >> Refactor this sample backend. Clean up configuration loading,\n       authentication, and tests, preserve existing interfaces,\n       and make sure the tests pass.\n\nLead: I suggest config, auth, and tests as three parallel areas.\n      Shall I start the team?\n\ns15 >> Go ahead.\n\n[teammate] config spawned\n[teammate] auth spawned\n[teammate] tests spawned\n[bus] auth → lead (result) ...\n[bus] auth → lead (idle_notification) ...\n[wake: 2 team events → new turn]\nLead: I received the authentication result and will coordinate the rest.\n```\n\nThe terminal exposes the user request, Lead's split, teammate startup, messages, results, idle transitions, and shutdown events. The user does not have to name a Lead or ask it to check an inbox.\n\n---\n\n## What Changed from s14\n\n| Component | s14 | s15 |\n|---|---|---|\n| Agents | One agent | One Lead plus persistent teammates |\n| User flow | Execute the request | Propose a team, then confirm startup |\n| Communication | None | File mailboxes plus automatic delivery |\n| Lifecycle | One loop | Teammate `WORK / IDLE / shutdown` |\n| Reporting | Current agent output | Separate `result` and `idle_notification` |\n| Control | None | Shutdown and plan approval protocols |\n| Enforcement | No team constraint | Required plans gate mutating tools |\n\n---\n\n## Try It\n\n```sh\ncd learn-claude-code\npython s15_agent_teams/code.py\n```\n\nStart with an ordinary request:\n\n```text\nRefactor this sample backend. Clean up configuration loading,\nauthentication, and tests, preserve the existing interfaces,\nand make sure the tests pass.\n```\n\nAfter Lead proposes the team, reply:\n\n```text\nGo ahead.\n```\n\nWatch for `spawned`, `result`, `idle_notification`, `plan_approval_*`, and `shutdown_*` events, along with mailbox files appearing and being consumed under `.mailboxes/`.\n\n---\n\n## Next\n\nIn s15, Lead still assigns each teammate explicitly. The next lesson gives idle teammates access to the shared task board so they can discover and claim ready work themselves.\n\nNext: [s16 Autonomous Agents](/en/s16).\n\n<!-- translation-sync: zh@v2, en@v2, ja@v2 -->\n"
  },
  {
    "version": "s15",
    "locale": "zh",
    "title": "s15: Agent Teams — 团队运行时与协作协议",
    "content": "# s15: Agent Teams — 团队运行时与协作协议\n\ns01 → ... → s13 → s14 → `s15` → [s16](/zh/s16) → s17 → s18 → s19 → s20 → s21\n\n> *\"一个 Agent 顾不过来，就让队友分工协作。\"* — 持久队友、消息投递与协作协议。\n>\n> **Harness 层**：团队 — 多个 Agent 如何并行工作，又如何保持可控。\n\n---\n\n## 问题\n\n当我们需要 Agent 帮助我们重构整个后端时，任务可能同时涉及配置加载、认证逻辑和测试。一个 Agent 依次处理所有模块，不但耗时更长，早期细节也会逐渐退出上下文。\n\n这类任务适合拆给多个 Agent，但用户通常只会描述需求，不会先设计一套团队：\n\n```text\n请重构这个示例后端，分别整理配置加载、认证逻辑和测试，\n保持现有接口兼容，并确保测试通过。\n```\n\n因此，Harness 需要解决的不只是“再启动几个 Agent”，而是四个连续问题：\n\n1. 谁判断任务是否值得并行，以及如何征得用户确认？\n2. 队友如何保留自己的身份和上下文，持续接收工作？\n3. 队友的结果如何自动回到 Lead，而不是依赖模型反复检查邮箱？\n4. 关机与计划审批如何变成可追踪、可执行的协议？\n\n---\n\n## 解决方案\n\n![Agent Teams Overview](/course-assets/s15_agent_teams/agent-teams-overview.svg)\n\ns15 在单 Agent Harness 外增加一个由 Lead 管理的团队运行时：\n\n- **Lead** 保持用户对话，判断是否需要团队，提出分工并等待确认。\n- **队友** 在独立线程中运行自己的 Agent Loop，完成工作后进入空闲。\n- **MessageBus** 用文件邮箱传递普通消息、结果和控制事件。\n- **运行时投递** 自动消费 Lead 的邮箱，把团队事件注入下一轮上下文。\n- **协作协议** 用 `type`、`request_id` 和状态机处理关机与计划审批。\n- **计划闸门** 在计划未批准时拦截队友的 `bash` 和 `write_file`。\n\n模型负责理解任务与分工，代码负责消息投递、生命周期和协议约束。\n\n---\n\n## 工作原理\n\n### 1. Lead 先提出团队，再等待用户确认\n\n是否创建团队会改变成本、并发度和可写入范围，不应该被隐藏在一次普通工具调用里。Lead 的 system prompt 明确规定：\n\n```python\n\"When parallel work would help, first propose a small team with clear \"\n\"responsibilities and wait for the user's confirmation. Do not call \"\n\"spawn_teammate before the user confirms.\"\n```\n\n第一次输入需求时，Lead 只需要说明建议的拆分：\n\n```text\n我建议分成三个方向并行处理：\n- config：整理配置加载\n- auth：重构认证逻辑\n- tests：补齐回归测试\n\n确认后我会启动队友并协调结果。\n```\n\n用户回复“开始吧”后，Lead 才调用 `spawn_teammate`。用户表达目标，Lead 设计团队，用户确认执行边界；三者的职责不会混在一起。\n\n### 2. 每个队友拥有独立循环\n\ns06 的子 Agent 是一次性调用，返回结果后就结束。队友则是持久执行单元：\n\n| | s06 子 Agent | s15 队友 |\n|---|---|---|\n| 生命周期 | 完成一次调用后结束 | `WORK → IDLE → WORK`，直到收到关机请求 |\n| 上下文 | 只服务当前任务 | 在多轮协作中保留 |\n| 通信 | 返回一次结果 | 持续接收消息并上报事件 |\n| 协调 | 主 Agent 单向委派 | Lead 与队友双向协作 |\n\n`spawn_teammate_thread()` 为队友创建独立的 system prompt、messages 和工具集，并把循环放入 daemon 线程。Lead 不必等待某个队友结束，仍可继续派发任务或处理其他结果。\n\n### 3. MessageBus 把通信放在上下文之外\n\nLead 和队友不能共享同一份 messages，否则一个队友的工具结果会混入另一个队友的推理。`MessageBus` 为每个 Agent 建立 `.mailboxes/<name>.jsonl`：\n\n```python\nclass MessageBus:\n    def send(self, from_agent, to_agent, content,\n             msg_type=\"message\", metadata=None):\n        msg = {\n            \"from\": from_agent,\n            \"to\": to_agent,\n            \"content\": content,\n            \"type\": msg_type,\n            \"metadata\": metadata or {},\n        }\n        with self._changed:\n            append_jsonl(self._path(to_agent), msg)\n            self._changed.notify_all()\n\n    def wait_for_messages(self, agent):\n        with self._changed:\n            while not self.peek(agent):\n                self._changed.wait()\n            return self._read_unlocked(agent)\n```\n\n锁保证同一进程中的多个队友不会同时破坏邮箱文件，`Condition` 让空闲队友等待事件，而不是持续轮询。\n\n### 4. 收件箱由运行时自动投递\n\n`read_inbox()` 是消费式读取：读出后删除邮箱文件。因此，Lead 只保留一个消费入口 `consume_lead_inbox()`：\n\n```python\ndef consume_lead_inbox():\n    messages = BUS.read_inbox(\"lead\")\n    for message in messages:\n        if message[\"type\"].endswith(\"_response\"):\n            match_response(...)\n    return messages\n```\n\n主循环旁的事件线程发现新消息后，会唤醒 Lead：\n\n```text\nMessageBus → consume_lead_inbox\n           → 更新协议状态\n           → [Team events] 注入 history\n           → Lead 开始新一轮\n```\n\n`check_inbox` 不再是模型工具。消息何时到达属于运行时职责；模型只需要处理已经送入上下文的事件。\n\n### 5. 结果与空闲是两个不同事件\n\n队友完成一项工作时，运行时依次发送：\n\n```text\nresult:            \"认证逻辑已重构，相关测试通过。\"\nidle_notification: \"Waiting for more work.\"\n```\n\n`result` 回答“这次工作产出了什么”，`idle_notification` 表示“这个队友现在可以接新任务”。如果把两者合成一个模糊的“done”，Lead 就无法区分任务结果和资源状态。\n\n队友进入 IDLE 后不会退出。新普通消息会让它回到 WORK；`shutdown_request` 则让它完成关机握手并结束线程。\n\n### 6. 控制消息使用类型和 request_id\n\n普通消息可以交给模型理解，关机和审批不能依赖自由文本猜测。它们使用结构化消息：\n\n![Team Protocols](/course-assets/s15_agent_teams/team-protocols-overview.svg)\n\n```python\n@dataclass\nclass ProtocolState:\n    request_id: str\n    type: str\n    sender: str\n    target: str\n    status: str\n    payload: str\n\n\npending_requests: dict[str, ProtocolState] = {}\n```\n\n关机协议的完整路径是：\n\n```text\nLead 创建 shutdown 请求，状态为 pending\n  → shutdown_request(request_id) 发给队友\n  → 队友完成当前步骤并回复 shutdown_response(request_id)\n  → Lead 用 request_id 找到原请求\n  → pending 变为 approved，队友线程退出\n```\n\n`request_id` 负责关联请求与回复，`type` 防止错误类型的回复修改状态，`status` 防止重复响应被再次处理。\n\n### 7. 计划审批不仅传消息，还约束执行\n\n计划协议沿相反方向流动：\n\n```text\nLead → plan_request\n队友 → plan_approval_request(request_id, plan)\nLead → plan_approval_response(request_id, approve, feedback)\n```\n\n只告诉队友“请等待批准”并不可靠，所以工具分发器检查计划状态：\n\n```python\ndef _run_teammate_tool(name, block, handlers):\n    gate = plan_gates.get(name, \"not_required\")\n    if block.name in {\"bash\", \"write_file\"} and gate not in {\n        \"not_required\", \"approved\"\n    }:\n        return f\"Blocked: plan status is {gate}.\"\n    return handlers[block.name](**block.input)\n```\n\n当状态为 `required`、`pending` 或 `rejected` 时，队友仍可读取文件、提交或修改计划，但不能执行 Shell 或写文件。批准消息到达后，状态变为 `approved`，工具才会放行。\n\n---\n\n## 一次完整运行\n\n```text\ns15 >> 请重构这个示例后端，分别整理配置加载、认证逻辑和测试，\n       保持现有接口兼容，并确保测试通过。\n\nLead: 建议由 config、auth、tests 三个方向并行处理，是否开始？\n\ns15 >> 开始吧\n\n[teammate] config spawned\n[teammate] auth spawned\n[teammate] tests spawned\n[bus] auth → lead (result) ...\n[bus] auth → lead (idle_notification) ...\n[wake: 2 team events → new turn]\nLead: 已收到认证部分结果，继续等待并协调其他队友。\n```\n\n终端中显示的是用户需求、Lead 分工、队友启动、消息流、结果、空闲和关机事件。用户不需要在提示词里指定谁是 Lead，也不需要手动要求检查邮箱。\n\n---\n\n## 相对 s14 的变化\n\n| 组件 | s14 | s15 |\n|---|---|---|\n| Agent 数量 | 一个 Agent | 一个 Lead + 多个持久队友 |\n| 用户交互 | 直接执行任务 | 先提出团队方案，再确认启动 |\n| 通信 | 无 | 文件邮箱 + 自动事件投递 |\n| 生命周期 | 单循环 | 队友 `WORK / IDLE / shutdown` |\n| 结果上报 | 当前 Agent 输出 | `result` 与 `idle_notification` 分离 |\n| 控制协议 | 无 | 关机与计划审批 |\n| 执行约束 | 无团队约束 | 未批准计划会拦截写入类工具 |\n\n---\n\n## 试一下\n\n```sh\ncd learn-claude-code\npython s15_agent_teams/code.py\n```\n\n先输入一个自然需求：\n\n```text\n请重构这个示例后端，分别整理配置加载、认证逻辑和测试，\n保持现有接口兼容，并确保测试通过。\n```\n\n看到 Lead 给出分工后，再回复：\n\n```text\n开始吧\n```\n\n观察终端中的 `spawned`、`result`、`idle_notification`、`plan_approval_*` 和 `shutdown_*` 事件，以及 `.mailboxes/` 中消息写入和消费的过程。\n\n---\n\n## 接下来\n\ns15 中，Lead 仍然要明确告诉每个队友做什么。下一章把共享任务看板交给空闲队友，让它们自己发现并认领可执行任务。\n\n下一章：[s16 Autonomous Agents](/zh/s16)。\n\n<!-- translation-sync: zh@v2, en@v2, ja@v2 -->\n"
  },
  {
    "version": "s15",
    "locale": "ja",
    "title": "s15: Agent Teams — チームランタイムと協調プロトコル",
    "content": "# s15: Agent Teams — チームランタイムと協調プロトコル\n\ns01 → ... → s13 → s14 → `s15` → [s16](/ja/s16) → s17 → s18 → s19 → s20 → s21\n\n> *「1 つの Agent だけでは扱いきれないなら、チームメイトで分担する。」* — 永続チームメイト、メッセージ配信、協調プロトコル。\n>\n> **Harness レイヤー**：チーム — 複数 Agent を並行動作させながら制御を保つ。\n\n---\n\n## 問題\n\nAgent にバックエンド全体のリファクタリングを頼む場合、設定読み込み、認証、テストを同時に扱うことになる。1 つの Agent が順番に処理することもできるが、時間がかかり、初期の詳細は徐々にコンテキストから抜けていく。\n\nこのような仕事は並列化に向いている。しかし、通常のユーザーはチーム構成ではなく目的だけを伝える：\n\n```text\nこのサンプルバックエンドをリファクタリングしてください。\n設定読み込み、認証ロジック、テストを整理し、\n既存インターフェースを保ったままテストを通してください。\n```\n\nそのため Harness は、単に Agent を増やすだけでなく、次の 4 点を解決する必要がある：\n\n1. 並列化が有効かを誰が判断し、追加 Agent の起動を誰が確認するか。\n2. チームメイトが複数の依頼にまたがって、どう身元とコンテキストを保つか。\n3. モデルに受信箱を繰り返し確認させず、結果をどう Lead へ戻すか。\n4. 終了と計画承認を、どう追跡可能で強制可能なプロトコルにするか。\n\n---\n\n## 解決策\n\n![Agent Teams Overview](/course-assets/s15_agent_teams/agent-teams-overview.ja.svg)\n\ns15 は単一 Agent の Harness の外側に、Lead が管理するチームランタイムを追加する：\n\n- **Lead** はユーザーとの会話を維持し、分担案を提示して確認を待つ。\n- **チームメイト** は独立した Agent Loop をバックグラウンドスレッドで実行し、作業後は IDLE になる。\n- **MessageBus** はファイル受信箱を通して、通常メッセージ、結果、制御イベントを運ぶ。\n- **ランタイム配信** は Lead の受信箱を消費し、チームイベントを次のターンへ注入する。\n- **協調プロトコル** は `type`、`request_id`、状態遷移で終了と計画承認を扱う。\n- **計画ゲート** は、必要な計画が承認されるまで `bash` と `write_file` を遮断する。\n\nモデルはタスクを理解して分担を決める。コードは配信、ライフサイクル、プロトコル制約を担う。\n\n---\n\n## 仕組み\n\n### 1. Lead はチーム案を示し、確認を待つ\n\nチームメイトの起動は、コスト、並行度、ワークスペースを書き換える主体を変える。この境界を通常のツール呼び出しの中に隠してはいけない。Lead の system prompt は次のように定める：\n\n```python\n\"When parallel work would help, first propose a small team with clear \"\n\"responsibilities and wait for the user's confirmation. Do not call \"\n\"spawn_teammate before the user confirms.\"\n```\n\n最初の依頼に対して、Lead はまず分担案だけを返す：\n\n```text\n次の 3 方向で並行処理することを提案します。\n- config：設定読み込みの整理\n- auth：認証ロジックのリファクタリング\n- tests：回帰テストの追加\n\n確認後にチームメイトを起動します。\n```\n\nユーザーが「始めてください」と返した後で、Lead は `spawn_teammate` を呼ぶ。ユーザーが目的を示し、Lead がチームを設計し、ユーザーが実行境界を確認する。\n\n### 2. 各チームメイトは独立したループを持つ\n\ns06 の Subagent は 1 回限りの呼び出しだが、チームメイトは永続する実行単位である：\n\n| | s06 Subagent | s15 チームメイト |\n|---|---|---|\n| ライフサイクル | 1 回の呼び出し後に終了 | 終了要求まで `WORK → IDLE → WORK` |\n| コンテキスト | 1 つのタスクだけ | 複数の依頼をまたいで保持 |\n| 通信 | 1 回だけ結果を返す | メッセージを受け取り、イベントを送る |\n| 協調 | 一方向の委任 | Lead との双方向協調 |\n\n`spawn_teammate_thread()` はチームメイトごとに system prompt、messages、ツールを作り、daemon thread でループを実行する。Lead はチームメイトの終了を待たずに、別の依頼や結果を調整できる。\n\n### 3. MessageBus は通信をモデルのコンテキスト外に置く\n\nLead とチームメイトが同じ messages 配列を共有すると、あるチームメイトのツール結果が別のチームメイトの推論へ混ざる。`MessageBus` は各 Agent に `.mailboxes/<name>.jsonl` 受信箱を与える：\n\n```python\nclass MessageBus:\n    def send(self, from_agent, to_agent, content,\n             msg_type=\"message\", metadata=None):\n        msg = {\n            \"from\": from_agent,\n            \"to\": to_agent,\n            \"content\": content,\n            \"type\": msg_type,\n            \"metadata\": metadata or {},\n        }\n        with self._changed:\n            append_jsonl(self._path(to_agent), msg)\n            self._changed.notify_all()\n\n    def wait_for_messages(self, agent):\n        with self._changed:\n            while not self.peek(agent):\n                self._changed.wait()\n            return self._read_unlocked(agent)\n```\n\nロックは複数スレッドによる受信箱ファイルの破損を防ぐ。`Condition` により、IDLE のチームメイトはポーリングせずイベント到着まで待機できる。\n\n### 4. 受信イベントはランタイムが自動配信する\n\n`read_inbox()` はメッセージを読み、受信箱ファイルを削除する。そのため Lead の消費入口は `consume_lead_inbox()` だけにする：\n\n```python\ndef consume_lead_inbox():\n    messages = BUS.read_inbox(\"lead\")\n    for message in messages:\n        if message[\"type\"].endswith(\"_response\"):\n            match_response(...)\n    return messages\n```\n\nメインループのイベントスレッドは、新しいメッセージが届くと Lead を起こす：\n\n```text\nMessageBus → consume_lead_inbox\n           → プロトコル状態を更新\n           → [Team events] を history へ注入\n           → Lead の次ターンを開始\n```\n\n`check_inbox` はモデルのツールではない。メッセージの到着はランタイムの責務であり、モデルはコンテキストへ配信済みのイベントだけを処理する。\n\n### 5. 結果と IDLE は別のイベント\n\nチームメイトが 1 件の作業を終えると、ランタイムは次の順序で 2 つのイベントを送る：\n\n```text\nresult:            \"認証をリファクタリングし、関連テストが通りました。\"\nidle_notification: \"Waiting for more work.\"\n```\n\n`result` は「今回の作業で何が得られたか」、`idle_notification` は「新しい仕事を受けられるか」を表す。1 つの曖昧な「done」では両者を区別できない。\n\nIDLE になったチームメイトは終了しない。通常メッセージで WORK に戻り、`shutdown_request` で終了ハンドシェイクを始める。\n\n### 6. 制御メッセージには型と request_id を使う\n\n通常の協調は自由文でよいが、終了と承認を意図の推測に任せてはいけない。制御イベントは構造化する：\n\n![Team Protocols](/course-assets/s15_agent_teams/team-protocols-overview.ja.svg)\n\n```python\n@dataclass\nclass ProtocolState:\n    request_id: str\n    type: str\n    sender: str\n    target: str\n    status: str\n    payload: str\n\n\npending_requests: dict[str, ProtocolState] = {}\n```\n\n終了プロトコルは次の経路を通る：\n\n```text\nLead が pending の shutdown request を作る\n  → shutdown_request(request_id) をチームメイトへ送る\n  → チームメイトが現在の手順を終える\n  → shutdown_response(request_id) を Lead へ返す\n  → request_id で元の要求を特定する\n  → pending が approved になり、チームメイトループが終了する\n```\n\nID は要求と応答を対応付け、型は誤った応答による状態変更を防ぎ、状態は重複応答の再適用を防ぐ。\n\n### 7. 計画承認は実行も制約する\n\n計画プロトコルは逆方向に流れる：\n\n```text\nLead → plan_request\nチームメイト → plan_approval_request(request_id, plan)\nLead → plan_approval_response(request_id, approve, feedback)\n```\n\n「承認まで待つ」と伝えるだけでは確実なゲートにならない。そこでツール dispatch が計画状態を検査する：\n\n```python\ndef _run_teammate_tool(name, block, handlers):\n    gate = plan_gates.get(name, \"not_required\")\n    if block.name in {\"bash\", \"write_file\"} and gate not in {\n        \"not_required\", \"approved\"\n    }:\n        return f\"Blocked: plan status is {gate}.\"\n    return handlers[block.name](**block.input)\n```\n\n状態が `required`、`pending`、`rejected` の間、チームメイトはファイルを読み、計画を提出または修正できるが、Shell 実行やファイル書き込みはできない。承認応答で `approved` になった後にだけツールが解放される。\n\n---\n\n## 一連の実行例\n\n```text\ns15 >> このサンプルバックエンドをリファクタリングしてください。\n       設定読み込み、認証、テストを整理し、\n       既存インターフェースを保ってテストを通してください。\n\nLead: config、auth、tests の 3 方向で並行処理することを提案します。\n      チームを開始しますか？\n\ns15 >> 始めてください\n\n[teammate] config spawned\n[teammate] auth spawned\n[teammate] tests spawned\n[bus] auth → lead (result) ...\n[bus] auth → lead (idle_notification) ...\n[wake: 2 team events → new turn]\nLead: 認証の結果を受け取りました。残りの作業も調整します。\n```\n\n端末には、ユーザー要求、Lead の分担、起動、メッセージ、結果、IDLE、終了イベントが表示される。ユーザーが Lead を指名したり、受信箱の確認を頼んだりする必要はない。\n\n---\n\n## s14 からの変更\n\n| コンポーネント | s14 | s15 |\n|---|---|---|\n| Agent | 1 つ | 1 つの Lead + 永続チームメイト |\n| ユーザーフロー | 依頼を直接実行 | チーム案を提示してから起動を確認 |\n| 通信 | なし | ファイル受信箱 + 自動イベント配信 |\n| ライフサイクル | 1 つのループ | チームメイトの `WORK / IDLE / shutdown` |\n| 結果通知 | 現在の Agent の出力 | `result` と `idle_notification` を分離 |\n| 制御 | なし | 終了と計画承認プロトコル |\n| 強制 | チーム制約なし | 必須計画が変更系ツールをゲート |\n\n---\n\n## 試してみる\n\n```sh\ncd learn-claude-code\npython s15_agent_teams/code.py\n```\n\nまず通常の依頼を入力する：\n\n```text\nこのサンプルバックエンドをリファクタリングしてください。\n設定読み込み、認証ロジック、テストを整理し、\n既存インターフェースを保ったままテストを通してください。\n```\n\nLead がチーム案を示したら、次のように返す：\n\n```text\n始めてください\n```\n\n`spawned`、`result`、`idle_notification`、`plan_approval_*`、`shutdown_*` の各イベントと、`.mailboxes/` のファイルが生成・消費される流れを確認する。\n\n---\n\n## 次へ\n\ns15 では、Lead が各チームメイトへ明示的に仕事を割り当てる。次のセッションでは共有タスクボードを IDLE のチームメイトに公開し、実行可能な仕事を自ら見つけて claim できるようにする。\n\n次へ：[s16 Autonomous Agents](/ja/s16)。\n\n<!-- translation-sync: zh@v2, en@v2, ja@v2 -->\n"
  },
  {
    "version": "s16",
    "locale": "en",
    "title": "s16: Autonomous Agents — Check the Board, Claim the Work",
    "content": "# s16: Autonomous Agents — Check the Board, Claim the Work\n\ns01 → ... → s14 → s15 → `s16` → [s17](/en/s17) → s18 → s19 → s20 → s21\n\n> *\"Idle does not only mean waiting for a message; it can also mean looking for ready work.\"* — Shared task board, automatic discovery, and atomic claims.\n>\n> **Harness layer**: Autonomy — Lead owns the goal while teammates discover the next step from shared state.\n\n---\n\n## The Problem\n\nIn s15, a teammate enters IDLE after finishing an assignment and waits for Lead to send more work. If the task board already contains ten pending tasks, Lead still has to choose a teammate, send a message, and wait for a result ten times.\n\nOnce work has been decomposed and dependencies are recorded on the task board, assigning the next ready task does not always need another model decision. An idle teammate can read shared state and claim work whose prerequisites are complete.\n\n---\n\n## The Solution\n\n![Autonomous Agents Overview](/course-assets/s16_autonomous_agents/autonomous-agents-overview.en.svg)\n\ns16 keeps the s15 team lifecycle and extends only the IDLE state:\n\n```text\ns15: WORK → result → IDLE → wait for a message\ns16: WORK → result → IDLE → wait for a message\n                            └→ scan board → claim → WORK\n```\n\nIt adds two functions:\n\n- `scan_unclaimed_tasks()` finds tasks that can start now.\n- `claim_next_task(name)` attempts to claim one candidate atomically.\n\nTeammates also receive `list_tasks`, `claim_task`, and `complete_task`, allowing the claimed work to close inside the same loop.\n\n---\n\n## How It Works\n\n### 1. Discovery and ownership are separate steps\n\nScanning reads state without changing it:\n\n```python\ndef scan_unclaimed_tasks() -> list[Task]:\n    return [\n        task for task in list_tasks()\n        if (\n            task.status == \"pending\"\n            and task.owner is None\n            and can_start(task.id)\n        )\n    ]\n```\n\nA candidate must be `pending`, have no owner, and have every `blockedBy` dependency completed.\n\nThe resulting list is only a snapshot. Another teammate may claim the same task immediately afterward, so \"discovered\" must never mean \"owned.\"\n\n### 2. Claim performs read, validation, and write under one lock\n\n`claim_task()` protects the full state transition with `task_lock`:\n\n```python\ndef claim_task(task_id: str, owner: str) -> str:\n    with task_lock:\n        task = load_task(task_id)\n        if task.status != \"pending\" or task.owner:\n            return \"Task is no longer available\"\n        if not can_start(task_id):\n            return \"Task is blocked\"\n\n        task.owner = owner\n        task.status = \"in_progress\"\n        save_task(task)\n        return f\"Claimed {task.id}\"\n```\n\n`claim_next_task()` tries candidates until one claim succeeds:\n\n```python\ndef claim_next_task(name: str) -> Task | None:\n    for task in scan_unclaimed_tasks():\n        result = claim_task(task.id, owner=name)\n        if result.startswith(\"Claimed \"):\n            return load_task(task.id)\n    return None\n```\n\nMany teammates may observe the board at once, but the claim function gives each task one final owner.\n\n### 3. Messages take priority over board scans\n\nIn IDLE, a teammate first waits briefly for mailbox events:\n\n```python\nwhile True:\n    inbox = BUS.wait_for_messages(name, IDLE_SCAN_INTERVAL)\n    if inbox:\n        handle_messages(inbox)\n        break\n\n    task = claim_next_task(name)\n    if task:\n        messages.append({\n            \"role\": \"user\",\n            \"content\": (\n                f\"[Auto-claimed task {task.id}] \"\n                f\"{task.subject}\\n{task.description}\"\n            ),\n        })\n        break\n```\n\nThis ordering matters:\n\n- Shutdown, plan approval, and direct Lead messages should be handled promptly.\n- Only otherwise idle time is used to look for shared work.\n\nIf there is neither a message nor a ready task, the teammate stays idle. An empty scan is not a reason to exit because a blocked task may become ready later.\n\n### 4. A claimed task reuses the same WORK loop\n\nAfter a successful claim, the runtime injects the task ID, subject, and description into the teammate's messages. The existing file tools, Shell, plan gate, result reporting, and shutdown protocol all remain unchanged.\n\n```text\nready task appears\n  → idle teammate discovers it\n  → claim_task writes owner and in_progress\n  → task enters teammate messages\n  → WORK\n  → complete_task\n  → result + idle_notification\n  → scan again\n```\n\nAutonomy does not require another agent loop. It adds a shared-state entry point to the loop that already exists.\n\n---\n\n## Why This Design\n\n**Why not ask Lead to assign every task?**\n\nThe task's `status`, `owner`, and `blockedBy` already encode whether it can run. Reinterpreting that same state through Lead adds coordination turns without adding judgment.\n\n**Why not set the owner during scanning?**\n\nScans may overlap. Keeping ownership changes in one locked function gives every caller the same rule.\n\n**Why keep teammates alive when no task is ready?**\n\nAn empty candidate list may only mean that prerequisites are still running. IDLE teammates can pick up downstream work as soon as it becomes ready.\n\n---\n\n## What Changed from s15\n\n| Component | s15 | s16 |\n|---|---|---|\n| IDLE behavior | Wait for team messages | Wait for messages, then scan the board |\n| Assignment | Lead sends work explicitly | Teammates may auto-claim |\n| Ownership | Caller initiates claim | `task_lock` makes claim atomic |\n| Teammate tools | Files, Shell, messages, plans | Adds list / claim / complete task |\n| Result and shutdown | `result`, `idle_notification`, shutdown protocol | Unchanged |\n\n---\n\n## Try It\n\n```sh\ncd learn-claude-code\npython s16_autonomous_agents/code.py\n```\n\nEnter an ordinary request:\n\n```text\nPut the backend refactor on a shared task board. Complete configuration,\nauthentication, and tests in parallel where dependencies allow, preserve\nexisting interfaces, and summarize the result.\n```\n\nAfter Lead proposes a team, reply:\n\n```text\nGo ahead.\n```\n\nWatch tasks move from `pending` to `in_progress` and `completed` under `.tasks/`. Two idle teammates should claim different tasks, and a task with `blockedBy` should become a candidate only after its prerequisites finish.\n\n---\n\n## Next\n\nTeammates can now discover work, but they still edit files in the same directory. The next lesson binds task ownership to isolated working directories.\n\nNext: [s17 Worktree Isolation](/en/s17).\n\n<!-- translation-sync: zh@v3, en@v3, ja@v3 -->\n"
  },
  {
    "version": "s16",
    "locale": "zh",
    "title": "s16: Autonomous Agents — 自己看板，自己认领",
    "content": "# s16: Autonomous Agents — 自己看板，自己认领\n\ns01 → ... → s14 → s15 → `s16` → [s17](/zh/s17) → s18 → s19 → s20 → s21\n\n> *\"空闲时不只等消息，也主动寻找可以开始的工作。\"* — 共享任务板、自动发现与原子认领。\n>\n> **Harness 层**：自治 — Lead 管目标，队友从任务状态中发现下一步。\n\n---\n\n## 问题\n\ns15 的队友会在完成一项工作后进入 IDLE，等待 Lead 继续派发。如果任务板上已经有十个待办任务，Lead 仍然要逐个选择队友、发送消息，再等待结果。\n\n当任务已经被拆分，并且依赖关系也写进了任务板，谁来执行下一项工作不一定需要 Lead 再做一次模型决策。空闲队友可以直接读取共享状态，找到已经满足条件的任务并认领它。\n\n---\n\n## 解决方案\n\n![Autonomous Agents Overview](/course-assets/s16_autonomous_agents/autonomous-agents-overview.svg)\n\ns16 不改变 s15 的团队生命周期，只扩展 IDLE 状态：\n\n```text\ns15: WORK → result → IDLE → 等待消息\ns16: WORK → result → IDLE → 等待消息\n                            └→ 扫描任务板 → 认领 → WORK\n```\n\n新增两个函数：\n\n- `scan_unclaimed_tasks()`：找出当前可以开始的任务。\n- `claim_next_task(name)`：尝试原子认领其中一个任务。\n\n队友工具集同时增加 `list_tasks`、`claim_task` 和 `complete_task`，让认领后的工作能在同一个循环中闭合。\n\n---\n\n## 工作原理\n\n### 1. 发现任务和认领任务是两步\n\n扫描只读取状态，不修改任务：\n\n```python\ndef scan_unclaimed_tasks() -> list[Task]:\n    return [\n        task for task in list_tasks()\n        if (\n            task.status == \"pending\"\n            and task.owner is None\n            and can_start(task.id)\n        )\n    ]\n```\n\n一个任务必须同时满足三个条件：\n\n- 状态是 `pending`；\n- 还没有 `owner`；\n- `blockedBy` 中的任务都已经完成。\n\n扫描得到的只是候选列表。另一个队友可能在下一瞬间认领同一任务，因此不能把“扫描到”当成“已经拥有”。\n\n### 2. claim 在锁内完成读、检查和写入\n\n`claim_task()` 使用同一把 `task_lock` 包住完整的读改写过程：\n\n```python\ndef claim_task(task_id: str, owner: str) -> str:\n    with task_lock:\n        task = load_task(task_id)\n        if task.status != \"pending\" or task.owner:\n            return \"Task is no longer available\"\n        if not can_start(task_id):\n            return \"Task is blocked\"\n\n        task.owner = owner\n        task.status = \"in_progress\"\n        save_task(task)\n        return f\"Claimed {task.id}\"\n```\n\n`claim_next_task()` 依次尝试候选任务。某次认领失败时，它会继续尝试下一个，而不是把失败误当成成功：\n\n```python\ndef claim_next_task(name: str) -> Task | None:\n    for task in scan_unclaimed_tasks():\n        result = claim_task(task.id, owner=name)\n        if result.startswith(\"Claimed \"):\n            return load_task(task.id)\n    return None\n```\n\n扫描负责发现，claim 负责所有权。把两者分开后，多个队友可以同时观察任务板，但每个任务只能有一个最终 owner。\n\n### 3. 消息优先，任务扫描其次\n\n队友进入 IDLE 后，先等待一小段时间的收件箱事件：\n\n```python\nwhile True:\n    inbox = BUS.wait_for_messages(name, IDLE_SCAN_INTERVAL)\n    if inbox:\n        handle_messages(inbox)\n        break\n\n    task = claim_next_task(name)\n    if task:\n        messages.append({\n            \"role\": \"user\",\n            \"content\": (\n                f\"[Auto-claimed task {task.id}] \"\n                f\"{task.subject}\\n{task.description}\"\n            ),\n        })\n        break\n```\n\n这样安排有两个原因：\n\n- 关机、计划审批和 Lead 的直接消息应该尽快响应；\n- 没有消息时，空闲时间才用于寻找共享任务。\n\n如果既没有消息也没有可认领任务，队友继续保持 IDLE，不会因为一次扫描为空就退出。\n\n### 4. 自动认领后复用同一个 WORK 循环\n\n认领成功后，运行时把任务 ID、标题和描述写入队友 messages。对模型来说，它只是收到了一项新工作；文件、Shell、计划闸门、结果上报都继续使用 s15 的机制。\n\n```text\n任务板出现 ready task\n  → 空闲队友扫描到候选\n  → claim_task 写入 owner 和 in_progress\n  → 任务进入队友 messages\n  → WORK\n  → complete_task\n  → result + idle_notification\n  → 再次扫描\n```\n\n自治不是再造一个 Agent Loop，而是给既有循环增加一个由共享状态触发的入口。\n\n---\n\n## 为什么这样设计\n\n**为什么不是 Lead 每次分配？**\n\n任务依赖已经编码在 `status`、`owner` 和 `blockedBy` 中。让 Lead 反复解释同一状态，只会增加协调轮次。\n\n**为什么不是扫描时直接改 owner？**\n\n扫描可能并发发生。把认领集中到带锁的函数中，所有调用方共享同一个所有权规则。\n\n**为什么不在没有任务时关闭队友？**\n\n暂时没有 ready task 可能只是因为依赖尚未完成。保持 IDLE 后，前置任务完成时队友可以自动接上后续工作。\n\n---\n\n## 相对 s15 的变化\n\n| 组件 | s15 | s16 |\n|---|---|---|\n| IDLE 行为 | 等待团队消息 | 先等消息，再扫描任务板 |\n| 任务分配 | Lead 明确派发 | 队友可自动认领 |\n| 任务所有权 | 调用方发起 claim | `task_lock` 保证认领原子性 |\n| 队友工具 | 文件、Shell、消息、计划 | 增加 list / claim / complete task |\n| 结果与关机 | `result`、`idle_notification`、shutdown 协议 | 保持不变 |\n\n---\n\n## 试一下\n\n```sh\ncd learn-claude-code\npython s16_autonomous_agents/code.py\n```\n\n输入一个自然需求：\n\n```text\n请把后端改造拆到共享任务板，按依赖关系并行完成配置、认证和测试，\n保持现有接口兼容，并在最后汇总结果。\n```\n\nLead 提出团队方案后回复：\n\n```text\n开始吧\n```\n\n观察 `.tasks/` 中任务如何从 `pending` 进入 `in_progress` 和 `completed`，以及两个空闲队友是否会认领不同任务。带 `blockedBy` 的任务应该只在前置任务完成后出现为候选。\n\n---\n\n## 接下来\n\n队友已经能自己找到任务，但仍然在同一个工作目录里修改文件。下一章把任务所有权和工作目录绑定起来，让并行工作彼此隔离。\n\n下一章：[s17 Worktree Isolation](/zh/s17)。\n\n<!-- translation-sync: zh@v3, en@v3, ja@v3 -->\n"
  },
  {
    "version": "s16",
    "locale": "ja",
    "title": "s16: Autonomous Agents — ボードを見て、自分で Claim する",
    "content": "# s16: Autonomous Agents — ボードを見て、自分で Claim する\n\ns01 → ... → s14 → s15 → `s16` → [s17](/ja/s17) → s18 → s19 → s20 → s21\n\n> *「IDLE はメッセージを待つだけでなく、開始可能な仕事を探す時間でもある。」* — 共有タスクボード、自動発見、原子的な Claim。\n>\n> **Harness レイヤー**：自律 — Lead は目標を管理し、チームメイトは共有状態から次の仕事を見つける。\n\n---\n\n## 問題\n\ns15 のチームメイトは作業後に IDLE へ入り、Lead から次の依頼を待つ。タスクボードに 10 件の pending task があっても、Lead はチームメイトを選び、メッセージを送り、結果を待つ操作を 10 回繰り返す必要がある。\n\n仕事がすでに分解され、依存関係もタスクボードに記録されているなら、次の ready task の割り当てに毎回モデル判断は要らない。IDLE のチームメイト自身が共有状態を読み、前提条件を満たした仕事を Claim できる。\n\n---\n\n## 解決策\n\n![Autonomous Agents Overview](/course-assets/s16_autonomous_agents/autonomous-agents-overview.ja.svg)\n\ns16 は s15 のチームライフサイクルを変えず、IDLE の動作だけを拡張する：\n\n```text\ns15: WORK → result → IDLE → メッセージを待つ\ns16: WORK → result → IDLE → メッセージを待つ\n                            └→ ボード走査 → Claim → WORK\n```\n\n追加する関数は 2 つ：\n\n- `scan_unclaimed_tasks()`：現在開始できるタスクを探す。\n- `claim_next_task(name)`：候補の 1 件を原子的に Claim する。\n\nチームメイトのツールにも `list_tasks`、`claim_task`、`complete_task` を加え、同じループ内で作業を完了できるようにする。\n\n---\n\n## 仕組み\n\n### 1. 発見と所有権を分離する\n\n走査は状態を変更せず、読み取りだけを行う：\n\n```python\ndef scan_unclaimed_tasks() -> list[Task]:\n    return [\n        task for task in list_tasks()\n        if (\n            task.status == \"pending\"\n            and task.owner is None\n            and can_start(task.id)\n        )\n    ]\n```\n\n候補は `pending` で、owner がなく、すべての `blockedBy` が完了していなければならない。\n\nただし候補一覧は一時点のスナップショットにすぎない。直後に別のチームメイトが同じタスクを Claim する可能性があるため、「発見した」と「所有した」を同じ意味にしてはいけない。\n\n### 2. Claim はロック内で読み取り、確認、書き込みを行う\n\n`claim_task()` は状態遷移全体を `task_lock` で保護する：\n\n```python\ndef claim_task(task_id: str, owner: str) -> str:\n    with task_lock:\n        task = load_task(task_id)\n        if task.status != \"pending\" or task.owner:\n            return \"Task is no longer available\"\n        if not can_start(task_id):\n            return \"Task is blocked\"\n\n        task.owner = owner\n        task.status = \"in_progress\"\n        save_task(task)\n        return f\"Claimed {task.id}\"\n```\n\n`claim_next_task()` は成功する候補が見つかるまで順に試す：\n\n```python\ndef claim_next_task(name: str) -> Task | None:\n    for task in scan_unclaimed_tasks():\n        result = claim_task(task.id, owner=name)\n        if result.startswith(\"Claimed \"):\n            return load_task(task.id)\n    return None\n```\n\n複数のチームメイトが同時にボードを観察しても、最終的な owner は Claim 関数によって 1 人に決まる。\n\n### 3. メッセージを優先し、その後にタスクを探す\n\nIDLE に入ったチームメイトは、まず短時間だけ受信イベントを待つ：\n\n```python\nwhile True:\n    inbox = BUS.wait_for_messages(name, IDLE_SCAN_INTERVAL)\n    if inbox:\n        handle_messages(inbox)\n        break\n\n    task = claim_next_task(name)\n    if task:\n        messages.append({\n            \"role\": \"user\",\n            \"content\": (\n                f\"[Auto-claimed task {task.id}] \"\n                f\"{task.subject}\\n{task.description}\"\n            ),\n        })\n        break\n```\n\nこの順序にする理由は明確だ：\n\n- shutdown、計画承認、Lead からの直接メッセージにはすぐ応答する。\n- メッセージがない IDLE 時間だけを、共有タスクの探索に使う。\n\nメッセージも ready task もなければ IDLE を続ける。候補が空なのは、依存タスクがまだ完了していないだけかもしれない。\n\n### 4. Claim 後は同じ WORK ループを再利用する\n\nClaim に成功すると、ランタイムはタスク ID、件名、説明をチームメイトの messages へ追加する。ファイルツール、Shell、計画ゲート、結果通知、終了プロトコルはすべて s15 の仕組みをそのまま使う。\n\n```text\nready task が現れる\n  → IDLE のチームメイトが発見\n  → claim_task が owner と in_progress を記録\n  → タスクが messages に入る\n  → WORK\n  → complete_task\n  → result + idle_notification\n  → 再び走査\n```\n\n自律のために別の Agent Loop を作る必要はない。既存ループへ共有状態から入る入口を追加すればよい。\n\n---\n\n## この設計を選ぶ理由\n\n**Lead が毎回割り当てないのはなぜか。**\n\n`status`、`owner`、`blockedBy` が実行可能性をすでに表している。同じ状態を Lead に毎回解釈させても、調整ターンが増えるだけである。\n\n**走査時に owner を設定しないのはなぜか。**\n\n走査は並行実行され得る。所有権変更を 1 つのロック付き関数に集めれば、すべての呼び出し元が同じ規則に従う。\n\n**ready task がない時に終了しないのはなぜか。**\n\n依存タスクが完了すれば、後続タスクが ready になる。IDLE を維持すれば、その瞬間に次の仕事を引き継げる。\n\n---\n\n## s15 からの変更\n\n| コンポーネント | s15 | s16 |\n|---|---|---|\n| IDLE | チームメッセージを待つ | メッセージ待機後にボードを走査 |\n| 割り当て | Lead が明示的に送る | チームメイトが自動 Claim 可能 |\n| 所有権 | 呼び出し元が Claim | `task_lock` で Claim を原子的にする |\n| チームメイトツール | ファイル、Shell、メッセージ、計画 | list / claim / complete task を追加 |\n| 結果と終了 | `result`、`idle_notification`、shutdown protocol | 変更なし |\n\n---\n\n## 試してみる\n\n```sh\ncd learn-claude-code\npython s16_autonomous_agents/code.py\n```\n\n通常の要求を入力する：\n\n```text\nバックエンド改修を共有タスクボードへ分解し、依存関係が許す範囲で\n設定、認証、テストを並行実行してください。既存インターフェースを\n維持し、最後に結果をまとめてください。\n```\n\nLead がチーム案を示したら、次のように返す：\n\n```text\n始めてください\n```\n\n`.tasks/` のタスクが `pending`、`in_progress`、`completed` と変化する様子を確認する。2 人の IDLE チームメイトは別々のタスクを Claim し、`blockedBy` のあるタスクは前提完了後にだけ候補になるはずだ。\n\n---\n\n## 次へ\n\nチームメイトは仕事を自分で見つけられるようになったが、まだ同じディレクトリでファイルを変更する。次のセッションではタスク所有権を分離された作業ディレクトリへ結び付ける。\n\n次へ：[s17 Worktree Isolation](/ja/s17)。\n\n<!-- translation-sync: zh@v3, en@v3, ja@v3 -->\n"
  },
  {
    "version": "s17",
    "locale": "en",
    "title": "s17: Worktree Isolation — Separate Directories, No Conflicts",
    "content": "# s17: Worktree Isolation — Separate Directories, No Conflicts\n\ns01 → ... → s15 → s16 → `s17` → [s18](/en/s18) → s19 → s20 → s21\n\n> *\"Separate directories, no conflicts\"* — Tasks own the goal, worktrees own the directory, bound by ID.\n>\n> **Harness Layer**: Isolation — Parallel execution in separate directories.\n\n---\n\n## The Problem\n\nIn s16, Alice and Bob both work in the same directory. Alice's task is \"refactor auth module\", Bob's task is \"refactor UI login page\".\n\nAlice calls `write_file(\"config.py\", ...)`. Bob also calls `write_file(\"config.py\", ...)`. Both edit the same file, overwriting each other. And there's no clean rollback — you can't tell whose changes are whose.\n\ns15-s16 solved \"who does what\" (task system) and \"how to communicate\" (message bus), but not \"where to work\".\n\n---\n\n## The Solution\n\n![Worktree Overview](/course-assets/s17_worktree_isolation/worktree-overview.en.svg)\n\nGit worktree lets you create multiple independent working directories in the same repo, each with its own branch. Alice works in `.worktrees/auth-refactor/`, Bob in `.worktrees/ui-login/` — no conflicts.\n\nCarries forward s16's MessageBus, protocols, and autonomous claiming. This chapter adds:\n\n| Capability | Purpose |\n|------------|---------|\n| create_worktree | Create isolated directory + branch for a task |\n| bind_task_to_worktree | Bind task and directory (no status change) |\n| remove_worktree / keep_worktree | Cleanup or preserve after completion |\n| validate_worktree_name | Reject path traversal and illegal characters |\n\n---\n\n## How It Works\n\n### Creation: Task-Worktree Binding\n\n```python\ndef create_worktree(name: str, task_id: str = \"\") -> str:\n    validate_worktree_name(name)       # Only [A-Za-z0-9._-]{1,64}\n    path = WORKTREES_DIR / name\n    ok, result = run_git([\"worktree\", \"add\", str(path), \"-b\", f\"wt/{name}\", \"HEAD\"])\n    if not ok:\n        return f\"Git error: {result}\"\n    if task_id:\n        bind_task_to_worktree(task_id, name)\n    log_event(\"create\", name, task_id)\n    return f\"Worktree '{name}' created at {path}\"\n\ndef bind_task_to_worktree(task_id: str, worktree_name: str):\n    task = load_task(task_id)\n    task.worktree = worktree_name       # Write worktree field only\n    save_task(task)                     # Status stays pending, waits for teammate claim\n```\n\nBinding rule: one task binds to one worktree. Binding does NOT change task status — the task stays `pending`, and advances to `in_progress` only when a teammate claims it. This way Lead can pre-create tasks and worktrees, and teammates naturally claim worktree-bound tasks during idle.\n\n### Teammate Tool Cwd Switching\n\nEach teammate keeps a `wt_ctx` dictionary with its current worktree path. When a teammate claims a task bound to a worktree, the runtime updates `wt_ctx`; that teammate's `bash`, `read_file`, and `write_file` calls then run in the worktree directory:\n\n```python\n# Inside teammate thread\nwt_ctx = {\"path\": None}\n\ndef _run_claim_task(task_id):\n    result = claim_task(task_id, owner=name)\n    if \"Claimed\" in result:\n        task = load_task(task_id)\n        if task.worktree:\n            wt_ctx[\"path\"] = str(WORKTREES_DIR / task.worktree)\n    return result\n\ndef _run_bash(command):\n    return run_bash(command, cwd=wt_ctx[\"path\"])  # Execute in worktree\n```\n\n### Cleanup: Keep or Remove\n\nAfter task completion, two choices:\n\n```python\ndef remove_worktree(name: str, discard_changes: bool = False) -> str:\n    # Safety check: refuse by default if changes exist\n    if not discard_changes:\n        files, commits = _count_worktree_changes(path)\n        if files > 0 or commits > 0:\n            return \"Has uncommitted changes. Use discard_changes=true to force, or keep_worktree\"\n    ok, _ = run_git([\"worktree\", \"remove\", str(path), \"--force\"])\n    if not ok:\n        return \"Remove failed\"\n    run_git([\"branch\", \"-D\", f\"wt/{name}\"])\n    log_event(\"remove\", name)\n\ndef keep_worktree(name: str) -> str:\n    log_event(\"keep\", name)\n    return f\"Worktree '{name}' kept for review (branch: wt/{name})\"\n```\n\nKeep = preserve branch for manual review and merge. Remove = refuse by default if uncommitted changes; requires `discard_changes=true` to confirm. Does NOT auto-complete task — task completion is triggered explicitly by the teammate's `complete_task`.\n\n### Event Log: Auditable\n\nEach lifecycle operation writes to a log for auditing:\n\n```python\ndef log_event(event_type: str, worktree_name: str, task_id: str = \"\"):\n    event = {\"type\": event_type, \"worktree\": worktree_name,\n             \"task_id\": task_id, \"ts\": time.time()}\n    # append to .worktrees/events.jsonl\n```\n\nEvent types are `create`, `remove`, and `keep`. The log supports manual auditing; a recovery flow can rebuild the current set from `git worktree list`.\n\n### run_git: Returns Success/Failure\n\n```python\ndef run_git(args: list[str]) -> tuple[bool, str]:\n    r = subprocess.run([\"git\"] + args, cwd=WORKDIR, ...)\n    return r.returncode == 0, output\n```\n\n`create_worktree` and `remove_worktree` only write event logs after successful git commands, ensuring logs reflect actual state.\n\n---\n\n## Changes from s16\n\n| Component | Before (s16) | After (s17) |\n|-----------|-------------|-------------|\n| Working directory | All agents share WORKDIR | Each task can bind to a git worktree |\n| Task data | id/subject/status/owner/blockedBy | + worktree field |\n| Teammate tool cwd | Always WORKDIR | Auto-switches when claiming worktree-bound task |\n| New functions | — | create_worktree, bind_task_to_worktree, remove_worktree, keep_worktree, validate_worktree_name |\n| Worktree safety | None | Name validation + refuse removal with changes |\n| Event log | None | events.jsonl lifecycle auditing |\n| Lead tools | Team and task tools | + create_worktree, remove_worktree, keep_worktree |\n| Teammate tools | Task and file tools | Same tools; bash/read/write use the claimed worktree cwd |\n\n---\n\n## Try It\n\n```sh\ncd learn-claude-code\npython s17_worktree_isolation/code.py\n```\n\nTry this prompt:\n\n`Refactor the authentication module and the login page in parallel without letting the changes interfere with each other.`\n\nWhat to observe: Do both worktrees show different branches in `git status`? After claiming a worktree-bound task, does the teammate's bash run in the worktree directory? Does `remove_worktree` refuse when there are changes? Is task status still `pending` after binding?\n\n---\n\n## What's Next\n\nAgent teams can now self-organize in isolated workspaces. But Agent capabilities are limited to the tools we wrote — bash, read, write, task...\n\nWhat if users already have their own tools? Like an internal Jira API, or a custom deployment system?\n\ns18 MCP Plugin → Give Agent a plugin system. External tools connect via standard protocol; Agent doesn't need to know who wrote them.\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v0 -->\n"
  },
  {
    "version": "s17",
    "locale": "zh",
    "title": "s17: Worktree Isolation — 各干各的，互不干扰",
    "content": "# s17: Worktree Isolation — 各干各的，互不干扰\n\ns01 → ... → s15 → s16 → `s17` → [s18](/zh/s18) → s19 → s20 → s21\n\n> *\"各干各的目录, 互不干扰\"* — 任务管目标, worktree 管目录, 按 ID 绑定。\n>\n> **Harness 层**: 隔离 — 并行执行的目录隔离。\n\n---\n\n## 问题\n\ns16 中，Alice 和 Bob 都在同一个目录下工作。Alice 的任务是\"重构认证模块\"，Bob 的任务是\"重构 UI 登录页\"。\n\nAlice `write_file(\"config.py\", ...)`。Bob 也 `write_file(\"config.py\", ...)`。两个人改同一个文件，互相覆盖。而且无法干净地回滚——分不清哪些改动是谁的。\n\ns15-s16 解决了\"谁干什么\"（任务系统）和\"怎么通信\"（消息总线），但没解决\"在哪干\"。\n\n---\n\n## 解决方案\n\n![Worktree Overview](/course-assets/s17_worktree_isolation/worktree-overview.svg)\n\nGit worktree 让你在同一仓库中创建多个独立的工作目录，每个有自己的分支。Alice 在 `.worktrees/auth-refactor/` 下工作，Bob 在 `.worktrees/ui-login/` 下工作——互不干扰。\n\n沿用 s16 的 MessageBus、协议和自治认领机制。本章新增：\n\n| 能力 | 作用 |\n|------|------|\n| create_worktree | 为任务创建独立目录 + 独立分支 |\n| bind_task_to_worktree | 把任务和工作目录绑定（不改状态） |\n| remove_worktree / keep_worktree | 完成后清理或保留 |\n| validate_worktree_name | 拒绝路径穿越和非法字符 |\n\n---\n\n## 工作原理\n\n### 创建：任务-Worktree 绑定\n\n```python\ndef create_worktree(name: str, task_id: str = \"\") -> str:\n    validate_worktree_name(name)       # 只允许 [A-Za-z0-9._-]{1,64}\n    path = WORKTREES_DIR / name\n    ok, result = run_git([\"worktree\", \"add\", str(path), \"-b\", f\"wt/{name}\", \"HEAD\"])\n    if not ok:\n        return f\"Git error: {result}\"\n    if task_id:\n        bind_task_to_worktree(task_id, name)\n    log_event(\"create\", name, task_id)\n    return f\"Worktree '{name}' created at {path}\"\n\ndef bind_task_to_worktree(task_id: str, worktree_name: str):\n    task = load_task(task_id)\n    task.worktree = worktree_name       # 只写 worktree 字段\n    save_task(task)                     # 状态保持 pending，等队友 claim\n```\n\n绑定规则：一个任务绑定一个 worktree。绑定不改任务状态——任务仍是 `pending`，队友自动认领时才推进到 `in_progress`。这样 Lead 可以提前创建任务和 worktree，队友 idle 时自然认领带 worktree 的任务。\n\n### 队友工具的 cwd 切换\n\n每个队友都有一个 `wt_ctx` 字典，用来记录当前 worktree 路径。队友认领绑定了 worktree 的任务后，运行时会更新 `wt_ctx`；该队友的 `bash`、`read_file`、`write_file` 随后都在对应的 worktree 目录下执行：\n\n```python\n# 队友线程内部\nwt_ctx = {\"path\": None}\n\ndef _run_claim_task(task_id):\n    result = claim_task(task_id, owner=name)\n    if \"Claimed\" in result:\n        task = load_task(task_id)\n        if task.worktree:\n            wt_ctx[\"path\"] = str(WORKTREES_DIR / task.worktree)\n    return result\n\ndef _run_bash(command):\n    return run_bash(command, cwd=wt_ctx[\"path\"])  # 在 worktree 下执行\n```\n\n### 收尾：Keep 还是 Remove\n\n任务完成后，两个选择：\n\n```python\ndef remove_worktree(name: str, discard_changes: bool = False) -> str:\n    # 安全检查：有改动时默认拒绝\n    if not discard_changes:\n        files, commits = _count_worktree_changes(path)\n        if files > 0 or commits > 0:\n            return \"有未提交改动，使用 discard_changes=true 强制删除，或 keep_worktree 保留\"\n    ok, _ = run_git([\"worktree\", \"remove\", str(path), \"--force\"])\n    if not ok:\n        return \"删除失败\"\n    run_git([\"branch\", \"-D\", f\"wt/{name}\"])\n    log_event(\"remove\", name)\n\ndef keep_worktree(name: str) -> str:\n    log_event(\"keep\", name)\n    return f\"Worktree '{name}' kept for review (branch: wt/{name})\"\n```\n\nKeep = 留着分支，等人工 review 后合并到主分支。Remove = 有改动时默认拒绝，需要 `discard_changes=true` 确认。不自动 complete task——任务完成由队友的 `complete_task` 显式触发。\n\n### 事件流：可审计\n\n每次生命周期操作写入日志，方便排查：\n\n```python\ndef log_event(event_type: str, worktree_name: str, task_id: str = \"\"):\n    event = {\"type\": event_type, \"worktree\": worktree_name,\n             \"task_id\": task_id, \"ts\": time.time()}\n    # append to .worktrees/events.jsonl\n```\n\n事件类型包括 `create`（创建）、`remove`（删除）和 `keep`（保留）。日志用于人工排查；恢复流程可以通过 `git worktree list` 重建当前 worktree 集合。\n\n### run_git：返回成功/失败\n\n```python\ndef run_git(args: list[str]) -> tuple[bool, str]:\n    r = subprocess.run([\"git\"] + args, cwd=WORKDIR, ...)\n    return r.returncode == 0, output\n```\n\n`create_worktree` 和 `remove_worktree` 只在 git 命令成功后才写事件日志，保证日志反映真实状态。\n\n---\n\n## 相对 s16 的变更\n\n| 组件 | 之前 (s16) | 之后 (s17) |\n|------|-----------|-----------|\n| 工作目录 | 所有 Agent 共享 WORKDIR | 每个任务可绑定独立 git worktree |\n| Task 数据 | id/subject/status/owner/blockedBy | + worktree 字段 |\n| 队友工具 cwd | 始终 WORKDIR | 认领带 worktree 的任务时自动切换 |\n| 新函数 | — | create_worktree, bind_task_to_worktree, remove_worktree, keep_worktree, validate_worktree_name |\n| worktree 安全 | 无 | name 校验 + 有改动时拒绝删除 |\n| 事件日志 | 无 | events.jsonl 生命周期审计 |\n| Lead 工具 | 团队与任务工具 | + create_worktree、remove_worktree、keep_worktree |\n| 队友工具 | 任务与文件工具 | 工具不变，bash/read/write 使用已认领任务的 worktree cwd |\n\n---\n\n## 试一下\n\n```sh\ncd learn-claude-code\npython s17_worktree_isolation/code.py\n```\n\n试试这个 prompt：\n\n`请并行重构认证模块和登录页面，确保两部分改动不会互相干扰。`\n\n观察重点：两个 worktree 的 `git status` 输出是否显示不同的分支？队友认领带 worktree 的任务后，bash 命令是否在 worktree 目录下执行？`remove_worktree` 对有改动的 worktree 是否拒绝？`.tasks/` 中的任务在绑定后状态是否仍为 `pending`？\n\n---\n\n## 接下来\n\nAgent 团队能在隔离的工作空间中自组织了。但 Agent 的能力受限于我们给它写的工具——bash、read、write、task...\n\n如果用户已经有了自己的工具怎么办？比如一个公司内部的 Jira API、一个自建的部署系统？\n\ns18 MCP Plugin → 给 Agent 装一个插件系统。外部工具通过标准协议接入，Agent 不需要知道它们是谁写的。\n\n\n<!-- translation-sync: zh@v1, en@v0, ja@v0 -->\n"
  },
  {
    "version": "s17",
    "locale": "ja",
    "title": "s17: Worktree Isolation — それぞれのディレクトリ、互いに干渉しない",
    "content": "# s17: Worktree Isolation — それぞれのディレクトリ、互いに干渉しない\n\ns01 → ... → s15 → s16 → `s17` → [s18](/ja/s18) → s19 → s20 → s21\n\n> *\"それぞれのディレクトリ、互いに干渉しない\"* — タスクは目標を管理、worktree はディレクトリを管理、ID で紐付け。\n>\n> **Harness 層**: 隔離 — 並列実行のディレクトリ分離。\n\n---\n\n## 課題\n\ns16 では、Alice も Bob も同じディレクトリで作業。Alice のタスクは「認証モジュールのリファクタリング」、Bob のタスクは「UI ログインページのリファクタリング」。\n\nAlice が `write_file(\"config.py\", ...)` を呼び出し、Bob も `write_file(\"config.py\", ...)` を呼び出す。両者が同じファイルを編集し、互いに上書き。クリーンなロールバックもできない——どの変更が誰のものか区別できない。\n\ns15-s16 は「誰が何をするか」（タスクシステム）と「どう通信するか」（メッセージバス）を解決したが、「どこで作業するか」は未解決。\n\n---\n\n## ソリューション\n\n![Worktree Overview](/course-assets/s17_worktree_isolation/worktree-overview.ja.svg)\n\nGit worktree を使うと、同じリポジトリ内に複数の独立した作業ディレクトリを作成でき、それぞれが独自のブランチを持つ。Alice は `.worktrees/auth-refactor/` で作業、Bob は `.worktrees/ui-login/` で作業——互いに干渉しない。\n\ns16 の MessageBus、プロトコル、自動認領を引き継ぐ。本章では次を追加する：\n\n| 機能 | 目的 |\n|------|------|\n| create_worktree | タスク用の独立ディレクトリ + 独立ブランチを作成 |\n| bind_task_to_worktree | タスクとディレクトリを紐付け（状態は変更しない） |\n| remove_worktree / keep_worktree | 完了後のクリーンアップまたは保持 |\n| validate_worktree_name | パストラバーサルと不正文字を拒否 |\n\n---\n\n## 仕組み\n\n### 作成：タスク-Worktree 紐付け\n\n```python\ndef create_worktree(name: str, task_id: str = \"\") -> str:\n    validate_worktree_name(name)       # [A-Za-z0-9._-]{1,64} のみ許可\n    path = WORKTREES_DIR / name\n    ok, result = run_git([\"worktree\", \"add\", str(path), \"-b\", f\"wt/{name}\", \"HEAD\"])\n    if not ok:\n        return f\"Git error: {result}\"\n    if task_id:\n        bind_task_to_worktree(task_id, name)\n    log_event(\"create\", name, task_id)\n    return f\"Worktree '{name}' created at {path}\"\n\ndef bind_task_to_worktree(task_id: str, worktree_name: str):\n    task = load_task(task_id)\n    task.worktree = worktree_name       # worktree フィールドのみ書き込み\n    save_task(task)                     # 状態は pending のまま、チームメイトの claim を待つ\n```\n\n紐付けルール：1 つのタスクに 1 つの worktree を紐付け。紐付けはタスクの状態を変更しない——タスクは `pending` のままで、チームメイトが認領した時に `in_progress` に進む。これにより Lead は事前にタスクと worktree を作成でき、チームメイトは idle 時に自然に worktree 紐付け済みタスクを認領する。\n\n### チームメイトツールの cwd 切り替え\n\n各チームメイトは、現在の worktree パスを記録する `wt_ctx` 辞書を持つ。worktree に紐付いたタスクを認領すると、ランタイムが `wt_ctx` を更新し、そのチームメイトの `bash`、`read_file`、`write_file` は対応する worktree ディレクトリで実行される：\n\n```python\n# チームメイトスレッド内部\nwt_ctx = {\"path\": None}\n\ndef _run_claim_task(task_id):\n    result = claim_task(task_id, owner=name)\n    if \"Claimed\" in result:\n        task = load_task(task_id)\n        if task.worktree:\n            wt_ctx[\"path\"] = str(WORKTREES_DIR / task.worktree)\n    return result\n\ndef _run_bash(command):\n    return run_bash(command, cwd=wt_ctx[\"path\"])  # worktree で実行\n```\n\n### クリーンアップ：Keep または Remove\n\nタスク完了後、2 つの選択肢：\n\n```python\ndef remove_worktree(name: str, discard_changes: bool = False) -> str:\n    # 安全チェック：変更がある場合デフォルトで拒否\n    if not discard_changes:\n        files, commits = _count_worktree_changes(path)\n        if files > 0 or commits > 0:\n            return \"未コミットの変更あり。discard_changes=true で強制削除、または keep_worktree で保持\"\n    ok, _ = run_git([\"worktree\", \"remove\", str(path), \"--force\"])\n    if not ok:\n        return \"削除失敗\"\n    run_git([\"branch\", \"-D\", f\"wt/{name}\"])\n    log_event(\"remove\", name)\n\ndef keep_worktree(name: str) -> str:\n    log_event(\"keep\", name)\n    return f\"Worktree '{name}' kept for review (branch: wt/{name})\"\n```\n\nKeep = ブランチを保持し、手動 review 後にマージ。Remove = 未コミット変更がある場合デフォルトで拒否、`discard_changes=true` で確認が必要。タスクの自動 complete はしない——タスク完了はチームメイトの `complete_task` で明示的にトリガー。\n\n### イベントログ：監査可能\n\n各ライフサイクル操作はログに記録され、監査に利用：\n\n```python\ndef log_event(event_type: str, worktree_name: str, task_id: str = \"\"):\n    event = {\"type\": event_type, \"worktree\": worktree_name,\n             \"task_id\": task_id, \"ts\": time.time()}\n    # .worktrees/events.jsonl に append\n```\n\nイベントタイプは `create`、`remove`、`keep`。ログは手動監査に使い、復元時は `git worktree list` から現在の worktree 一覧を再構築できる。\n\n### run_git：成功/失敗を返す\n\n```python\ndef run_git(args: list[str]) -> tuple[bool, str]:\n    r = subprocess.run([\"git\"] + args, cwd=WORKDIR, ...)\n    return r.returncode == 0, output\n```\n\n`create_worktree` と `remove_worktree` は git コマンド成功後のみイベントログに書き込み、ログが実際の状態を反映することを保証。\n\n---\n\n## s16 からの変更\n\n| コンポーネント | 変更前 (s16) | 変更後 (s17) |\n|--------------|------------|------------|\n| 作業ディレクトリ | 全 Agent が WORKDIR を共有 | 各タスクが git worktree に紐付け可能 |\n| タスクデータ | id/subject/status/owner/blockedBy | + worktree フィールド |\n| チームメイトツール cwd | 常に WORKDIR | worktree 紐付けタスク認領時に自動切り替え |\n| 新規関数 | — | create_worktree, bind_task_to_worktree, remove_worktree, keep_worktree, validate_worktree_name |\n| worktree 安全性 | なし | name 検証 + 変更ありの場合削除拒否 |\n| イベントログ | なし | events.jsonl ライフサイクル監査 |\n| Lead ツール | チーム・タスクツール | + create_worktree、remove_worktree、keep_worktree |\n| チームメイトツール | タスク・ファイルツール | ツールは同じ。bash/read/write は認領した worktree の cwd を使う |\n\n---\n\n## 試してみる\n\n```sh\ncd learn-claude-code\npython s17_worktree_isolation/code.py\n```\n\n以下のプロンプトを試してください：\n\n`認証モジュールとログインページを並行してリファクタリングし、変更が互いに干渉しないようにしてください。`\n\n観察ポイント：2 つの worktree の `git status` 出力は異なるブランチを表示しているか？チームメイトが worktree 紐付けタスクを認領後、bash コマンドは worktree ディレクトリで実行されているか？`remove_worktree` は変更がある場合に拒否するか？紐付け後のタスク状態は `pending` のままか？\n\n---\n\n## 次の章\n\nAgent チームが隔離されたワークスペースで自己組織化できるようになった。しかし Agent の能力はツールに制限される——bash、read、write、task...\n\nもしユーザーが独自のツールを持っていたら？例えば社内 Jira API や独自デプロイシステム？\n\ns18 MCP Plugin → Agent にプラグインシステムを追加。外部ツールが標準プロトコルで接続、Agent は誰が書いたか知る必要がない。\n\n\n<!-- translation-sync: zh@v1, en@v1, ja@v1 -->\n"
  },
  {
    "version": "s18",
    "locale": "en",
    "title": "s18: MCP Tools — External Tools, Standard Protocol",
    "content": "# s18: MCP Tools — External Tools, Standard Protocol\n\ns01 → ... → s16 → s17 → `s18` → [s19](/en/s19) → s20 → s21\n\n> *\"External tools, standard protocol\"* — Discover, assemble, invoke. Agent doesn't need to know who wrote them.\n>\n> **Harness layer**: Plugins — External capabilities via a standard protocol.\n\n---\n\n## The Problem\n\nFrom s01 through s17, every tool the agent uses was hand-written — bash, read, write, task, worktree. Input validation, execution logic, error handling — all written line by line.\n\nNow you have 3 external services to integrate: the company's Jira API (query issues, create tickets), an in-house deployment system (trigger deploys, view logs), and the team's Notion knowledge base (search docs, create pages). You don't want to rewrite tool code for every service.\n\nYou need a standard protocol — as long as an external service implements it, the agent can call its tools directly, regardless of what language the service is written in.\n\n---\n\n## The Solution\n\n![MCP Architecture](/course-assets/s18_mcp_plugin/mcp-architecture.en.svg)\n\nMCP (Model Context Protocol) defines how agents discover and invoke external tools. Core concepts:\n\n| Concept | Purpose |\n|------|------|\n| MCPClient | The agent-side client — connects to servers, discovers tools, invokes tools |\n| MCP Server | The external service — implements `tools/list` + `tools/call` |\n| assemble_tool_pool | Assembles built-in tools and MCP tools into one tool pool |\n| mcp\\_\\_server\\_\\_tool naming | Prevents tool name collisions across different servers |\n\nCarries forward s17's worktree isolation, autonomous claiming, and team protocols. This chapter adds the `connect_mcp` tool, which connects to a service, discovers its tools, and adds them to the tool pool.\n\nThe chapter registers in-process server handlers so the full discovery and invocation flow runs offline. Each handler exposes the two operations the client needs: `tools/list` and `tools/call`.\n\n---\n\n## How It Works\n\n### MCPClient: Discovery + Invocation\n\n```python\nclass MCPClient:\n    def __init__(self, name: str):\n        self.name = name\n        self.tools: list[dict] = []\n        self._handlers: dict[str, callable] = {}\n\n    def register(self, tool_defs, handlers):\n        \"\"\"Simulates tools/list discovery.\"\"\"\n        self.tools = tool_defs\n        self._handlers = handlers\n\n    def call_tool(self, tool_name: str, args: dict) -> str:\n        \"\"\"Simulates tools/call.\"\"\"\n        handler = self._handlers.get(tool_name)\n        if not handler:\n            return f\"MCP error: unknown tool '{tool_name}'\"\n        return handler(**args)\n```\n\nThe registered Python functions provide the server-side tool implementations used by `tools/call`.\n\n### connect_mcp: Connect + Discover\n\n```python\ndef connect_mcp(name: str) -> str:\n    if name in mcp_clients:\n        return f\"MCP server '{name}' already connected\"\n    factory = MOCK_SERVERS.get(name)\n    if not factory:\n        return f\"Unknown server '{name}'. Available: ...\"\n    mcp_client = factory()\n    mcp_clients[name] = mcp_client\n    return f\"Connected to '{name}'. Discovered: ...\"\n```\n\nAfter connecting, the server's tools are immediately available.\n\n### normalize_mcp_name: Name Normalization\n\n```python\n_DISALLOWED_CHARS = re.compile(r'[^a-zA-Z0-9_-]')\n\ndef normalize_mcp_name(name: str) -> str:\n    return _DISALLOWED_CHARS.sub('_', name)\n```\n\nAll non-`[a-zA-Z0-9_-]` characters are replaced with `_`. Prevents special characters in server or tool names from causing naming conflicts or injection issues.\n\n### assemble_tool_pool: Assemble Tool Pool\n\n```python\ndef assemble_tool_pool() -> tuple[list[dict], dict]:\n    tools = list(BUILTIN_TOOLS)\n    handlers = dict(BUILTIN_HANDLERS)\n    for server_name, mcp_client in mcp_clients.items():\n        safe_server = normalize_mcp_name(server_name)\n        for tool_def in mcp_client.tools:\n            safe_tool = normalize_mcp_name(tool_def[\"name\"])\n            prefixed = f\"mcp__{safe_server}__{safe_tool}\"\n            tools.append(...)\n            handlers[prefixed] = (\n                lambda *, c=mcp_client, t=tool_def[\"name\"], **kw:\n                    c.call_tool(t, kw))\n    return tools, handlers\n```\n\nThe prefix `mcp__{server}__{tool}` prevents tool name collisions across different servers. Names are normalized through `normalize_mcp_name`.\n\nMCP tool descriptions include `(readOnly)` or `(destructive)` labels, making the distinction visible in the tool metadata.\n\n### No Cache: Tool Pool Changes, Prompt Changes Too\n\ns10-s17's agent_loop used prompt caching to avoid re-serialization. s18 removes the cache:\n\n```python\ndef agent_loop(messages, context):\n    tools, handlers = assemble_tool_pool()     # Rebuild every time\n    system = assemble_system_prompt(context)    # Regenerate every time\n    ...\n    if any(b.name == \"connect_mcp\" ...):\n        tools, handlers = assemble_tool_pool()  # Rebuild after connection\n        system = assemble_system_prompt(context)\n```\n\nAfter `connect_mcp`, the tool pool gains entries such as `mcp__docs__search`. Reusing the old serialized tool list would hide those entries from the model, so the loop rebuilds the pool and system prompt after every connection.\n\n### MCP Tools: Lead Only\n\n`connect_mcp` belongs to the Lead, and `assemble_tool_pool` serves the Lead's agent loop. Teammates keep their task, file, message, and plan tools; the Lead invokes external services and dispatches the resulting work.\n\n---\n\n## Changes from s17\n\n| Component | Before (s17) | After (s18) |\n|------|-----------|-----------|\n| Tool source | All hand-written built-in | Hand-written + MCP external tools with dynamic discovery |\n| Tool pool | Fixed BUILTIN_TOOLS | assemble_tool_pool dynamically assembles mcp\\_\\_ prefixed tools |\n| Name safety | None | normalize_mcp_name normalization |\n| New type | — | MCPClient class (simulates tools/list + tools/call) |\n| Namespace | — | mcp\\_\\_server\\_\\_tool prevents collisions |\n| Tool descriptions | No annotations | (readOnly)/(destructive) annotations |\n| Prompt cache | Yes (since s10) | Removed — tool pool is dynamic, cache goes stale |\n| Lead tools | Worktree and team tools | + connect_mcp and dynamically discovered MCP tools |\n| Teammate tools | Task, file, message, and plan tools | Unchanged |\n| Extension method | Write code to add tools | Standard protocol, implement servers in any language |\n\n---\n\n## Try It Out\n\n```sh\ncd learn-claude-code\npython s18_mcp_plugin/code.py\n```\n\nTry these prompts:\n\n1. `Search the docs for the worktree cleanup policy.`\n2. `Deploy the current project and report the result.`\n3. `What documentation and deployment actions can you perform?`\n\nWhat to observe: After connecting to an MCP server, do tool names have `mcp__docs__` or `mcp__deploy__` prefixes? Are both servers' tools available simultaneously? Do MCP tool descriptions include (readOnly)/(destructive) annotations?\n\n---\n\n## What's Next\n\nThe Agent can now connect external tools through a standard protocol. The first 18 chapters introduced these mechanisms one at a time so each boundary stayed visible.\n\nTools, permissions, hooks, todo, task graph, memory, compact, background work, cron, teams, worktrees, and MCP should all attach to the same loop, not live in separate examples.\n\ns19 Integrated Harness → Combine the mechanisms from s01-s18 into one harness. Many mechanisms, one loop.\n\n\n<!-- translation-sync: zh@v2, en@v2, ja@v0 -->\n"
  },
  {
    "version": "s18",
    "locale": "zh",
    "title": "s18: MCP Tools — 外接工具，标准协议",
    "content": "# s18: MCP Tools — 外接工具，标准协议\n\ns01 → ... → s16 → s17 → `s18` → [s19](/zh/s19) → s20 → s21\n\n> *\"外接工具, 标准协议\"* — 发现、组装、调用，Agent 不需要知道工具是谁写的。\n>\n> **Harness 层**: 插件 — 外部能力通过标准协议接入。\n\n---\n\n## 问题\n\ns01 到 s17，Agent 的所有工具都是手写的——bash、read、write、task、worktree。每个工具的输入验证、执行逻辑、错误处理，都是你一行行写的。\n\n现在你有 3 个外部服务想接入：公司的 Jira API（查 issue、建 ticket）、自建的部署系统（触发 deploy、看日志）、团队的 Notion 知识库（搜文档、建页面）。你不想为每个服务重写一套工具代码。\n\n你需要一个标准协议——外部服务只要实现它，Agent 就能直接调用，不管服务用什么语言写的。\n\n---\n\n## 解决方案\n\n![MCP Architecture](/course-assets/s18_mcp_plugin/mcp-architecture.svg)\n\nMCP（Model Context Protocol）定义了 Agent 如何发现和调用外部工具。核心概念：\n\n| 概念 | 作用 |\n|------|------|\n| MCPClient | Agent 端的客户端，连接 server、发现工具、调用工具 |\n| MCP Server | 外部服务，实现 `tools/list` + `tools/call` |\n| assemble_tool_pool | 把内置工具和 MCP 工具组装成一个工具池 |\n| mcp\\_\\_server\\_\\_tool 命名 | 避免不同 server 的工具名冲突 |\n\n沿用 s17 的 worktree 隔离、自主认领和团队协议。本章新增 `connect_mcp` 工具，用于连接服务、发现工具并加入工具池。\n\n本章注册进程内 server handler，让工具发现和调用流程可以离线运行。每个 handler 都提供客户端需要的 `tools/list` 和 `tools/call` 两个操作。\n\n---\n\n## 工作原理\n\n### MCPClient：发现 + 调用\n\n```python\nclass MCPClient:\n    def __init__(self, name: str):\n        self.name = name\n        self.tools: list[dict] = []\n        self._handlers: dict[str, callable] = {}\n\n    def register(self, tool_defs, handlers):\n        \"\"\"Simulates tools/list discovery.\"\"\"\n        self.tools = tool_defs\n        self._handlers = handlers\n\n    def call_tool(self, tool_name: str, args: dict) -> str:\n        \"\"\"Simulates tools/call.\"\"\"\n        handler = self._handlers.get(tool_name)\n        if not handler:\n            return f\"MCP error: unknown tool '{tool_name}'\"\n        return handler(**args)\n```\n\n注册的 Python 函数提供 `tools/call` 所调用的 server 端工具实现。\n\n### connect_mcp：连接 + 发现\n\n```python\ndef connect_mcp(name: str) -> str:\n    if name in mcp_clients:\n        return f\"MCP server '{name}' already connected\"\n    factory = MOCK_SERVERS.get(name)\n    if not factory:\n        return f\"Unknown server '{name}'. Available: ...\"\n    mcp_client = factory()\n    mcp_clients[name] = mcp_client\n    return f\"Connected to '{name}'. Discovered: ...\"\n```\n\n连接后，server 提供的工具立即可用。\n\n### normalize_mcp_name：名称规范化\n\n```python\n_DISALLOWED_CHARS = re.compile(r'[^a-zA-Z0-9_-]')\n\ndef normalize_mcp_name(name: str) -> str:\n    return _DISALLOWED_CHARS.sub('_', name)\n```\n\n所有非 `[a-zA-Z0-9_-]` 的字符替换为 `_`。防止 server 名或工具名中包含特殊字符导致命名冲突或注入问题。\n\n### assemble_tool_pool：组装工具池\n\n```python\ndef assemble_tool_pool() -> tuple[list[dict], dict]:\n    tools = list(BUILTIN_TOOLS)\n    handlers = dict(BUILTIN_HANDLERS)\n    for server_name, mcp_client in mcp_clients.items():\n        safe_server = normalize_mcp_name(server_name)\n        for tool_def in mcp_client.tools:\n            safe_tool = normalize_mcp_name(tool_def[\"name\"])\n            prefixed = f\"mcp__{safe_server}__{safe_tool}\"\n            tools.append(...)\n            handlers[prefixed] = (\n                lambda *, c=mcp_client, t=tool_def[\"name\"], **kw:\n                    c.call_tool(t, kw))\n    return tools, handlers\n```\n\n前缀 `mcp__{server}__{tool}` 避免不同 server 的工具名冲突。名称经过 `normalize_mcp_name` 规范化。\n\nMCP 工具的 description 带 `(readOnly)` 或 `(destructive)` 标注，让只读操作和修改操作在工具元数据中直接可见。\n\n### 无缓存：工具池变了，prompt 也变\n\ns10-s17 的 agent_loop 用 prompt cache 避免重复序列化。s18 去掉了缓存：\n\n```python\ndef agent_loop(messages, context):\n    tools, handlers = assemble_tool_pool()     # 每次重新构建\n    system = assemble_system_prompt(context)    # 每次重新生成\n    ...\n    if any(b.name == \"connect_mcp\" ...):\n        tools, handlers = assemble_tool_pool()  # 连接后重建\n        system = assemble_system_prompt(context)\n```\n\n`connect_mcp` 之后，工具池会新增 `mcp__docs__search` 等条目。继续复用旧的序列化工具列表，模型就看不到这些工具，所以每次连接后都要重建工具池和 system prompt。\n\n### MCP 工具只有 Lead 可用\n\n`connect_mcp` 属于 Lead，`assemble_tool_pool` 也服务于 Lead 的 agent loop。Teammate 保留任务、文件、消息和计划工具，由 Lead 调用外部服务，再把得到的工作分派下去。\n\n---\n\n## 相对 s17 的变更\n\n| 组件 | 之前 (s17) | 之后 (s18) |\n|------|-----------|-----------|\n| 工具来源 | 全部手写 builtin | 手写 + MCP 外部工具动态发现 |\n| 工具池 | 固定 BUILTIN_TOOLS | assemble_tool_pool 动态组装 mcp\\_\\_ 前缀工具 |\n| 名称安全 | 无 | normalize_mcp_name 规范化 |\n| 新类型 | — | MCPClient 类（模拟 tools/list + tools/call） |\n| 命名空间 | — | mcp\\_\\_server\\_\\_tool 避免冲突 |\n| 工具描述 | 无标注 | (readOnly)/(destructive) 标注 |\n| prompt 缓存 | 有（s10 起） | 去掉——工具池动态变化后缓存失效 |\n| Lead 工具 | worktree 与团队工具 | + connect_mcp 和动态发现的 MCP 工具 |\n| Teammate 工具 | 任务、文件、消息与计划工具 | 不变 |\n| 扩展方式 | 写代码加工具 | 标准协议，任意语言实现 server |\n\n---\n\n## 试一下\n\n```sh\ncd learn-claude-code\npython s18_mcp_plugin/code.py\n```\n\n试试这些 prompt：\n\n1. `查一下文档里的 worktree 清理策略。`\n2. `部署当前项目，并告诉我结果。`\n3. `你现在可以执行哪些文档和部署操作？`\n\n观察重点：连接 MCP server 后，工具名是否带 `mcp__docs__` 或 `mcp__deploy__` 前缀？两个 server 的工具是否同时可用？MCP 工具的 description 是否带 (readOnly)/(destructive) 标注？\n\n---\n\n## 接下来\n\n现在 Agent 可以通过标准协议接入外部工具了。前 18 章逐个引入这些机制，让每个边界都能单独观察。\n\n工具、权限、hooks、todo、任务图、记忆、压缩、后台、cron、团队、worktree、MCP 这些机制应该挂在同一个循环上，而不是散在 19 个 demo 里。\n\ns19 Agent Harness 集成 → 把 s01-s18 的机制合回同一个 harness。机制很多，循环一个。\n\n\n<!-- translation-sync: zh@v2, en@v0, ja@v0 -->\n"
  },
  {
    "version": "s18",
    "locale": "ja",
    "title": "s18: MCP Tools — 外部ツール、標準プロトコル",
    "content": "# s18: MCP Tools — 外部ツール、標準プロトコル\n\ns01 → ... → s16 → s17 → `s18` → [s19](/ja/s19) → s20 → s21\n\n> *\"外部ツール、標準プロトコル\"* — 発見、組み立て、呼び出し。Agent はツールを誰が書いたか知る必要がない。\n>\n> **Harness 層**: プラグイン — 外部能力を標準プロトコルで接続。\n\n---\n\n## 課題\n\ns01 から s17 まで、Agent の全ツールは手書き — bash、read、write、task、worktree。入力検証、実行ロジック、エラーハンドリング、全て一行ずつ書いた。\n\n今、統合したい外部サービスが 3 つある：社内の Jira API（issue 検索、ticket 作成）、独自のデプロイシステム（deploy トリガー、ログ閲覧）、チームの Notion ナレッジベース（ドキュメント検索、ページ作成）。各サービスのためにツールコードを書き直したくない。\n\n標準プロトコルが必要 — 外部サービスがこのプロトコルを実装していれば、サービスが何の言語で書かれていても、Agent は直接そのツールを呼び出せる。\n\n---\n\n## ソリューション\n\n![MCP Architecture](/course-assets/s18_mcp_plugin/mcp-architecture.ja.svg)\n\nMCP（Model Context Protocol）は、Agent が外部ツールを発見・呼び出しする方法を定義。核心概念：\n\n| 概念 | 目的 |\n|------|------|\n| MCPClient | Agent 側のクライアント — server に接続、ツールを発見、ツールを呼び出し |\n| MCP Server | 外部サービス側 — `tools/list` + `tools/call` を実装 |\n| assemble_tool_pool | 組み込みツールと MCP ツールを一つのツールプールに組み立てる |\n| mcp\\_\\_server\\_\\_tool 命名 | 異なる server 間のツール名衝突を防止 |\n\ns17 の worktree 分離、自動認領、チームプロトコルを引き継ぐ。本章では `connect_mcp` ツールを追加し、サービスへの接続、ツール発見、ツールプールへの追加を行う。\n\n本章はプロセス内の server handler を登録し、発見から呼び出しまでをオフラインで実行する。各 handler はクライアントが必要とする `tools/list` と `tools/call` を提供する。\n\n---\n\n## 仕組み\n\n### MCPClient：発見 + 呼び出し\n\n```python\nclass MCPClient:\n    def __init__(self, name: str):\n        self.name = name\n        self.tools: list[dict] = []\n        self._handlers: dict[str, callable] = {}\n\n    def register(self, tool_defs, handlers):\n        \"\"\"Simulates tools/list discovery.\"\"\"\n        self.tools = tool_defs\n        self._handlers = handlers\n\n    def call_tool(self, tool_name: str, args: dict) -> str:\n        \"\"\"Simulates tools/call.\"\"\"\n        handler = self._handlers.get(tool_name)\n        if not handler:\n            return f\"MCP error: unknown tool '{tool_name}'\"\n        return handler(**args)\n```\n\n登録した Python 関数が、`tools/call` から呼ばれる server 側のツール実装になる。\n\n### connect_mcp：接続 + 発見\n\n```python\ndef connect_mcp(name: str) -> str:\n    if name in mcp_clients:\n        return f\"MCP server '{name}' already connected\"\n    factory = MOCK_SERVERS.get(name)\n    if not factory:\n        return f\"Unknown server '{name}'. Available: ...\"\n    mcp_client = factory()\n    mcp_clients[name] = mcp_client\n    return f\"Connected to '{name}'. Discovered: ...\"\n```\n\n接続後、server が提供するツールが即座に利用可能。\n\n### normalize_mcp_name：名前の正規化\n\n```python\n_DISALLOWED_CHARS = re.compile(r'[^a-zA-Z0-9_-]')\n\ndef normalize_mcp_name(name: str) -> str:\n    return _DISALLOWED_CHARS.sub('_', name)\n```\n\n`[a-zA-Z0-9_-]` 以外の全文字を `_` に置換。server 名やツール名の特殊文字による名前衝突やインジェクション問題を防止。\n\n### assemble_tool_pool：ツールプールの組み立て\n\n```python\ndef assemble_tool_pool() -> tuple[list[dict], dict]:\n    tools = list(BUILTIN_TOOLS)\n    handlers = dict(BUILTIN_HANDLERS)\n    for server_name, mcp_client in mcp_clients.items():\n        safe_server = normalize_mcp_name(server_name)\n        for tool_def in mcp_client.tools:\n            safe_tool = normalize_mcp_name(tool_def[\"name\"])\n            prefixed = f\"mcp__{safe_server}__{safe_tool}\"\n            tools.append(...)\n            handlers[prefixed] = (\n                lambda *, c=mcp_client, t=tool_def[\"name\"], **kw:\n                    c.call_tool(t, kw))\n    return tools, handlers\n```\n\nプレフィックス `mcp__{server}__{tool}` で異なる server 間のツール名衝突を防止。名前は `normalize_mcp_name` で正規化。\n\nMCP ツールの description に `(readOnly)` または `(destructive)` を付け、読み取りと変更の区別をツールメタデータ上で明示する。\n\n### キャッシュなし：ツールプールが変われば、プロンプトも変わる\n\ns10-s17 の agent_loop は prompt cache で再シリアライズを回避。s18 はキャッシュを削除：\n\n```python\ndef agent_loop(messages, context):\n    tools, handlers = assemble_tool_pool()     # 毎回再構築\n    system = assemble_system_prompt(context)    # 毎回再生成\n    ...\n    if any(b.name == \"connect_mcp\" ...):\n        tools, handlers = assemble_tool_pool()  # 接続後に再構築\n        system = assemble_system_prompt(context)\n```\n\n`connect_mcp` の後には `mcp__docs__search` などがツールプールへ加わる。古いシリアライズ済みツール一覧を再利用するとモデルから新しいツールが見えないため、接続後にツールプールと system prompt を再構築する。\n\n### MCP ツールは Lead のみ利用可能\n\n`connect_mcp` は Lead のツールであり、`assemble_tool_pool` も Lead の agent loop に使われる。チームメイトはタスク、ファイル、メッセージ、プランの各ツールを保持し、Lead が外部サービスを呼び出して得た仕事を割り当てる。\n\n---\n\n## s17 からの変更\n\n| コンポーネント | 変更前 (s17) | 変更後 (s18) |\n|--------------|------------|------------|\n| ツールソース | 全て手書き builtin | 手書き + MCP 外部ツール動的発見 |\n| ツールプール | 固定 BUILTIN_TOOLS | assemble_tool_pool が動的に mcp\\_\\_ プレフィックスツールを組み立てる |\n| 名前の安全性 | なし | normalize_mcp_name 正規化 |\n| 新規タイプ | — | MCPClient クラス（tools/list + tools/call をシミュレート） |\n| 名前空間 | — | mcp\\_\\_server\\_\\_tool 衝突防止 |\n| ツール説明 | アノテーションなし | (readOnly)/(destructive) アノテーション |\n| プロンプトキャッシュ | あり（s10 から） | 削除 — ツールプールが動的、キャッシュが陳腐化 |\n| Lead ツール | worktree・チームツール | + connect_mcp と動的に発見した MCP ツール |\n| チームメイトツール | タスク、ファイル、メッセージ、プランのツール | 変更なし |\n| 拡張方法 | ツール追加のコードを書く | 標準プロトコル、任意言語で server を実装 |\n\n---\n\n## 試してみる\n\n```sh\ncd learn-claude-code\npython s18_mcp_plugin/code.py\n```\n\n以下のプロンプトを試してください：\n\n1. `ドキュメントから worktree のクリーンアップ方針を調べてください。`\n2. `現在のプロジェクトをデプロイし、結果を報告してください。`\n3. `現在実行できるドキュメント操作とデプロイ操作を教えてください。`\n\n観察ポイント：MCP server 接続後、ツール名に `mcp__docs__` や `mcp__deploy__` プレフィックスが付いているか？両方の server のツールが同時に利用可能か？MCP ツールの description に (readOnly)/(destructive) アノテーションが付いているか？\n\n---\n\n## 次の章\n\nAgent は標準プロトコルで外部ツールに接続できるようになった。前 18 章では、各境界を観察できるように仕組みを一つずつ追加してきた。\n\ntools、permissions、hooks、todo、task graph、memory、compact、background work、cron、teams、worktree、MCP は、別々の例ではなく同じ loop に接続されるべきです。\n\ns19 Integrated Harness → s01-s18 の仕組みを 1 つの harness に統合。仕組みは多く、loop は 1 つ。\n\n\n<!-- translation-sync: zh@v2, en@v2, ja@v2 -->\n"
  },
  {
    "version": "s19",
    "locale": "en",
    "title": "s19: Integrated Harness — Many Mechanisms, One Loop",
    "content": "# s19: Integrated Harness — Many Mechanisms, One Loop\n\ns01 → ... → s17 → s18 → `s19` → [s20](/en/s20) → s21\n\n> *\"Many mechanisms, one loop\"* — tools, permissions, memory, tasks, teams, and plugins all hang off the same `while True`.\n>\n> **Harness layer**: Integration — put the mechanisms from s01-s18 into one runnable system.\n\n---\n\n## Problem\n\nThe first 18 chapters add one mechanism at a time so each boundary stays visible. This chapter connects them in one runtime.\n\nA long-running coding agent needs all of these at once:\n\n- tool dispatch and permission boundaries\n- hook extension points\n- todo planning and task graphs\n- skills, memory, and runtime system prompt assembly\n- compaction and error recovery\n- background tasks and cron scheduling\n- teams, protocols, autonomous claiming\n- worktree isolation\n- MCP external tool integration\n\nThe hard part is not piling up features. The hard part is seeing where each mechanism belongs around the loop. S19 is the integration checkpoint: every earlier component is placed back into one harness before s20-s21 add orchestration and goal closure around it.\n\n---\n\n## Solution\n\n![System Architecture](/course-assets/s19_comprehensive/system-architecture.en.svg)\n\nS19 does not introduce a new mechanism. It connects the components from the earlier chapters in one integrated harness:\n\n```text\nuser input\n  → UserPromptSubmit hooks\n  → cron/background notification injection\n  → context compact\n  → memory + skills + MCP state assemble the system prompt\n  → LLM\n  → has tool_use block?\n      no  → Stop hooks → return\n      yes → PreToolUse hooks + permission\n          → TOOL_HANDLERS / MCP handlers / background dispatch\n          → PostToolUse hooks\n          → tool_result / task_notification back to messages\n          → next round\n```\n\nThe loop keeps the same structure: call the model, check whether the response contains a `tool_use` block, execute tools, and append results to `messages`. The presence of a `tool_use` block decides whether tool execution continues.\n\n---\n\n## Where Each Component Sits\n\n| Position | Component | Role |\n|----------|-----------|------|\n| Around user input | `UserPromptSubmit` hooks | Log, inject, or audit user input |\n| Before LLM | cron queue | Inject scheduled prompts into `messages` |\n| Before LLM | background notifications | Inject completed background work as `<task_notification>` |\n| Before LLM | compaction pipeline | Budget large outputs, trim history, compact old tool results, summarize when needed |\n| Before LLM | memory / skills / MCP state | Assemble the system prompt so the model sees current capabilities and long-term context |\n| LLM call | error recovery | Retry 429/529, escalate `max_tokens`, compact on prompt-too-long |\n| Before tool execution | `PreToolUse` hooks + permission | Block dangerous commands, out-of-bounds writes, destructive MCP tools |\n| Tool dispatch | `assemble_tool_pool` | Assemble built-in tools and dynamic MCP tools |\n| During tool execution | background dispatch | Move slow bash work into a daemon thread and return a placeholder result |\n| After tool execution | `PostToolUse` hooks | Large-output warnings, logs, post-processing |\n| Back to loop | tool_result | One `tool_result` per `tool_use`, then the next model round |\n| No tool_use this round / on stop | `Stop` hooks | Stats, cleanup, audit |\n\n---\n\n## What code.py Contains\n\n### Tools and Dispatch\n\nThe built-in tool pool contains 26 tools:\n\n```text\nbash, read_file, write_file, edit_file, glob\ntodo_write, task, load_skill, compact\ncreate_task, list_tasks, get_task, claim_task, complete_task\nschedule_cron, list_crons, cancel_cron\nspawn_teammate, send_message\nrequest_shutdown, request_plan, review_plan\ncreate_worktree, remove_worktree, keep_worktree\nconnect_mcp\n```\n\n`assemble_tool_pool()` assembles these every round:\n\n```text\nBUILTIN_TOOLS + connected MCP tools\nBUILTIN_HANDLERS + mcp__server__tool handlers\n```\n\nAfter `connect_mcp(\"docs\")`, the next round exposes tools like `mcp__docs__search`.\n\n### Permissions and Hooks\n\nPermission is not hardcoded into the tool execution line. It is a `PreToolUse` hook:\n\n```python\nblocked = trigger_hooks(\"PreToolUse\", block)\nif blocked:\n    results.append(tool_result(block.id, blocked))\n    continue\n```\n\nThat means permission, logging, and audit logic all attach to the same hook point. After execution, `PostToolUse` hooks run.\n\n### Planning and Tasks\n\nS19 keeps two planning layers:\n\n- `todo_write`: lightweight plan for the current session, kept in memory\n- task graph: cross-session, dependency-aware, claimable task files under `.tasks/task_*.json`\n\nThe first keeps a single agent from drifting. The second supports team coordination.\n\nThey share an intent, not an implementation: `todo_write` replaces one session checklist, while task records have stable IDs and individual lifecycle updates. The separate `task` tool below means \"dispatch one isolated subagent\"; it is not the Task System.\n\n### Subagents and Teams\n\nS19 has two kinds of delegation:\n\n- `task`: one-shot subagent. It uses an isolated `messages[]`, discards intermediate context, and returns only a final summary.\n- `spawn_teammate`: persistent teammate thread. The runtime delivers `MessageBus` events, and the teammate scans the task board while idle so it can claim work autonomously.\n\nOne-shot subagents solve context isolation. Persistent teammates solve long-running parallel collaboration.\n\n### Memory, Skills, and Prompt\n\n`assemble_system_prompt(context)` assembles each round from:\n\n- identity and tool guidance\n- workspace\n- skills catalog\n- `.memory/MEMORY.md`\n- connected MCP servers\n\nSkills only put their catalog into the system prompt. Full content is loaded on demand through `load_skill(name)`.\n\n### Compaction and Recovery\n\nBefore the LLM call, S19 runs the compaction pipeline:\n\n```text\ntool_result_budget → snip_compact → micro_compact → compact_history\n```\n\nThe model call is wrapped with recovery:\n\n- 429: exponential backoff retry\n- 529: exponential backoff, optionally switch to fallback model after repeated failures\n- `max_tokens`: raise max tokens, then request continuation\n- prompt too long: reactive compact and retry\n\n### Background and Cron\n\nSlow bash work does not block the main loop:\n\n```text\nshould_run_background → start_background_task → placeholder tool_result\nbackground done → task_notification → next round injects messages\n```\n\nThe cron scheduler runs as a daemon thread and checks once per second. The CLI watches `cron_queue`; when a job fires, it injects `[Scheduled] ...` and runs one agent turn automatically.\n\n### Worktree and MCP\n\nWorktree isolation owns directories:\n\n- `create_worktree(name, task_id)` creates an isolated branch and directory\n- the task `worktree` field binds a task to that directory\n- when a teammate claims a task with a worktree, its bash/read/write tools run in that directory\n\nMCP owns external capability:\n\n- `connect_mcp(name)` connects a mock server\n- `assemble_tool_pool()` assembles MCP tools into the tool pool\n- tool names use `mcp__server__tool`\n\n---\n\n## Changes from s18\n\n| Component | s18 | s19 |\n|-----------|-----|-----|\n| tool pool | built-in + MCP | built-in + MCP, with s01-s17 tools restored |\n| permission | outside s18's scope | runs inside `PreToolUse` hook |\n| hooks | outside s18's scope | UserPromptSubmit / PreToolUse / PostToolUse / Stop |\n| todo | outside s18's scope | `todo_write` + reminder |\n| skill | outside s18's scope | catalog in system prompt + `load_skill` |\n| compact | outside s18's scope | pre-LLM compaction + `compact` tool + reactive compact |\n| error recovery | simple try/except | retry / max_tokens / prompt too long |\n| background | outside s18's scope | slow-operation thread + task notification |\n| cron | outside s18's scope | daemon scheduler + durable jobs |\n| multi-agent | kept | kept; teammates use basic tools in isolated directories |\n| worktree | kept | kept |\n| MCP | new | kept as part of the final tool pool |\n\n---\n\n## Try It\n\n```sh\ncd learn-claude-code\npython s19_comprehensive/code.py\n```\n\nTry:\n\n1. `Inspect this repository and tell me which Python files matter most.`\n2. `Search the connected documentation for agent loop guidance.`\n3. `Refactor the authentication module and login page in parallel in isolated worktrees. Show me each plan before editing.`\n4. `Remind me about the meeting in 3 minutes.`\n5. `Install the dependencies in the background while you read README.md.`\n\nWatch for:\n\n- whether each tool call passes through hooks/permission\n- whether MCP tools appear on the next round after `connect_mcp`\n- whether slow operations return a background placeholder\n- whether cron automatically reminds you when the time arrives\n- whether teammates submit plans and pause before approval\n- whether teammates can claim tasks after plan approval\n- whether teammates switch to the bound worktree directory\n\n---\n\n## The End Is the Beginning\n\nFrom s01 to s19, the code gets more capable, but the core remains unchanged:\n\n```python\nwhile True:\n    response = LLM(messages, tools)\n    if not has_tool_use(response.content):\n        return\n    results = execute_tools(response.content)\n    messages.append(tool_results)\n```\n\nA mature harness gets its complexity from coordination around the model. The model chooses actions; the harness organizes the environment, tools, permissions, memory, teams, and external capabilities.\n\nThis is the course's integration checkpoint: many mechanisms, one loop.\n\nNext: [s20 Workflow Runtime](/en/s20) — when the orchestration shape is fixed, move it out of chat turns and into deterministic, resumable code.\n"
  },
  {
    "version": "s19",
    "locale": "zh",
    "title": "s19: Agent Harness 集成 — 多种机制，一个循环",
    "content": "# s19: Agent Harness 集成 — 多种机制，一个循环\n\ns01 → ... → s17 → s18 → `s19` → [s20](/zh/s20) → s21\n\n> *\"机制很多，循环一个\"* — 工具、权限、记忆、任务、团队、插件都挂在同一个 while True 上。\n>\n> **Harness 层**: 集成 — 把 s01-s18 的机制放回同一个可运行系统。\n\n---\n\n## 问题\n\n前 18 章每章只加一个机制，让每个边界都能单独观察。本章把它们接入同一个运行时。\n\n一个能长期工作的 coding agent 需要同时拥有：\n\n- 工具分发和权限边界\n- hooks 扩展点\n- todo 计划和任务图\n- 技能、记忆、系统 prompt 组装\n- 压缩和错误恢复\n- 后台任务和 cron 调度\n- 团队、协议、自治认领\n- worktree 隔离\n- MCP 外部工具接入\n\n难点不是把功能堆起来，而是看清楚它们都挂在循环的哪个位置。S19 是集成检查点：先把此前组件归位，再由 s20-s21 在外层加入编排与目标闭环。\n\n---\n\n## 解决方案\n\n![System Architecture](/course-assets/s19_comprehensive/system-architecture.svg)\n\nS19 不再引入新机制，而是把前面各章的组件集成到同一个 harness：\n\n```text\n用户输入\n  → UserPromptSubmit hooks\n  → cron/background 通知注入\n  → context compact\n  → memory + skills + MCP 状态组装 system prompt\n  → LLM\n  → has tool_use block?\n      否 → Stop hooks → 返回\n      是 → PreToolUse hooks + permission\n          → TOOL_HANDLERS / MCP handlers / background dispatch\n          → PostToolUse hooks\n          → tool_result / task_notification 回 messages\n          → 下一轮\n```\n\n循环仍是同一个结构：调用模型，检查响应里是否出现 `tool_use` block，执行工具，再把结果追加回 `messages`。是否继续工具轮，由响应中有没有实际的 `tool_use` block 决定。\n\n---\n\n## 组件在循环中的位置\n\n| 位置 | 组件 | 作用 |\n|------|------|------|\n| 用户输入前后 | `UserPromptSubmit` hooks | 记录、注入、审计用户输入 |\n| LLM 前 | cron queue | 把定时触发的 prompt 注入 `messages` |\n| LLM 前 | background notifications | 后台任务完成后以 `<task_notification>` 注入 |\n| LLM 前 | compaction pipeline | 先压大输出，再裁历史，再压旧 tool_result，必要时摘要 |\n| LLM 前 | memory / skills / MCP state | 组装 system prompt，让模型看到当前能力和长期上下文 |\n| LLM 调用 | error recovery | 429/529 重试，`max_tokens` 升级，prompt too long 触发 reactive compact |\n| 工具执行前 | `PreToolUse` hooks + permission | 拦截危险命令、写越界、破坏性 MCP 工具 |\n| 工具分发 | `assemble_tool_pool` | 组装内置工具和 MCP 动态工具 |\n| 工具执行时 | background dispatch | 慢 bash 操作放 daemon thread，主循环先返回占位结果 |\n| 工具执行后 | `PostToolUse` hooks | 大输出告警、日志等后处理 |\n| 返回循环 | tool_result | 每个 `tool_use` 对应一个 `tool_result`，再回到下一轮 |\n| 本轮没有 tool_use / 停止时 | `Stop` hooks | 统计、清理、审计 |\n\n---\n\n## code.py 包含什么\n\n### 工具与分发\n\n内置工具池包含 26 个工具：\n\n```text\nbash, read_file, write_file, edit_file, glob\ntodo_write, task, load_skill, compact\ncreate_task, list_tasks, get_task, claim_task, complete_task\nschedule_cron, list_crons, cancel_cron\nspawn_teammate, send_message\nrequest_shutdown, request_plan, review_plan\ncreate_worktree, remove_worktree, keep_worktree\nconnect_mcp\n```\n\n`assemble_tool_pool()` 每轮组装：\n\n```text\nBUILTIN_TOOLS + connected MCP tools\nBUILTIN_HANDLERS + mcp__server__tool handlers\n```\n\n所以 `connect_mcp(\"docs\")` 后，下一轮工具池里会出现 `mcp__docs__search`。\n\n### 权限和 hooks\n\n权限不写死在工具执行行里，而是作为 `PreToolUse` hook：\n\n```python\nblocked = trigger_hooks(\"PreToolUse\", block)\nif blocked:\n    results.append(tool_result(block.id, blocked))\n    continue\n```\n\n这样 permission、log、审计都可以挂在同一个 hook 点上。执行后再触发 `PostToolUse`。\n\n### 计划与任务\n\nS19 同时保留两层计划：\n\n- `todo_write`：当前会话内的轻量计划，保存在内存中\n- task graph：跨会话、可依赖、可认领的任务文件，写入 `.tasks/task_*.json`\n\n前者帮助单个 Agent 不漂移；后者支撑团队协作。\n\n两者目标相近，但实现不同：`todo_write` 整表替换当前会话清单，task record 则有稳定 ID 和单条生命周期更新。下面单独出现的 `task` 工具表示“一次性派发隔离 subagent”，不是 Task System。\n\n### 子 agent 与团队\n\nS19 有两种 delegation：\n\n- `task`：一次性 subagent。独立 `messages[]`，中间过程丢弃，只返回最终摘要。\n- `spawn_teammate`：持久队友线程。运行时自动投递 MessageBus 事件，队友在 idle 时扫描任务板并自主认领。\n\n一次性 subagent 解决“上下文隔离”；持久队友解决“长期并行协作”。\n\n### 记忆、技能和 prompt\n\n`assemble_system_prompt(context)` 每轮组装：\n\n- 身份和工具说明\n- workspace\n- skills catalog\n- `.memory/MEMORY.md`\n- 已连接 MCP server\n\n技能只在 system prompt 里放目录。完整内容通过 `load_skill(name)` 按需加载。\n\n### 压缩和恢复\n\nLLM 前先跑压缩管线：\n\n```text\ntool_result_budget → snip_compact → micro_compact → compact_history\n```\n\n调用模型时再包一层恢复：\n\n- 429：指数退避重试\n- 529：指数退避，连续失败可切 fallback model\n- `max_tokens`：先提高 max_tokens，再要求 continuation\n- prompt too long：reactive compact 后重试\n\n### 后台和 cron\n\n慢 bash 操作不会阻塞主循环：\n\n```text\nshould_run_background → start_background_task → placeholder tool_result\n后台完成 → task_notification → 下一轮注入 messages\n```\n\ncron 调度器独立 daemon thread 每秒检查一次。CLI 会监听 `cron_queue`，命中后主动把 `[Scheduled] ...` 注入并运行一轮 Agent。\n\n### worktree 与 MCP\n\nworktree 负责隔离目录：\n\n- `create_worktree(name, task_id)` 创建独立分支和目录\n- task 的 `worktree` 字段绑定目录\n- 队友 claim 到带 worktree 的 task 后，bash/read/write 自动在对应目录下执行\n\nMCP 负责外部能力：\n\n- `connect_mcp(name)` 连接 mock server\n- `assemble_tool_pool()` 把 MCP 工具组装进工具池\n- 工具名统一为 `mcp__server__tool`\n\n---\n\n## 相对 s18 的变化\n\n| 组件 | s18 | s19 |\n|------|-----|-----|\n| 工具池 | 内置 + MCP | 内置 + MCP，补齐 s01-s17 的工具 |\n| 权限 | 不在 s18 范围内 | `PreToolUse` hook 中执行 |\n| hooks | 不在 s18 范围内 | UserPromptSubmit / PreToolUse / PostToolUse / Stop |\n| todo | 不在 s18 范围内 | `todo_write` + reminder |\n| skill | 不在 s18 范围内 | catalog in system prompt + `load_skill` |\n| compact | 不在 s18 范围内 | LLM 前压缩 + `compact` 工具 + reactive compact |\n| error recovery | 简化 try/except | retry / max_tokens / prompt too long |\n| background | 不在 s18 范围内 | 慢操作后台线程 + task notification |\n| cron | 不在 s18 范围内 | daemon scheduler + durable jobs |\n| multi-agent | 保留 | 保留；队友使用隔离目录下的基础工具 |\n| worktree | 保留 | 保留 |\n| MCP | 新增 | 保留，作为最终工具池的一部分 |\n\n---\n\n## 试一下\n\n```sh\ncd learn-claude-code\npython s19_comprehensive/code.py\n```\n\n可以试：\n\n1. `检查这个仓库，告诉我哪些 Python 文件最重要。`\n2. `从已连接的文档中查一下 agent loop 的相关说明。`\n3. `请在隔离的 worktree 中并行重构认证模块和登录页，修改前先把各自的计划给我看。`\n4. `3 分钟后提醒我开会。`\n5. `在后台安装依赖，同时继续阅读 README.md。`\n\n观察重点：\n\n- 工具调用前是否经过 hooks/permission\n- `connect_mcp` 后下一轮是否出现 MCP 工具\n- 慢操作是否返回 background placeholder\n- 到点是不是自动提醒开会\n- 队友是否提交 plan，并在 approval 前暂停\n- plan 批准后，队友是否能认领任务\n- worktree 绑定后，队友是否切到对应目录\n\n---\n\n## 结束亦是开始\n\n从 s01 到 s19，代码表面越来越复杂，但核心始终没变：\n\n```python\nwhile True:\n    response = LLM(messages, tools)\n    if not has_tool_use(response.content):\n        return\n    results = execute_tools(response.content)\n    messages.append(tool_results)\n```\n\n成熟 harness 的复杂性来自模型周围的协作机制。模型负责判断和行动选择，harness 负责组织环境、工具、权限、记忆、团队和外部能力。\n\n这是课程的集成检查点：机制很多，循环一个。\n\n下一章：[s20 Workflow Runtime](/zh/s20) — 当编排形状固定时，把它从多轮对话移入确定性、可恢复的代码。\n"
  },
  {
    "version": "s19",
    "locale": "ja",
    "title": "s19: Integrated Harness — 多くの仕組みを 1 つのループへ",
    "content": "# s19: Integrated Harness — 多くの仕組みを 1 つのループへ\n\ns01 → ... → s17 → s18 → `s19` → [s20](/ja/s20) → s21\n\n> *\"仕組みは多い、ループは 1 つ\"* — tools、permissions、memory、tasks、teams、plugins はすべて同じ `while True` に接続される。\n>\n> **Harness レイヤー**: 統合 — s01-s18 の仕組みを 1 つの実行可能なシステムへ戻す。\n\n---\n\n## 問題\n\n前 18 章では、各境界を観察できるように仕組みを一つずつ追加した。本章では、それらを一つのランタイムへ接続する。\n\n長時間動く coding agent には、同時に次のものが必要になる：\n\n- tool dispatch と permission boundary\n- hook extension point\n- todo plan と task graph\n- skill、memory、runtime system prompt assembly\n- compaction と error recovery\n- background task と cron scheduling\n- team、protocol、autonomous claiming\n- worktree isolation\n- MCP external tool integration\n\n難しいのは機能を積み上げることではない。それぞれの仕組みが loop のどこに接続されるかを見抜くことだ。S19 は統合チェックポイントであり、これまでの component を 1 つの harness に戻してから、s20-s21 が編成と目標完了を外側に追加する。\n\n---\n\n## 解決策\n\n![System Architecture](/course-assets/s19_comprehensive/system-architecture.ja.svg)\n\nS19 は新しい mechanism を追加せず、前章までの component を同じ harness に統合する：\n\n```text\nuser input\n  → UserPromptSubmit hooks\n  → cron/background notification injection\n  → context compact\n  → memory + skills + MCP state で system prompt を組み立てる\n  → LLM\n  → has tool_use block?\n      no  → Stop hooks → return\n      yes → PreToolUse hooks + permission\n          → TOOL_HANDLERS / MCP handlers / background dispatch\n          → PostToolUse hooks\n          → tool_result / task_notification を messages へ戻す\n          → next round\n```\n\nloop 自体は同じ構造のままだ。model を呼び、response に `tool_use` block があるかを見て、tool を実行し、結果を `messages` に戻す。tool 実行を続けるかどうかは、実際の `tool_use` block の有無で決まる。\n\n---\n\n## 各 Component の位置\n\n| 位置 | Component | 役割 |\n|------|-----------|------|\n| user input 周辺 | `UserPromptSubmit` hooks | user input の記録、注入、監査 |\n| LLM 前 | cron queue | scheduled prompt を `messages` へ注入 |\n| LLM 前 | background notifications | 完了した background work を `<task_notification>` として注入 |\n| LLM 前 | compaction pipeline | 大きな出力を予算化し、履歴を切り、古い tool_result を圧縮し、必要なら要約 |\n| LLM 前 | memory / skills / MCP state | current capabilities と long-term context を system prompt に組み込む |\n| LLM call | error recovery | 429/529 retry、`max_tokens` escalation、prompt-too-long compact |\n| tool 実行前 | `PreToolUse` hooks + permission | 危険な command、範囲外 write、destructive MCP tool を止める |\n| tool dispatch | `assemble_tool_pool` | built-in tools と dynamic MCP tools を組み立てる |\n| tool 実行中 | background dispatch | 遅い bash work を daemon thread に逃がし、placeholder result を返す |\n| tool 実行後 | `PostToolUse` hooks | large-output warning、log、後処理 |\n| loop へ戻る | tool_result | 1 つの `tool_use` に 1 つの `tool_result`、そして次の model round |\n| tool_use がない round / stop 時 | `Stop` hooks | 統計、cleanup、audit |\n\n---\n\n## code.py に含まれるもの\n\n### Tools と Dispatch\n\nbuilt-in tool pool には 26 個の tool がある：\n\n```text\nbash, read_file, write_file, edit_file, glob\ntodo_write, task, load_skill, compact\ncreate_task, list_tasks, get_task, claim_task, complete_task\nschedule_cron, list_crons, cancel_cron\nspawn_teammate, send_message\nrequest_shutdown, request_plan, review_plan\ncreate_worktree, remove_worktree, keep_worktree\nconnect_mcp\n```\n\n`assemble_tool_pool()` は毎 round で次を組み立てる：\n\n```text\nBUILTIN_TOOLS + connected MCP tools\nBUILTIN_HANDLERS + mcp__server__tool handlers\n```\n\n`connect_mcp(\"docs\")` のあと、次の round では `mcp__docs__search` のような tool が出現する。\n\n### Permission と Hooks\n\npermission は tool 実行行に直接埋め込まない。`PreToolUse` hook として扱う：\n\n```python\nblocked = trigger_hooks(\"PreToolUse\", block)\nif blocked:\n    results.append(tool_result(block.id, blocked))\n    continue\n```\n\nこれにより permission、logging、audit が同じ hook point に接続できる。実行後には `PostToolUse` hook が走る。\n\n### Plan と Task\n\nS19 には 2 層の plan がある：\n\n- `todo_write`: current session 用の軽量 plan。メモリに保持。\n- task graph: cross-session、dependency-aware、claimable な task file。`.tasks/task_*.json` に保存。\n\n前者は単独 agent の drift を防ぐ。後者は team coordination の土台になる。\n\n目的は近いが実装は別である。`todo_write` は現在のセッションのチェックリスト全体を置き換え、task record は安定 ID と個別のライフサイクル更新を持つ。次節の独立した `task` ツールは「隔離 subagent を一度派遣する」意味であり、Task System ではない。\n\n### Subagent と Team\n\nS19 には 2 種類の delegation がある：\n\n- `task`: one-shot subagent。独立した `messages[]` を使い、中間 context を捨て、final summary だけ返す。\n- `spawn_teammate`: persistent teammate thread。ランタイムが `MessageBus` event を自動配信し、teammate は idle 中に task board を確認して自律的に claim できる。\n\none-shot subagent は context isolation を解決する。persistent teammate は長期並列協作を解決する。\n\n### Memory、Skills、Prompt\n\n`assemble_system_prompt(context)` は毎 round 次を組み立てる：\n\n- identity と tool guidance\n- workspace\n- skills catalog\n- `.memory/MEMORY.md`\n- connected MCP servers\n\nskills は system prompt には catalog だけ置く。全文は `load_skill(name)` で必要な時に読む。\n\n### Compaction と Recovery\n\nLLM call の前に compaction pipeline を走らせる：\n\n```text\ntool_result_budget → snip_compact → micro_compact → compact_history\n```\n\nmodel call は recovery で包む：\n\n- 429: exponential backoff retry\n- 529: exponential backoff、連続失敗時は fallback model へ切替可能\n- `max_tokens`: max tokens を上げ、その後 continuation を要求\n- prompt too long: reactive compact 後に retry\n\n### Background と Cron\n\n遅い bash work は main loop を止めない：\n\n```text\nshould_run_background → start_background_task → placeholder tool_result\nbackground done → task_notification → next round injects messages\n```\n\ncron scheduler は daemon thread として動き、1 秒ごとに確認する。CLI は `cron_queue` を監視し、発火した job を `[Scheduled] ...` として注入して Agent を 1 turn 自動実行する。\n\n### Worktree と MCP\n\nworktree isolation は directory を担当する：\n\n- `create_worktree(name, task_id)` が isolated branch と directory を作る\n- task の `worktree` field が task と directory を紐付ける\n- teammate が worktree 付き task を claim すると、bash/read/write はその directory で実行される\n\nMCP は external capability を担当する：\n\n- `connect_mcp(name)` が mock server に接続する\n- `assemble_tool_pool()` が MCP tools を tool pool に組み立てる\n- tool name は `mcp__server__tool` 形式に統一する\n\n---\n\n## s18 からの変化\n\n| Component | s18 | s19 |\n|-----------|-----|-----|\n| tool pool | built-in + MCP | built-in + MCP、s01-s17 の tool を補完 |\n| permission | s18 の対象外 | `PreToolUse` hook で実行 |\n| hooks | s18 の対象外 | UserPromptSubmit / PreToolUse / PostToolUse / Stop |\n| todo | s18 の対象外 | `todo_write` + reminder |\n| skill | s18 の対象外 | system prompt の catalog + `load_skill` |\n| compact | s18 の対象外 | LLM 前 compaction + `compact` tool + reactive compact |\n| error recovery | simple try/except | retry / max_tokens / prompt too long |\n| background | s18 の対象外 | slow-operation thread + task notification |\n| cron | s18 の対象外 | daemon scheduler + durable jobs |\n| multi-agent | 維持 | 維持。teammate は isolated directory 上の basic tools を使う |\n| worktree | 維持 | 維持 |\n| MCP | 新規 | final tool pool の一部として維持 |\n\n---\n\n## 試す\n\n```sh\ncd learn-claude-code\npython s19_comprehensive/code.py\n```\n\n試す prompt：\n\n1. `このリポジトリを調べ、重要な Python ファイルを教えてください。`\n2. `接続済みのドキュメントから agent loop の説明を探してください。`\n3. `認証モジュールとログインページを隔離した worktree で並行してリファクタリングし、編集前にそれぞれのプランを見せてください。`\n4. `3 分後に会議を知らせてください。`\n5. `依存関係をバックグラウンドでインストールしながら README.md を読んでください。`\n\n見るポイント：\n\n- tool call の前に hooks/permission を通るか\n- `connect_mcp` 後の次 round で MCP tool が出るか\n- 遅い operation が background placeholder を返すか\n- cron が時刻到達時に自動で reminder を返すか\n- teammate が plan を提出し、approval 前に停止するか\n- plan approval 後、teammate が task を claim できるか\n- worktree binding 後、teammate が対応 directory に切り替わるか\n\n---\n\n## 終わりは始まり\n\ns01 から s19 まで、コードの能力は増えていく。しかし中心は変わらない：\n\n```python\nwhile True:\n    response = LLM(messages, tools)\n    if not has_tool_use(response.content):\n        return\n    results = execute_tools(response.content)\n    messages.append(tool_results)\n```\n\n成熟した harness の複雑さは model 周辺の協調機構から生まれる。model は判断と action selection を担当し、harness は environment、tools、permissions、memory、teams、external capabilities を整理する。\n\nこれは本コースの統合チェックポイントだ：仕組みは多い、ループは 1 つ。\n\n次へ：[s20 Workflow Runtime](/ja/s20) — 編成の形が固定なら、多数の会話ターンではなく、決定的で再開可能なコードへ移す。\n"
  },
  {
    "version": "s20",
    "locale": "en",
    "title": "s20: Workflow Runtime — The Model Decides Each Step; a Script Decides the Orchestration",
    "content": "# s20: Workflow Runtime — The Model Decides Each Step; a Script Decides the Orchestration\n\ns01 → ... → s18 → s19 → `s20` → [s21](/en/s21)\n\n> *\"One tool_use starts an entire orchestration in the background\"* — The `Workflow` tool starts a deterministic, recoverable script runtime that dispatches many subagents in bulk.\n>\n> **Harness layer**: Orchestration — a deterministic multi-agent script runtime above the single-agent loop.\n\n`code.py` keeps the demo deterministic: it emits `async_launched` and then awaits completion in one process. This demonstrates the lifecycle and journal without requiring a long-running background service.\n\n---\n\nFrom s01 through s19, our loop has always been model-driven and step-by-step: the model chooses one tool each round, its result enters `messages[]`, and another round begins. That is ideal for open-ended tasks because the model can inspect the current context and decide the next step on the spot.\n\nSome jobs, however, require deterministic command of a group of agents. Consider reviewing a large change: inspect ten dimensions in parallel → send each finding to a separate agent for adversarial verification → combine and deduplicate the results → sort by severity. The shape is fixed, and you really need three properties:\n\n- **Parallelism**, rather than waiting for one item at a time;\n- **Determinism**, so the same input produces the same result structure;\n- **Recoverability**, so an interruption does not rerun work that is already complete.\n\nMaking the model drive this process one round at a time in the main loop is slow and nondeterministic, and an interruption starts everything over. At that point, you do not need \"one more conversation turn.\" You need to encode the orchestration directly as code.\n\n## Put the Plan in Code, Not in a Sequence of Chat Turns\n\nAdd a `Workflow` tool to the harness tool pool. The user or model provides a script that expresses deterministic orchestration through a few simple primitives: `agent()`, `parallel()`, `pipeline()`, and `phase()`.\n\nThe main loop sees only one `tool_use` and immediately receives a \"started in the background\" result. Real execution continues inside the background runtime, which reports progress in real time and records every step in a journal on disk. Intermediate script results live in variables instead of taking space in conversation history. When restarted with `resume_from_run_id`, unchanged `agent()` calls hit the journal cache and reuse previous results, resuming from the checkpoint.\n\n![Workflow Runtime Overview](/course-assets/s20_workflow_runtime/workflow-runtime-overview.svg)\n\n```python\nSAMPLE_META = {\"name\": \"review-changes\", \"description\": \"Review code changes\", \"phases\": [\"Review\", \"Verify\"]}\n\nasync def sample_workflow(ctx, args):\n    ctx.phase(\"Review\")\n    results = await ctx.pipeline(DIMENSIONS, audit, verify)   # Each dimension independently runs audit → verify\n    confirmed = [f for r in results if r for f in r[\"confirmed\"]]\n    ctx.log(f\"Confirmed {len(confirmed)} real issues\")\n    return {\"confirmed\": confirmed}\n```\n\n## The Workflow Tool: Start in the Background; the Main Loop Sees One Call\n\n`Workflow` lives in the main agent's tool pool. The user can request a saved workflow, or the model can select the tool when a task matches a known orchestration. In either case, the model emits one `Workflow(...)` tool call.\n\nThe tool parses the arguments, validates metadata, checks permissions, registers a local workflow task, and immediately returns \"started asynchronously.\" The main loop does not block and can continue with other work while the workflow runs in the background. This is the claim-ticket pattern from s13 at a larger scale: hand over the ticket now, notify the user when the result is ready.\n\n```python\nclass WorkflowTool:\n    async def call(self, meta, script_fn, args=None, resume_from_run_id=None):\n        validate_meta(meta)\n        check_permission(meta)\n        run_id = resume_from_run_id or create_run_id(meta)\n        task = LocalWorkflowTask(create_task_id(run_id), run_id, meta)\n        task.event(\"async_launched\", runId=run_id, taskId=task.task_id)   # Return immediately\n        ...                                                                # The rest proceeds in the background\n```\n\n## Workflow Metadata: Validate Before Launch\n\nEach workflow registers a metadata object with `name`, `description`, and optional `phases`. The runtime validates it before executing any workflow code. `name` and `description` identify the task in the UI, while `phases` names groups in the progress display.\n\nInvalid input raises `WorkflowInputError` immediately and is rejected during registration. This is the same idea as validating cron expressions in s14: do not wait until execution to discover a bad script.\n\nBecause the runtime uses `meta.name` in local artifact filenames, it also requires a 1-64 character safe slug containing letters, numbers, `.`, `_`, or `-`.\n\n```python\ndef validate_meta(meta):\n    if not isinstance(meta, dict):\n        raise WorkflowInputError(\"meta must be an object literal\")\n    if not meta.get(\"name\") or not meta.get(\"description\"):\n        raise WorkflowInputError(\"meta requires name and description\")\n    if not isinstance(meta[\"name\"], str) or not WORKFLOW_NAME_RE.fullmatch(meta[\"name\"]):\n        raise WorkflowInputError(\"meta.name must be a safe 1-64 character slug\")\n    if \"phases\" in meta and (\n        not isinstance(meta[\"phases\"], list)\n        or not all(isinstance(p, str) and p for p in meta[\"phases\"])\n    ):\n        raise WorkflowInputError(\"meta.phases must contain non-empty strings\")\n    return meta\n```\n\n## Orchestration Primitives: A Small Set Is Enough for Every Flow\n\nA script runs in an isolated context with only a small set of orchestration primitives as globals. The script does not read files or run shell commands directly. All real code operations are performed by dispatched subagents under their own tool permissions. These primitives are methods on `ExecutionState`:\n\n| Primitive | Purpose |\n|------|------|\n| `agent(prompt, {schema, label, phase})` | Dispatch one subagent |\n| `parallel(thunks)` | **Barrier**: run every task concurrently and wait until all results return |\n| `pipeline(items, *stages)` | Run each item through stages **without a barrier**; finished items proceed immediately |\n| `phase(title)` | Mark the current progress phase and update the progress display |\n| `log(message)` | Emit a progress log line |\n| `workflow(name, args)` | Run a nested sub-workflow, one level only |\n\n`pipeline` should be the default. Each item independently crosses every stage. Item A may reach stage three while item B is still in stage one. Use the `parallel` barrier only when the next stage truly requires every result from the previous stage. A barrier waits for the slowest task, so do not add one without need.\n\n```python\nasync def pipeline(self, items, *stages):\n    async def run_item(item, idx):\n        value = item\n        for stage in stages:                       # Each item independently completes every stage\n            value = await stage(value, item, idx)\n        return value\n    return await asyncio.gather(*[run_item(it, i) for i, it in enumerate(items)])\n```\n\n## Structured Output: Do Not Let Subagents Return Essays\n\n`agent({schema})` requires a subagent to return a JSON object matching the schema, internally through one structured-output call. The runtime validates the result and retries once if it does not match. Downstream code receives a regular object instead of a long essay that must be parsed again.\n\ns05 warned that tool arguments cannot be trusted completely. This is the same lesson in reverse: subagent output cannot be trusted completely either. Validate at the orchestration boundary, give one retry, and keep uncertainty out of the rest of the flow.\n\n```python\nresult = self.runner.run(prompt, schema, label)\nif schema is not None:\n    ok, err = SimpleJsonSchema(schema).validate(result)\n    if not ok:                                       # Retry once with a reminder, then fail\n        result = self.runner.run(prompt + \"\\n\\nReturn valid JSON.\", schema, label)\n        ok, err = SimpleJsonSchema(schema).validate(result)\n        if not ok:\n            raise WorkflowInputError(f\"agent({{schema}}) returned invalid output: {err}\")\n```\n\n## Background Tasks and Progress Events\n\n`LocalWorkflowTask` maintains status and token usage and emits an SDK-style event stream: `task_started` → a sequence of `task_progress` events containing phase changes, subagent starts, and log batches → one final `task_notification` reporting completion, failure, or stop, plus output files, token count, tool calls, and elapsed time.\n\nThe main session treats these as ordinary events. Only the final completion notification re-enters the main loop.\n\n```python\nclass LocalWorkflowTask:\n    def progress_event(self, ptype, **data):         # Phase/subagent/log\n        self.progress.append({\"type\": ptype, **data})\n        print(f\"  progress   {ptype} ...\")\n```\n\n## Storage: Snapshot + Journal for Resuming after Interruptions\n\nThe runtime stores each run under `s20_workflow_runtime/.runtime/`: a `<runId>.json` snapshot, `<runId>.output.json` output, and `<runId>.journal.jsonl` journal. The snapshot and journal share a stable `runId`, so resume can locate one run's state and completed steps.\n\nThe journal is the core of checkpointed resume. It records every `agent()` result one line at a time:\n\n```python\nclass WorkflowJournal:\n    def record(self, key, value):\n        self._f.write(json.dumps({\"key\": key, \"value\": value}) + \"\\n\")\n        self._f.flush()\n        self.cache[key] = value\n```\n\n## Resume: Continue by runId and Reuse Everything Unchanged\n\nCalling the workflow again with `resume_from_run_id` reruns the script, but every `agent()` computes a deterministic semantic key. If that key is present in the journal, it returns the cached result without executing again. Every unchanged call hits the cache; only a changed call and the downstream steps that depend on it actually rerun.\n\nThe key detail is that keys cannot depend on concurrency order. Agents in `parallel` and `pipeline` finish in nondeterministic order. If \"the nth completion\" became the key, cache entries would map to the wrong calls on the next run. A key therefore uses a stable hash of call content, including type, label, prompt, and schema, rather than a shared counter:\n\n```python\ndef key(self, kind, label, prompt, schema):\n    basis = f\"{kind}|{label}|{prompt}|{json.dumps(schema, sort_keys=True)}\"\n    return f\"{kind}-{_stable_hash(basis) % 10**10:010d}\"\n\n# Inside agent():\ncached = self.journal.cached(key)\nif cached is not MISS:\n    self.task.progress_event(\"workflow_agent\", label=label, status=\"cached\")\n    return cached\n```\n\n## Determinism: Reproducibility Makes Resume Meaningful\n\nResume works only if the workflow is reproducible. Stable hashes and a deterministic runner make the same workflow plus the same arguments produce the same keys. Workflow code must therefore avoid uncontrolled clocks, randomness, filesystem state, and other inputs that would change those keys between runs.\n\n## See It Run\n\nThe sample `review-changes` workflow uses `pipeline` to send each review dimension independently through audit → verify. An `agent()` with a schema finds issues during audit. During verification, `parallel()` dispatches a separate adversarial subagent for every finding. Only confirmed issues remain, sorted by severity.\n\n```python\nasync def sample_workflow(ctx, args):\n    ctx.phase(\"Review\")\n\n    async def audit(_v, dimension, _i):\n        out = await ctx.agent(f\"Inspect the changed code for {dimension} issues\",\n                              schema=FINDINGS_SCHEMA, label=f\"audit:{dimension}\", phase=\"Review\")\n        return {\"dimension\": dimension, \"findings\": out[\"findings\"]}\n\n    async def verify(audited, dimension, _i):\n        ctx.phase(\"Verify\")\n        verdicts = await ctx.parallel([                       # Verify every finding independently\n            (lambda f=f: ctx.agent(f\"Adversarially verify whether this issue is real: {f['title']}\",\n                                   schema=VERDICT_SCHEMA, label=f\"verify:{dimension}:{f['title']}\"))\n            for f in audited[\"findings\"]])\n        return {\"dimension\": dimension,\n                \"confirmed\": [f for f, v in zip(audited[\"findings\"], verdicts) if v and v[\"isReal\"]]}\n\n    results = await ctx.pipeline(DIMENSIONS, audit, verify)\n    ...\n```\n\n## Changes from s19\n\n| | s19 Integrated Harness | s20 Workflow Runtime |\n|--|-----------|---------------------|\n| Loop | One model-driven loop | Main loop unchanged; deterministic orchestration added above it |\n| Who decides the next step | Model decides each round | Script declares the orchestration in advance |\n| Multiple agents | One-shot s06 subagents | Scripted, reproducible, recoverable bulk orchestration |\n| New mechanisms | — | Script DSL, background tasks, progress events, journal/resume, structured output, deterministic VM |\n\ns20 does not replace the main loop. It exposes `Workflow` at the tool layer and starts a local workflow runtime behind it: one workflow deterministically drives N agent loops. An s06 subagent is dispatched once at the model's discretion; s20 turns orchestration into a replayable script.\n\n## Try It\n\n```bash\npython s20_workflow_runtime/code.py          # Start review-changes and watch the event stream\npython s20_workflow_runtime/code.py resume   # Resume by the last runId; every agent() hits the journal cache\n```\n\nWatch one launch produce `async_launched`, followed by background phase changes and subagent progress, then `task_notification`; the result is stored on the task object. A resumed run reports `agents=0 tokens=0` because every call hits the cache, and its result is byte-for-byte identical.\n\n## Next\n\nOrchestration adds a layer above agent capabilities: the main loop handles individual operations, while a script manages the whole team's flow. Once work becomes a deterministic, recoverable script, the model changes from the round-by-round driver into an execution unit scheduled by that script. The same `agent()` can be invoked ad hoc by the model in the main loop or orchestrated in bulk inside a workflow.\n\nNext: [s21 Goal Loop](/en/s21) — Orchestration fans work out and leaves the main loop. The next chapter moves in the opposite direction: a goal pulls control back into the main loop and refuses to let the turn end until the objective is achieved.\n\n<!-- translation-sync: zh@v2, en@v2, ja@v2 -->\n"
  },
  {
    "version": "s20",
    "locale": "zh",
    "title": "s20: Workflow Runtime — 模型决定单步，脚本决定编排",
    "content": "# s20: Workflow Runtime — 模型决定单步，脚本决定编排\n\ns01 → ... → s18 → s19 → `s20` → [s21](/zh/s21)\n\n> *\"一次 tool_use，后台跑完一整套编排\"* — `Workflow` 工具启动一个确定、可恢复的脚本运行时，批量派出去一堆子 agent。\n>\n> **Harness 层**: 编排 — 在单 agent 循环之上，加一层确定的多 agent 脚本运行时。\n\n`code.py` 为了让演示保持确定，会先发出 `async_launched`，随后在同一进程里等待执行完成。这样不用启动常驻后台服务，也能看清生命周期和 journal。\n\n---\n\n从 s01 到 s19，我们的循环一直是模型驱动、一步一步来的：每一轮模型挑一个工具，结果塞回 `messages[]`，再来一轮。开放式任务这么干最合适，下一步做什么，让模型看着上下文临场决定就好。\n\n但有些活，你需要的是确定地指挥一群 agent 干活。比如审一个大改动：十个维度并行找问题 → 每条发现各自派一个 agent 做对抗性验证 → 结果汇总去重 → 按严重度排序。这种流程的形状是固定的，你要的其实是三样东西：\n\n- **并行**，别一个一个串着等；\n- **确定**，同样的输入跑出来同样的结果结构；\n- **可恢复**，跑到一半断了，已经做完的部分别从头再来。\n\n让模型在主循环里一步一步驱动这套流程，又慢、结果又不确定，断了还得从头跑。这时候你要的不是\"再聊一轮\"，而是把这套编排直接写成代码。\n\n## 计划写在代码里，不是靠聊天一轮轮凑\n\n在 harness 的工具池里加入一个 `Workflow` 工具。用户或模型给它一段脚本，脚本用 `agent() / parallel() / pipeline() / phase()` 这几个简单的原语，把编排写成确定的代码。\n\n主循环这边只看到一次 `tool_use`，立刻拿到\"已在后台启动\"的返回：真正的执行在后台运行时里推进，实时上报进度，所有过程都写到磁盘的 journal 文件里。脚本里的中间结果存在变量里，不会塞进对话历史占地方。下次用 `resume_from_run_id` 重启时，没改过的 `agent()` 直接命中 journal 缓存，直接用之前的结果，断点续跑。\n\n![Workflow Runtime 总览](/course-assets/s20_workflow_runtime/workflow-runtime-overview.svg)\n\n```python\nSAMPLE_META = {\"name\": \"review-changes\", \"description\": \"审查代码改动\", \"phases\": [\"Review\", \"Verify\"]}\n\nasync def sample_workflow(ctx, args):\n    ctx.phase(\"Review\")\n    results = await ctx.pipeline(DIMENSIONS, audit, verify)   # 每个维度独立走 审计 → 验证\n    confirmed = [f for r in results if r for f in r[\"confirmed\"]]\n    ctx.log(f\"确认了 {len(confirmed)} 个真实问题\")\n    return {\"confirmed\": confirmed}\n```\n\n## Workflow 工具：后台启动，主循环只看到一次调用\n\n`Workflow` 就在主 agent 的工具池里。用户可以要求运行一个保存好的 workflow，模型也可以在任务匹配已知编排时选择这个工具；两种情况最终都只发出一次 `Workflow(...)` 工具调用。\n\n工具收到后会解析参数、校验 meta 信息、过权限检查、注册一个本地 workflow 任务，然后立刻返回\"已异步启动\"。主循环不阻塞，该干嘛干嘛；workflow 自己在后台跑。这其实就是 s13 后台任务那套\"凭条模式\"的放大版：先给你个取件条，结果好了再通知你。\n\n```python\nclass WorkflowTool:\n    async def call(self, meta, script_fn, args=None, resume_from_run_id=None):\n        validate_meta(meta)\n        check_permission(meta)\n        run_id = resume_from_run_id or create_run_id(meta)\n        task = LocalWorkflowTask(create_task_id(run_id), run_id, meta)\n        task.event(\"async_launched\", runId=run_id, taskId=task.task_id)   # 立刻返回\n        ...                                                                # 剩下的后台慢慢跑\n```\n\n## Workflow 元数据：启动前先校验\n\n每个 workflow 都要注册一个元数据对象，包含 `name`、`description` 和可选的 `phases`。运行时会在执行任何 workflow 代码之前校验它：`name` 和 `description` 用来标识任务，`phases` 给进度条分组命名。\n\n不对的输入直接抛 `WorkflowInputError`，注册的时候就拦住——这和 s14 校验 cron 表达式是一个思路：坏脚本别让它跑到执行的时候才炸。\n\n运行时会把 `meta.name` 用在本地产物文件名中，因此还要求它是 1-64 个字符的安全 slug，只能包含字母、数字、`.`、`_`、`-`。\n\n```python\ndef validate_meta(meta):\n    if not isinstance(meta, dict):\n        raise WorkflowInputError(\"meta 必须是对象字面量\")\n    if not meta.get(\"name\") or not meta.get(\"description\"):\n        raise WorkflowInputError(\"meta 必须包含 name 和 description\")\n    if not isinstance(meta[\"name\"], str) or not WORKFLOW_NAME_RE.fullmatch(meta[\"name\"]):\n        raise WorkflowInputError(\"meta.name 必须是 1-64 字符的安全 slug\")\n    if \"phases\" in meta and (\n        not isinstance(meta[\"phases\"], list)\n        or not all(isinstance(p, str) and p for p in meta[\"phases\"])\n    ):\n        raise WorkflowInputError(\"meta.phases 必须包含非空字符串\")\n    return meta\n```\n\n## 编排原语：就这几个，够写所有流程\n\n脚本跑在一个独立的上下文里，能用的全局变量就这几个编排原语。脚本本身不直接读写文件、不跑 shell，真正的代码操作都由派出去的子 agent 用它们自己的工具权限完成。这些原语都是 `ExecutionState` 上的方法：\n\n| 原语 | 作用 |\n|------|------|\n| `agent(prompt, {schema, label, phase})` | 派一个子 agent 干活 |\n| `parallel(thunks)` | **等齐屏障**：所有任务并行跑完，一起等结果回来 |\n| `pipeline(items, *stages)` | 每个 item 分阶段跑，**不等齐**，跑完一个往下走一个 |\n| `phase(title)` | 标记当前进度阶段（更新进度条） |\n| `log(message)` | 打一行进度日志 |\n| `workflow(name, args)` | 嵌套子工作流（只支持一层） |\n\n`pipeline` 是你默认该用的：每个 item 独立穿过所有 stage，item A 跑到第 3 阶段的时候，item B 可能还在第 1 阶段；只有真的需要\"拿到上一阶段所有结果才能往下走\"的时候，才用 `parallel` 这个屏障。屏障的代价是等最慢的那个任务，没必要就别立。\n\n```python\nasync def pipeline(self, items, *stages):\n    async def run_item(item, idx):\n        value = item\n        for stage in stages:                       # 每个 item 独立跑完所有 stage\n            value = await stage(value, item, idx)\n        return value\n    return await asyncio.gather(*[run_item(it, i) for i, it in enumerate(items)])\n```\n\n## 结构化输出：别让子 agent 回来写散文\n\n`agent({schema})` 会强制子 agent 返回一个匹配 schema 的 JSON 对象（内部通过一次结构化输出调用实现），运行时会按 schema 校验结果，不对就重试一次。这样下游代码拿到的是规整的对象，不是需要再解析的一大段散文。\n\ns05 就说过，工具的参数不能全信；这里是同一个道理反过来：子 agent 的输出也不能全信。加一层校验，不对就给一次机会重试，把不确定性挡在编排层外面。\n\n```python\nresult = self.runner.run(prompt, schema, label)\nif schema is not None:\n    ok, err = SimpleJsonSchema(schema).validate(result)\n    if not ok:                                       # 提醒一次重试，再不对就报错\n        result = self.runner.run(prompt + \"\\n\\n返回合法的 JSON。\", schema, label)\n        ok, err = SimpleJsonSchema(schema).validate(result)\n        if not ok:\n            raise WorkflowInputError(f\"agent({{schema}}) 输出不合法: {err}\")\n```\n\n## 后台任务和进度事件\n\n`LocalWorkflowTask` 维护状态和 token 用量，向外发一条 SDK 风格的事件流：`task_started` → 一串 `task_progress`（包含阶段切换、子 agent 启动、日志输出这些批次）→ 最后一个 `task_notification`（完成/失败/停止，带输出文件、token 数、工具调用数、耗时）。\n\n主会话把这些当普通事件处理；只有最终的完成通知会重新进入主循环。\n\n```python\nclass LocalWorkflowTask:\n    def progress_event(self, ptype, **data):         # 阶段/子agent/日志\n        self.progress.append({\"type\": ptype, **data})\n        print(f\"  进度   {ptype} ...\")\n```\n\n## 存储：快照 + journal，断了能续\n\n运行时把每次运行的数据存在 `s20_workflow_runtime/.runtime/`：快照 `<runId>.json`、输出 `<runId>.output.json` 和 journal `<runId>.journal.jsonl`。快照与 journal 共享稳定的 `runId`，续跑时才能找到同一次运行的状态和已完成步骤。\n\njournal 是断点续跑的核心，它一条一条记下来每个 `agent()` 的结果：\n\n```python\nclass WorkflowJournal:\n    def record(self, key, value):\n        self._f.write(json.dumps({\"key\": key, \"value\": value}) + \"\\n\")\n        self._f.flush()\n        self.cache[key] = value\n```\n\n## resume：用 runId 续跑，没改的直接用缓存\n\n带着 `resume_from_run_id` 再次调用 workflow 时，脚本会重新执行，但每个 `agent()` 都会计算一个确定的语义 key：key 在 journal 里有记录，就直接返回缓存结果；只有改过的调用以及依赖它的后续步骤才会真的运行。\n\n这里有个关键点：key 不能依赖并发顺序。`parallel` 和 `pipeline` 里 agent 完成的顺序是不确定的，用\"第几个完成\"当 key，两次跑缓存就对错位了。所以 key 是根据调用内容（类型、标签、prompt、schema）算的稳定哈希，不是一个会竞争的计数器：\n\n```python\ndef key(self, kind, label, prompt, schema):\n    basis = f\"{kind}|{label}|{prompt}|{json.dumps(schema, sort_keys=True)}\"\n    return f\"{kind}-{_stable_hash(basis) % 10**10:010d}\"\n\n# agent() 内部：\ncached = self.journal.cached(key)\nif cached is not MISS:\n    self.task.progress_event(\"workflow_agent\", label=label, status=\"cached\")\n    return cached\n```\n\n## 确定性：能复现，续跑才有意义\n\n续跑要能工作，workflow 首先得可复现。稳定哈希和确定性的 runner 让同一份 workflow + 同样的参数产生同样的 key。因此 workflow 代码要避免不受控的时钟、随机数、文件系统状态等会让 key 在两次运行间变化的输入。\n\n## 跑起来看看\n\n示例 workflow `review-changes`：用 `pipeline` 让每个审查维度独立走\"审计 → 验证\"流程。审计用一个带 schema 的 `agent()` 找问题，验证用 `parallel()` 给每条发现各派一个对抗性验证的子 agent，最后只留确认真实的问题，按严重度排序。\n\n```python\nasync def sample_workflow(ctx, args):\n    ctx.phase(\"Review\")\n\n    async def audit(_v, dimension, _i):\n        out = await ctx.agent(f\"检查改动的代码里有没有{dimension}相关的问题\",\n                              schema=FINDINGS_SCHEMA, label=f\"audit:{dimension}\", phase=\"Review\")\n        return {\"dimension\": dimension, \"findings\": out[\"findings\"]}\n\n    async def verify(audited, dimension, _i):\n        ctx.phase(\"Verify\")\n        verdicts = await ctx.parallel([                       # 每条发现独立做对抗性验证\n            (lambda f=f: ctx.agent(f\"请对抗性验证这个问题是不是真的：{f['title']}\",\n                                   schema=VERDICT_SCHEMA, label=f\"verify:{dimension}:{f['title']}\"))\n            for f in audited[\"findings\"]])\n        return {\"dimension\": dimension,\n                \"confirmed\": [f for f, v in zip(audited[\"findings\"], verdicts) if v and v[\"isReal\"]]}\n\n    results = await ctx.pipeline(DIMENSIONS, audit, verify)\n    ...\n```\n\n## 相对 s19 的变更\n\n| | s19 Agent Harness 集成 | s20 Workflow Runtime |\n|--|-----------|---------------------|\n| 循环 | 单个、模型驱动 | 主循环不变；上面加一层确定的编排 |\n| 谁决定下一步 | 模型逐轮决定 | 脚本预先写好编排流程 |\n| 多 agent | s06 子 agent，一次性派出去 | 脚本化、可复现、可恢复的批量编排 |\n| 新增机制 | — | 脚本 DSL、后台任务、进度事件、journal/续跑、结构化输出、确定性 VM |\n\ns20 不替换主循环，它只是在工具层暴露了 `Workflow`，背后启动一个本地 workflow 运行时：一个 workflow 确定地驱动 N 个 agent 循环。s06 的子 agent 是模型临场派一次；s20 是把编排写成可以重放的脚本。\n\n## 试一下\n\n```bash\npython s20_workflow_runtime/code.py          # 启动 review-changes，看事件流\npython s20_workflow_runtime/code.py resume   # 用上次的 runId 续跑，每个 agent() 都命中 journal 缓存\n```\n\n观察：一次启动 → `async_launched` → 后台阶段切换/子agent进度推进 → `task_notification`；结果存在任务对象上。续跑的时候会显示 `agents=0 tokens=0`（全部命中缓存），结果和上次一字不差。\n\n## 接下来\n\n编排是在 agent 能力之上又加了一层：主循环管单步操作，脚本管整支队伍的流程。把工作写成确定、可恢复的脚本，模型就从\"逐轮驱动者\"变成了\"被脚本调度的执行单元\"。同一个 `agent()`，既能在主循环里被模型临场调用，也能在 workflow 里被脚本批量编排。\n\n下一章：[s21 Goal Loop](/zh/s21) — 编排是把工作扇出去、脱离主循环；下一章反过来，一个目标把控制权重拉回主循环，没达成就不让这一轮结束。\n\n<!-- translation-sync: zh@v2, en@v2, ja@v2 -->\n"
  },
  {
    "version": "s20",
    "locale": "ja",
    "title": "s20: Workflow Runtime — モデルが単一 step を決め、script が orchestration を決める",
    "content": "# s20: Workflow Runtime — モデルが単一 step を決め、script が orchestration を決める\n\ns01 → ... → s18 → s19 → `s20` → [s21](/ja/s21)\n\n> *「1 回の tool_use で、バックグラウンドに一式の orchestration を走らせる」* — `Workflow` ツールが決定的で復元可能な script runtime を起動し、多数の subagent をまとめて送り出します。\n>\n> **Harness 層**: Orchestration — single-agent loop の上に、決定的な multi-agent script runtime を追加します。\n\n`code.py` は demo を決定的に保つため、`async_launched` を出した後、同じ process で完了を待ちます。常駐 background service を用意しなくても、lifecycle と journal を確認できます。\n\n---\n\ns01 から s19 まで、loop は常にモデル駆動で 1 step ずつ進みました。各ラウンドでモデルが 1 つのツールを選び、結果を `messages[]` へ入れ、次のラウンドへ進みます。open-ended なタスクには最適です。次に何をするかを、モデルが context を見てその場で決められます。\n\nしかし、複数の Agent を決定的に指揮したい仕事もあります。大きな変更の review を考えてください。10 の観点から並行して問題を探す → 各 finding へ別 Agent を送り adversarial verification を行う → 結果を集約して重複を除く → severity 順に並べる。この流れの形は固定されており、本当に必要なのは 3 つです。\n\n- **並行性**: 1 件ずつ順番に待たないこと。\n- **決定性**: 同じ入力から同じ結果構造が得られること。\n- **復元可能性**: 途中で止まっても、完了済みの部分を最初からやり直さないこと。\n\nこの流れをモデルに main loop で 1 ラウンドずつ動かさせると、遅く、結果は不確定で、中断すれば最初からです。ここで必要なのは「もう 1 turn 話す」ことではなく、orchestration をそのままコードにすることです。\n\n## 計画は chat のラウンドを重ねず、コードに書く\n\nharness の tool pool に `Workflow` ツールを追加します。ユーザーまたはモデルが渡す script は、`agent() / parallel() / pipeline() / phase()` という少数の primitive を使い、orchestration を決定的なコードとして表します。\n\nmain loop から見えるのは 1 回の `tool_use` だけで、すぐ「バックグラウンドで起動済み」という結果を受け取ります。本当の実行は background runtime で進み、進捗をリアルタイムに報告し、全過程をディスク上の journal へ記録します。script の中間結果は変数に保存され、会話履歴の場所を取りません。`resume_from_run_id` で再開すると、変更されていない `agent()` は journal cache に当たり、以前の結果を直接使って checkpoint から続行します。\n\n![Workflow Runtime Overview](/course-assets/s20_workflow_runtime/workflow-runtime-overview.svg)\n\n```python\nSAMPLE_META = {\"name\": \"review-changes\", \"description\": \"コード変更を review\", \"phases\": [\"Review\", \"Verify\"]}\n\nasync def sample_workflow(ctx, args):\n    ctx.phase(\"Review\")\n    results = await ctx.pipeline(DIMENSIONS, audit, verify)   # 各 dimension が独立して audit → verify を通る\n    confirmed = [f for r in results if r for f in r[\"confirmed\"]]\n    ctx.log(f\"{len(confirmed)} 件の実在する問題を確認\")\n    return {\"confirmed\": confirmed}\n```\n\n## Workflow ツール: バックグラウンド起動、main loop には 1 回の call だけ\n\n`Workflow` は main Agent の tool pool にあります。ユーザーが保存済み workflow の実行を求めるか、タスクが既知の orchestration に一致したときにモデルがこのツールを選びます。どちらも 1 回の `Workflow(...)` tool call になります。\n\nツールは argument を parse し、meta 情報を検証し、permission check を通し、local workflow task を登録すると、すぐ「非同期で起動済み」と返します。main loop は block せず別の仕事を続け、workflow は background で実行されます。これは s13 の引換券 pattern を拡大したものです。先に引換券を渡し、結果ができたら通知します。\n\n```python\nclass WorkflowTool:\n    async def call(self, meta, script_fn, args=None, resume_from_run_id=None):\n        validate_meta(meta)\n        check_permission(meta)\n        run_id = resume_from_run_id or create_run_id(meta)\n        task = LocalWorkflowTask(create_task_id(run_id), run_id, meta)\n        task.event(\"async_launched\", runId=run_id, taskId=task.task_id)   # すぐ return\n        ...                                                                # 残りはバックグラウンドで進む\n```\n\n## Workflow metadata: 起動前に検証する\n\n各 workflow は `name`、`description`、任意の `phases` を持つ metadata object を登録します。runtime は workflow code を実行する前に検証します。`name` と `description` は task と UI の表示に使い、`phases` は progress bar の group 名を定義します。\n\n不正な入力はすぐ `WorkflowInputError` になり、登録時に止まります。s14 の cron 式検証と同じ考えです。不正な script が実行時まで進んでから壊れないようにします。\n\nruntime は `meta.name` をローカル artifact のファイル名に使うため、英数字で始まり、英数字、`.`、`_`、`-` のみからなる 1-64 文字の安全な slug も要求する。\n\n```python\ndef validate_meta(meta):\n    if not isinstance(meta, dict):\n        raise WorkflowInputError(\"meta は object literal でなければなりません\")\n    if not meta.get(\"name\") or not meta.get(\"description\"):\n        raise WorkflowInputError(\"meta には name と description が必要です\")\n    if not isinstance(meta[\"name\"], str) or not WORKFLOW_NAME_RE.fullmatch(meta[\"name\"]):\n        raise WorkflowInputError(\"meta.name は安全な 1-64 文字の slug が必要です\")\n    if \"phases\" in meta and (\n        not isinstance(meta[\"phases\"], list)\n        or not all(isinstance(p, str) and p for p in meta[\"phases\"])\n    ):\n        raise WorkflowInputError(\"meta.phases は空でない文字列だけを含む必要があります\")\n    return meta\n```\n\n## Orchestration primitive: この少数だけで、すべての flow を書ける\n\nscript は独立した context で動き、global variable として使えるのは少数の orchestration primitive だけです。script 自身はファイルを直接読み書きせず、shell も実行しません。実際のコード操作は、派遣された subagent が自分の tool permission で行います。primitive はすべて `ExecutionState` の method です。\n\n| Primitive | 役割 |\n|------|------|\n| `agent(prompt, {schema, label, phase})` | 1 つの subagent を派遣 |\n| `parallel(thunks)` | **barrier**: すべての task を並行実行し、全結果が戻るまで待つ |\n| `pipeline(items, *stages)` | 各 item を **barrier なし**で stage ごとに実行し、終わった item から先へ進める |\n| `phase(title)` | 現在の progress phase を記録し、progress bar を更新 |\n| `log(message)` | progress log を 1 行出力 |\n| `workflow(name, args)` | nested sub-workflow（1 階層だけ） |\n\n既定では `pipeline` を使うべきです。各 item がすべての stage を独立して通り、item A が stage 3 にいる間、item B はまだ stage 1 かもしれません。次の stage へ進むために前 stage の全結果が本当に必要なときだけ、`parallel` barrier を使います。barrier は最も遅い task を待つため、不要なら置かないでください。\n\n```python\nasync def pipeline(self, items, *stages):\n    async def run_item(item, idx):\n        value = item\n        for stage in stages:                       # 各 item がすべての stage を独立して完走\n            value = await stage(value, item, idx)\n        return value\n    return await asyncio.gather(*[run_item(it, i) for i, it in enumerate(items)])\n```\n\n## 構造化出力: Subagent に散文を返させない\n\n`agent({schema})` は、schema に一致する JSON object を subagent に要求します。内部では structured output call を 1 回使い、runtime が結果を schema で検証し、不一致なら 1 回 retry します。下流コードが受け取るのは規則的な object であり、再 parse が必要な長文ではありません。\n\ns05 では tool argument を全面的に信頼できないと説明しました。ここでは同じ教訓を逆向きに使います。subagent の出力も全面的には信頼できません。orchestration boundary で検証し、1 回 retry の機会を与え、不確実性を後続 flow の外へ止めます。\n\n```python\nresult = self.runner.run(prompt, schema, label)\nif schema is not None:\n    ok, err = SimpleJsonSchema(schema).validate(result)\n    if not ok:                                       # 1 回だけ注意して retry、それでも不正なら error\n        result = self.runner.run(prompt + \"\\n\\n有効な JSON を返してください。\", schema, label)\n        ok, err = SimpleJsonSchema(schema).validate(result)\n        if not ok:\n            raise WorkflowInputError(f\"agent({{schema}}) の出力が不正です: {err}\")\n```\n\n## Background task と progress event\n\n`LocalWorkflowTask` は status と token usage を管理し、SDK style の event stream を外へ出します。`task_started` → phase change、subagent start、log batch を含む一連の `task_progress` → 完了、失敗、停止に加え、output file、token 数、tool call 数、所要時間を含む最後の `task_notification` です。\n\nmain session は通常 event として処理し、最後の完了通知だけが main loop へ再び入ります。\n\n```python\nclass LocalWorkflowTask:\n    def progress_event(self, ptype, **data):         # phase/subagent/log\n        self.progress.append({\"type\": ptype, **data})\n        print(f\"  progress   {ptype} ...\")\n```\n\n## 保存: Snapshot + journal で中断から再開する\n\nruntime は各 run を `s20_workflow_runtime/.runtime/` に保存します。`<runId>.json` snapshot、`<runId>.output.json` output、`<runId>.journal.jsonl` journal です。snapshot と journal は安定した `runId` を共有し、resume 時に同じ run の状態と完了済み step を特定できるようにします。\n\njournal は checkpoint resume の中心で、各 `agent()` の結果を 1 行ずつ記録します。\n\n```python\nclass WorkflowJournal:\n    def record(self, key, value):\n        self._f.write(json.dumps({\"key\": key, \"value\": value}) + \"\\n\")\n        self._f.flush()\n        self.cache[key] = value\n```\n\n## Resume: runId から続行し、変更のないものを再利用する\n\n`resume_from_run_id` を渡して workflow を再度呼ぶと script を再実行しますが、各 `agent()` は決定的な semantic key を計算します。journal に key があれば、再実行せず cached result を返します。変更された call と、それに依存する後続 step だけが本当に動きます。\n\nkey は concurrency の完了順に依存してはいけません。`parallel` と `pipeline` の Agent は不定の順番で完了します。「何番目に完了したか」を key にすると、次回の cache が別の call へ対応してしまいます。そのため key は競合する counter ではなく、call の内容、つまり type、label、prompt、schema の stable hash です。\n\n```python\ndef key(self, kind, label, prompt, schema):\n    basis = f\"{kind}|{label}|{prompt}|{json.dumps(schema, sort_keys=True)}\"\n    return f\"{kind}-{_stable_hash(basis) % 10**10:010d}\"\n\n# agent() の内部:\ncached = self.journal.cached(key)\nif cached is not MISS:\n    self.task.progress_event(\"workflow_agent\", label=label, status=\"cached\")\n    return cached\n```\n\n## 決定性: Resume に意味を持たせる再現性\n\nresume が動くには、workflow が再現可能でなければなりません。stable hash と決定的な runner は、同じ workflow + 同じ argument から同じ key を作ります。そのため workflow code は、制御されていない clock、randomness、filesystem state など、run ごとに key を変える入力を避けます。\n\n## 実際に動かす\n\nsample workflow `review-changes` は `pipeline` を使い、各 review dimension を独立して audit → verify へ通します。audit では schema 付き `agent()` が問題を探し、verify では `parallel()` が各 finding に別の adversarial verification subagent を送ります。実在すると確認された問題だけを残し、severity 順に並べます。\n\n```python\nasync def sample_workflow(ctx, args):\n    ctx.phase(\"Review\")\n\n    async def audit(_v, dimension, _i):\n        out = await ctx.agent(f\"変更されたコードに {dimension} 関連の問題がないか確認してください\",\n                              schema=FINDINGS_SCHEMA, label=f\"audit:{dimension}\", phase=\"Review\")\n        return {\"dimension\": dimension, \"findings\": out[\"findings\"]}\n\n    async def verify(audited, dimension, _i):\n        ctx.phase(\"Verify\")\n        verdicts = await ctx.parallel([                       # 各 finding を独立して verify\n            (lambda f=f: ctx.agent(f\"この問題が実在するか adversarial に検証してください: {f['title']}\",\n                                   schema=VERDICT_SCHEMA, label=f\"verify:{dimension}:{f['title']}\"))\n            for f in audited[\"findings\"]])\n        return {\"dimension\": dimension,\n                \"confirmed\": [f for f, v in zip(audited[\"findings\"], verdicts) if v and v[\"isReal\"]]}\n\n    results = await ctx.pipeline(DIMENSIONS, audit, verify)\n    ...\n```\n\n## s19 からの変更点\n\n| | s19 Integrated Harness | s20 Workflow Runtime |\n|--|-----------|---------------------|\n| loop | 1 つ、モデル駆動 | main loop は不変。その上に決定的 orchestration を追加 |\n| 次の step を決めるもの | モデルが毎ラウンド判断 | script が orchestration flow を事前に定義 |\n| multi-agent | s06 subagent を一度だけ派遣 | script 化された、再現可能で復元可能な一括 orchestration |\n| 新しい仕組み | — | script DSL、background task、progress event、journal/resume、structured output、deterministic VM |\n\ns20 は main loop を置き換えません。tool layer に `Workflow` を公開し、背後で local workflow runtime を起動します。1 つの workflow が N 個の Agent loop を決定的に駆動します。s06 の subagent はモデルがその場で 1 回派遣し、s20 は orchestration を replay 可能な script にします。\n\n## 試してみる\n\n```bash\npython s20_workflow_runtime/code.py          # review-changes を起動し、event stream を確認\npython s20_workflow_runtime/code.py resume   # 前回の runId から resume。すべての agent() が journal cache に当たる\n```\n\n1 回の起動から `async_launched`、background の phase change と subagent progress、最後の `task_notification` までを観察してください。結果は task object に保存されます。resume 時はすべて cache hit するため `agents=0 tokens=0` と表示され、結果は前回と 1 byte も違いません。\n\n## 次へ\n\norchestration は Agent 能力の上にもう 1 層を加えます。main loop は個々の操作を管理し、script はチーム全体の flow を管理します。仕事が決定的で復元可能な script になると、モデルは「ラウンドごとの driver」から「script に schedule される実行 unit」へ変わります。同じ `agent()` を main loop でモデルがその場で呼ぶことも、workflow 内で script がまとめて編成することもできます。\n\n次へ: [s21 Goal Loop](/ja/s21) — Orchestration は仕事を fan-out し、main loop から離れます。次章は逆に、1 つの goal が control を main loop へ引き戻し、objective が達成されるまで turn の終了を認めません。\n\n<!-- translation-sync: zh@v2, en@v2, ja@v2 -->\n"
  },
  {
    "version": "s21",
    "locale": "en",
    "title": "s21: Goal Loop — The Goal Decides When to Stop, Not the Model",
    "content": "# s21: Goal Loop — The Goal Decides When to Stop, Not the Model\n\ns01 → ... → s19 → s20 → `s21`\n\n> *\"A turn ends only when the goal condition is satisfied, not merely when the model says stop\"* — `/goal` adds a gate at the end of every main-loop turn. An independent evaluator checks whether trusted evidence is sufficient; if not, it pushes the model into another round.\n>\n> **Harness layer**: Goal closure — a program-controlled completion gate at the end of each turn.\n\n---\n\nFrom s01 through s20, how does a conversation turn end? When the model stops emitting `tool_use`, the loop simply executes `return`. That is fine for one-shot work: finish and stop.\n\nSome objectives, however, must be carried through to completion: \"get the tests passing\" or \"do not stop until the deployment succeeds.\" Two problems appear often. The model does half the work, decides it is close enough, and stops. Worse, it says `tests passed` and tries to declare victory. The requirement is simple: the model cannot decide by itself whether the turn may end. An explicit condition must be evaluated against concrete evidence.\n\nThis thread was present from the first chapter. s01 explained that exiting the loop is a model decision. s04's Stop hook gave the program veto power for the first time. This chapter turns that veto into a complete loop with three indispensable parts: condition, evidence, and budget.\n\n## /goal: Add a Gate at the End of Every Turn\n\nEntering `/goal <condition>` sets a session-scoped stopping condition. The program stores it as the active goal. After each turn, an evaluator checks whether trusted evidence in the transcript satisfies the condition. If evidence is insufficient, the gate blocks the attempted stop and queues a \"keep working\" prompt for the next round. If it is sufficient, the goal is cleared and marked complete.\n\n![Goal Loop Overview](/course-assets/s21_goal_loop/goal-loop-overview.svg)\n\nCompared with the s01 loop, there is only one additional decision: when the model wants to stop, it must first pass the goal gate.\n\n```python\n# s01: stop when the model says stop\nif not has_tool_use(response):\n    return\n# s21: want to stop? Pass the goal gate first\nif not has_tool_use(response):\n    verdict = goal.evaluate_after_turn()\n    if verdict == \"continuing\":\n        continue                 # Not achieved -> push back for another round\n    return                       # Achieved / over budget / no goal -> really stop\n```\n\nThe program controls this gate. It is not the model restraining itself. The model does not even know the gate exists; it simply receives another round of input and continues working.\n\n## Setting a Goal: Evidence Starts after the Command\n\n`set_goal` stores an active goal containing the objective text, a maximum-turn budget, counters, and `start_index`, the beginning of the evidence window. It uses the transcript's current length, placing the `/goal` command itself outside the window. This is the first defense: a command cannot prove its own completion.\n\n```python\ndef set_goal(self, objective, max_turns=20):\n    self.active = {\n        \"objective\": objective, \"status\": \"active\",\n        \"start_index\": len(self.transcript),   # Evidence starts here; the command is outside the window\n        \"max_turns\": max_turns, \"checks\": 0, \"continuation_turns\": 0,\n    }\n```\n\n## The Evaluator: Trust Concrete Evidence Only\n\nThis is the core of the entire mechanism. The evaluator does not inspect the whole conversation. It sees only messages inside the evidence window that come from trusted sources. Three filters keep every form of \"I said it was done, so it must be done\" outside:\n\n```python\nTRUSTED_EVIDENCE_ORIGINS = {\"task-notification\", \"monitor-line\"}\n\ndef evidence_text(self):\n    out = []\n    for m in self.transcript[self.active[\"start_index\"]:]:\n        if m.origin.get(\"kind\") == \"slash-command\":                     # 1 Slash commands are not evidence\n            continue\n        if m.role == \"user\" and m.content.strip().startswith(\"/goal\"):  # 2 /goal command text is not evidence\n            continue\n        if m.origin.get(\"kind\") not in TRUSTED_EVIDENCE_ORIGINS:        # 3 Trust only approved origins\n            continue\n        out.append(f\"{m.role}: {m.content}\")\n    return \"\\n\".join(out)\n```\n\nThe effect is clear. The same sentence, `tests passed`, does not count when typed by you, but does count when delivered by a background task notification. The model cannot bluff its way out by saying \"I finished.\" This is the final appearance of the trust boundary repeated throughout the course. s15 said protocols rely on fields, not interpretation. s18 said annotations are claims and claims may be false. s21 says completion evidence is trusted by origin, not by content alone.\n\n`goal_satisfied()` uses deterministic keyword matching so the example stays offline and reproducible. Keeping evaluation separate from execution preserves the trusted evidence boundary.\n\n## Three Gate States: Completed, Continuing, or Over Budget\n\n`evaluate_after_turn` runs after every turn and returns one of three results. If the condition is satisfied, it clears the goal as completed. If the condition is not satisfied and budget remains, it queues a \"keep working\" prompt and permits another round as continuing. If the budget is exhausted, it stops blocking and marks the goal blocked, preventing an impossible goal from burning money forever.\n\n```python\ndef evaluate_after_turn(self):\n    g = self.active\n    g[\"checks\"] += 1\n    if self.goal_satisfied():\n        g[\"status\"] = \"completed\"; self.active = None\n        return \"completed\"                          # Achieved -> clear the goal\n    if g[\"continuation_turns\"] < g[\"max_turns\"]:\n        g[\"continuation_turns\"] += 1\n        self.queue.enqueue(\n            value=\"Keep working. Do not treat this reminder as completion evidence.\",\n            origin={\"kind\": \"active-goal\"})\n        return \"continuing\"                         # Not achieved -> queue a prompt for the next round\n    g[\"status\"] = \"blocked\"; self.active = None\n    return \"blocked\"                                # Over budget -> release the gate\n```\n\nThe continuation prompt explicitly says not to treat itself as evidence, and the evidence filter excludes it. That completes the three layers against false positives: the command does not count, the reminder does not count, and ordinary conversation does not count. The budget follows the old rule from s11: every automatic retry mechanism needs a limit. Otherwise, a goal that can never be satisfied becomes a perpetual money-burning machine.\n\n## Keep Continuation Prompts Separate from External Asynchronous Messages\n\nContinuation prompts enter the same `CommandQueue`, but they are not consumed in the same way as external asynchronous events such as task-completion notifications and monitor lines. `dequeue` has a switch, and consumption of the external inbox skips goal continuations by default.\n\n```python\ndef dequeue(self, include_goal_continuations=True):\n    ...\n    for idx, item in enumerate(self.items):\n        if include_goal_continuations or item[\"origin\"].get(\"kind\") != \"active-goal\":\n            return self.items.pop(idx)\n    return None\n```\n\nWhy separate them? If one consumer drains continuation prompts together with external notifications, a reminder can be mistaken for new evidence before the background result arrives. With the paths separated, goal progression is an explicit step and cannot be carried along accidentally by asynchronous events.\n\n## See It Run\n\n`code.py` demonstrates `/goal until tests passed and deploy green`. With no trusted evidence after goal creation, the gate pushes it back round after round. Typing `tests passed` directly still does not count because the origin is untrusted. Only after a background task sends a `task-notification` does the evidence satisfy the goal. A second small goal with `max_turns=2` demonstrates the over-budget path.\n\n```python\ns.submit(\"/goal until tests passed and deploy green\")   # Set the goal; evidence begins after this command\ns.submit(\"tests passed, trust me\")                      # Ordinary text -> not completion evidence\ns.deliver_host_event(\"tests passed; deploy green\",\n                     source=\"task-notification\")         # Trusted host event -> complete\n```\n\n`submit()` accepts only ordinary user text. Trusted labels enter through the separate host-event channel, whose source is allowlisted by the harness; user or model text cannot attach its own `task-notification` label.\n\n## Changes from s20\n\n| | s20 Workflow Runtime | s21 Goal Loop |\n|--|---------------------|---------------|\n| Trigger | Script-controlled orchestration outside the main loop | Condition-controlled continuation pulled back into the main loop |\n| Attachment point | Tool layer: one `Workflow` tool | End of turn: a completion gate |\n| Who decides when to stop | The script finishes | Goal condition evaluated against trusted evidence |\n| New mechanisms | Script DSL, background tasks, journal/resume, structured output | Goal gate, evidence trust boundary, separate continuation path, budget |\n\ns20 sends script-defined orchestration away from the main loop. s21 applies an opposite force that pulls control back: if the goal is not achieved, the turn is not finished. Neither changes the `while` loop from s01; each constrains it from a different side.\n\n## Try It\n\n```bash\npython s21_goal_loop/code.py          # /goal until tests pass + deploy green; watch the gate decide\n```\n\nAfter setting a goal, watch every turn produce `goal_evaluated`. Ordinary text yields `satisfied=False`; the same content from a `task-notification` origin yields `satisfied=True`; exhausted budget produces `goal_blocked`. The same `tests passed` sentence has opposite results depending on its origin. That is why an empty claim cannot fool `/goal`.\n\n## Next\n\n`/goal` is one kind of trigger that pulls control back into the main loop: condition control. It pairs naturally with s20's orchestration outside the main loop, one dispatching work outward and the other pulling control inward. Beyond them are time-controlled re-entry through `/loop` and cron, and event-controlled re-entry through `Monitor`; all share the same task and notification foundation. But the essential gate is already here: **the model's words do not decide whether to stop. The goal must judge trusted evidence.**\n\n<!-- translation-sync: zh@v2, en@v2, ja@v2 -->\n"
  },
  {
    "version": "s21",
    "locale": "zh",
    "title": "s21: Goal Loop — 什么时候停，目标说了算，不是模型说了算",
    "content": "# s21: Goal Loop — 什么时候停，目标说了算，不是模型说了算\n\ns01 → ... → s19 → s20 → `s21`\n\n> *\"一轮能不能结束，看目标条件满不满足，不是模型说停就停\"* — `/goal` 在主循环每轮收尾的地方加一道闸门：每轮结束后，一个独立的判断器看可信证据够不够，不够就把模型推回去再来一轮。\n>\n> **Harness 层**: 目标闭环 — 在轮次收尾处，加一道程序控制的完成闸门。\n\n---\n\n从 s01 到 s20，一轮对话怎么结束？模型不再发 `tool_use`，循环就直接 `return` 了。一次性任务这么干没问题，做完就停。\n\n但有些目标你得盯着它做到底：\"把测试跑过\"、\"部署成功了再说\"。这时候经常出两种问题：模型做了一半觉得差不多了，自己就停了；更过分的是，它嘴上说一句 `tests passed` 就想收工。你要的其实很简单：这一轮能不能结束，不能模型自己说了算，得有个明确的条件，对着实打实的证据来判断。\n\n这条线其实从第一课就埋着了。s01 说过，退出循环本来是模型的一个决定；s04 的 Stop hook 第一次给了程序否决权。这一课把那个否决权做成完整的闭环：条件、证据、预算，三样缺一不可。\n\n## /goal：每轮收尾加一道闸门\n\n输入 `/goal <条件>` 就设了一个会话级的停止条件。程序把它存成当前活跃目标，每轮结束后，判断器检查对话记录里的可信证据够不够满足条件。不够，闸门就把这次结束拦住，塞一条\"继续干\"的提示进下一轮；够了，就清除目标，标记完成。\n\n![Goal Loop 总览](/course-assets/s21_goal_loop/goal-loop-overview.svg)\n\n和 s01 的循环比，只多了一道判断，模型想停的时候先过目标这关：\n\n```python\n# s01：模型说停就停\nif not has_tool_use(response):\n    return\n# s21：想停？先过目标闸门\nif not has_tool_use(response):\n    verdict = goal.evaluate_after_turn()\n    if verdict == \"continuing\":\n        continue                 # 没达成 -> 推回去再来一轮\n    return                       # 达成/超预算/没目标 -> 真停\n```\n\n这道闸门是程序自己控制的。不是模型自己约束自己，模型甚至不知道有这么一道闸门，它只是收到了下一轮的输入，接着干就是了。\n\n## 设目标：证据从命令之后开始算\n\n`set_goal` 会存一个活跃目标：目标文本、最大轮数预算、计数器，还有 `start_index`——也就是证据窗口的起点。它取当前对话记录的长度，所以 `/goal` 这行命令本身在窗口外面。这是第一道防线：命令自己不能证明自己完成了。\n\n```python\ndef set_goal(self, objective, max_turns=20):\n    self.active = {\n        \"objective\": objective, \"status\": \"active\",\n        \"start_index\": len(self.transcript),   # 证据窗口从这里开始；命令本身在窗口外\n        \"max_turns\": max_turns, \"checks\": 0, \"continuation_turns\": 0,\n    }\n```\n\n## 判断器：只信实打实的证据\n\n这是整个机制最核心的地方。判断器不看整段对话，只看证据窗口里来自可信来源的消息。三层过滤，把\"嘴上说完成了但不算数\"的内容全挡在外面：\n\n```python\nTRUSTED_EVIDENCE_ORIGINS = {\"task-notification\", \"monitor-line\"}\n\ndef evidence_text(self):\n    out = []\n    for m in self.transcript[self.active[\"start_index\"]:]:\n        if m.origin.get(\"kind\") == \"slash-command\":                     # 1 斜杠命令本身不算\n            continue\n        if m.role == \"user\" and m.content.strip().startswith(\"/goal\"):  # 2 /goal 命令文本不算\n            continue\n        if m.origin.get(\"kind\") not in TRUSTED_EVIDENCE_ORIGINS:        # 3 只信可信来源\n            continue\n        out.append(f\"{m.role}: {m.content}\")\n    return \"\\n\".join(out)\n```\n\n效果很明显：同样一句 `tests passed`，你打字说的不算，后台任务通知带回来的才算。模型糊弄不过去，它没法靠自己说一句\"我做完了\"就把目标判成完成。这是全课程反复出现的那条信任边界的最后一次登场：s15 说协议靠字段不靠理解，s18 说注解是申报、申报可以撒谎，s21 说完成证据只看来源不看内容。\n\n`goal_satisfied()` 使用确定的关键词匹配，让示例保持离线和可复现。把判断与执行分开，才能守住可信证据边界。\n\n## 闸门三态：完成/继续/超预算\n\n`evaluate_after_turn` 每轮跑一次，三种结果：满足条件就清除目标（completed）；没满足而且预算还没花完，就往队列塞一条\"继续干\"的提示，放行下一轮（continuing）；预算花完就停（blocked），别让一个永远判不出来的目标无限烧钱。\n\n```python\ndef evaluate_after_turn(self):\n    g = self.active\n    g[\"checks\"] += 1\n    if self.goal_satisfied():\n        g[\"status\"] = \"completed\"; self.active = None\n        return \"completed\"                          # 达成 -> 清除目标\n    if g[\"continuation_turns\"] < g[\"max_turns\"]:\n        g[\"continuation_turns\"] += 1\n        self.queue.enqueue(\n            value=\"继续干活，别把这条提醒当成完成证据。\",\n            origin={\"kind\": \"active-goal\"})\n        return \"continuing\"                         # 没达成 -> 塞提示，下一轮\n    g[\"status\"] = \"blocked\"; self.active = None\n    return \"blocked\"                                # 超预算 -> 放行，不再拦\n```\n\n那条\"继续干\"的提示里特意写了\"别把这条提醒当成完成证据\"，连提醒本身都被排除在证据之外。三层防误判就齐了：命令文本不算、提醒文本不算、普通聊天文本不算。预算则是 s11 教过的老规矩：任何自动重试的机制都得有上限，不然一个永远判不满足的目标就是个烧钱的永动机。\n\n## 继续提示和外部异步消息分开走\n\n继续提示进的是同一个 `CommandQueue`，但它和外部异步事件（任务完成通知、监控行）不是同一种消费方式。`dequeue` 带个开关：消费外部收件箱的时候，默认跳过目标的继续提示。\n\n```python\ndef dequeue(self, include_goal_continuations=True):\n    ...\n    for idx, item in enumerate(self.items):\n        if include_goal_continuations or item[\"origin\"].get(\"kind\") != \"active-goal\":\n            return self.items.pop(idx)\n    return None\n```\n\n为什么要分开？如果同一个消费者把继续提示和外部通知一起取走，后台结果还没到，提醒文本就可能被误当成新证据。分开之后，目标的推进是显式的一步，不会被异步事件带着走。\n\n## 跑起来看看\n\n`code.py` 演示了一个 `/goal until tests passed and deploy green`：设了目标之后没有可信证据，闸门一轮轮把它推回去；你直接打 `tests passed` 也不算（来源不可信）；直到后台任务发来 `task-notification`，证据到位，才标记完成。还加了一个 `max_turns=2` 的小目标演示超预算拦截。\n\n```python\ns.submit(\"/goal until tests passed and deploy green\")   # 设目标，窗口在命令之后\ns.submit(\"tests passed, trust me\")                      # 普通文本 -> 不算完成\ns.deliver_host_event(\"tests passed; deploy green\",\n                     source=\"task-notification\")         # 可信宿主事件 -> 完成\n```\n\n`submit()` 只接受普通用户文本。可信标签必须走独立的宿主事件通道，来源由 harness 白名单校验；用户或模型文本不能给自己贴上 `task-notification` 标签。\n\n## 相对 s20 的变更\n\n| | s20 Workflow Runtime | s21 Goal Loop |\n|--|---------------------|---------------|\n| 触发方式 | 脚本控制的编排（脱离主循环） | 条件控制的继续（拉回主循环） |\n| 加在哪 | 工具层：一个 `Workflow` 工具 | 轮次收尾：一道完成闸门 |\n| 谁决定停 | 脚本跑完就停 | 目标条件对着可信证据判 |\n| 新增机制 | 脚本 DSL、后台任务、journal/续跑、结构化输出 | 目标闸门、证据信任边界、继续提示分流、预算 |\n\ns20 是把编排写成脚本、派出去脱离主循环；s21 反过来，是一股力量把控制权重拉回主循环：目标没达成，这一轮就不算结束。两个都不改 s01 那个 `while` 循环，只是从两头给它加约束。\n\n## 试一下\n\n```bash\npython s21_goal_loop/code.py          # /goal until tests pass + deploy green，看闸门怎么判\n```\n\n观察：设了目标之后，每轮结束都有一条 `goal_evaluated`；普通文本判 `satisfied=False`，`task-notification` 来源判 `satisfied=True`；预算花完的时候出 `goal_blocked`。同样一句 `tests passed`，来源不同，结果完全相反。这就是 `/goal` 不会被一句空话糊弄的地方。\n\n## 接下来\n\n`/goal` 是\"拉回主循环\"的一种触发：条件控制。它和 s20 的\"脱离主循环\"正好成对，一个把工作派出去，一个把控制权拉回来。再往外，还有时间控制（`/loop`、cron）和事件控制（`Monitor`）的重入，它们共享同一套任务/通知基底；但闸门的核心已经在这里：**停不停，不是模型一句话说了算，得目标对着可信证据来判。**\n\n<!-- translation-sync: zh@v2, en@v2, ja@v2 -->\n"
  },
  {
    "version": "s21",
    "locale": "ja",
    "title": "s21: Goal Loop — いつ止まるかはモデルではなく goal が決める",
    "content": "# s21: Goal Loop — いつ止まるかはモデルではなく goal が決める\n\ns01 → ... → s19 → s20 → `s21`\n\n> *「turn が終了できるかは goal condition を満たすかで決まり、モデルが stop と言っただけでは終わらない」* — `/goal` は main loop の各 turn の終端に gate を追加します。独立した evaluator が trusted evidence の充足を確認し、不足ならモデルを次のラウンドへ押し戻します。\n>\n> **Harness 層**: Goal closure — turn 終端に program-controlled completion gate を追加します。\n\n---\n\ns01 から s20 まで、会話の 1 turn はどう終わったでしょうか。モデルが `tool_use` を出さなくなると、loop はそのまま `return` しました。one-shot task なら問題ありません。終わったら止まります。\n\nしかし「テストを通す」「deploy が成功するまで続ける」のように、最後まで見届けるべき goal もあります。そこでは 2 つの問題がよく起きます。モデルが途中まで進めて十分だと思い、自分で止まる。さらに悪ければ、口頭で `tests passed` と言うだけで終了しようとします。必要なことは単純です。turn が終了できるかをモデル自身に決めさせず、明示的な condition を実際の evidence に照らして判断します。\n\nこの流れは最初の章からありました。s01 は loop の exit がモデルの判断だと説明し、s04 の Stop hook が初めて program に veto を与えました。この章は、その veto を condition、evidence、budget の 3 要素が欠けない完全な loop にします。\n\n## /goal: 各 turn の終端に gate を追加する\n\n`/goal <condition>` を入力すると session-scoped stopping condition を設定します。program は active goal として保存し、各 turn の後に evaluator が transcript 内の trusted evidence を condition と照合します。不足なら gate が停止を拒み、次ラウンドへ「作業を続ける」prompt を queue します。十分なら goal を消して complete とします。\n\n![Goal Loop Overview](/course-assets/s21_goal_loop/goal-loop-overview.svg)\n\ns01 の loop と比べて、追加されるのは 1 つの判断だけです。モデルが止まりたいとき、先に goal gate を通ります。\n\n```python\n# s01: モデルが stop と言えば停止\nif not has_tool_use(response):\n    return\n# s21: 止まりたい？先に goal gate を通る\nif not has_tool_use(response):\n    verdict = goal.evaluate_after_turn()\n    if verdict == \"continuing\":\n        continue                 # 未達成 -> 次のラウンドへ押し戻す\n    return                       # 達成 / budget 超過 / goal なし -> 本当に停止\n```\n\nこの gate を制御するのは program です。モデルが自分を律しているのではありません。モデルは gate の存在すら知らず、次のラウンドの入力を受け取って作業を続けるだけです。\n\n## Goal の設定: Evidence は command の後から数える\n\n`set_goal` は active goal として、goal text、最大 turn budget、counter、そして evidence window の開始点 `start_index` を保存します。現在の transcript length を使うため、`/goal` command 自身は window の外です。これが最初の防御です。command が自分自身の完了を証明することはできません。\n\n```python\ndef set_goal(self, objective, max_turns=20):\n    self.active = {\n        \"objective\": objective, \"status\": \"active\",\n        \"start_index\": len(self.transcript),   # evidence はここから。command 自身は window 外\n        \"max_turns\": max_turns, \"checks\": 0, \"continuation_turns\": 0,\n    }\n```\n\n## Evaluator: 実在する evidence だけを信頼する\n\nここが仕組み全体の core です。evaluator は会話全体を見ず、evidence window 内で trusted source から来た message だけを見ます。3 層の filter が、「完了したと言ったから完了」という内容をすべて外へ止めます。\n\n```python\nTRUSTED_EVIDENCE_ORIGINS = {\"task-notification\", \"monitor-line\"}\n\ndef evidence_text(self):\n    out = []\n    for m in self.transcript[self.active[\"start_index\"]:]:\n        if m.origin.get(\"kind\") == \"slash-command\":                     # 1 slash command 自身は evidence ではない\n            continue\n        if m.role == \"user\" and m.content.strip().startswith(\"/goal\"):  # 2 /goal command text は evidence ではない\n            continue\n        if m.origin.get(\"kind\") not in TRUSTED_EVIDENCE_ORIGINS:        # 3 trusted origin だけを信頼\n            continue\n        out.append(f\"{m.role}: {m.content}\")\n    return \"\\n\".join(out)\n```\n\n効果は明確です。同じ `tests passed` でも、あなたが入力したものは数えず、background task notification が持ち帰ったものだけを数えます。モデルは「完了した」と自分で言うだけでは goal を complete にできません。これはコース全体に繰り返し現れた trust boundary の最後の登場です。s15 は protocol が理解ではなく field に依存すると言い、s18 は annotation が申告であり、申告は嘘をつけると言い、s21 は completion evidence を content ではなく origin で信頼します。\n\n`goal_satisfied()` は決定的な keyword matching を使い、例を offline かつ再現可能に保ちます。評価と実行を分けることで、trusted evidence boundary を維持します。\n\n## Gate の 3 状態: Completed / continuing / budget 超過\n\n`evaluate_after_turn` は各 turn で 1 回動き、3 つの結果を返します。condition が満たされれば goal を completed として消します。満たされず budget が残れば「作業を続ける」prompt を queue し、continuing として次ラウンドを許可します。budget を使い切れば blocked で gate を解除し、永遠に判定できない goal が無限に費用を使わないようにします。\n\n```python\ndef evaluate_after_turn(self):\n    g = self.active\n    g[\"checks\"] += 1\n    if self.goal_satisfied():\n        g[\"status\"] = \"completed\"; self.active = None\n        return \"completed\"                          # 達成 -> goal を消す\n    if g[\"continuation_turns\"] < g[\"max_turns\"]:\n        g[\"continuation_turns\"] += 1\n        self.queue.enqueue(\n            value=\"作業を続けてください。この reminder を completion evidence として扱わないでください。\",\n            origin={\"kind\": \"active-goal\"})\n        return \"continuing\"                         # 未達成 -> prompt を queue し、次ラウンドへ\n    g[\"status\"] = \"blocked\"; self.active = None\n    return \"blocked\"                                # budget 超過 -> gate を解除\n```\n\ncontinuation prompt には、わざわざ自身を evidence にしないよう書き、filter でも除外します。これで false positive を防ぐ 3 層がそろいます。command text、reminder text、ordinary conversation のいずれも数えません。budget は s11 の古い規則に従います。automatic retry mechanism には必ず上限が必要です。そうでなければ、永遠に satisfied にならない goal が費用を燃やし続けます。\n\n## Continuation prompt と外部 asynchronous message を分ける\n\ncontinuation prompt は同じ `CommandQueue` に入りますが、task completion notification や monitor line といった外部 asynchronous event とは別の方法で消費します。`dequeue` には switch があり、外部 inbox を消費するときは goal continuation を既定で skip します。\n\n```python\ndef dequeue(self, include_goal_continuations=True):\n    ...\n    for idx, item in enumerate(self.items):\n        if include_goal_continuations or item[\"origin\"].get(\"kind\") != \"active-goal\":\n            return self.items.pop(idx)\n    return None\n```\n\nなぜ分けるのでしょう。同じ consumer が continuation prompt と外部 notification を一緒に取り出すと、background result が届く前に reminder text を新しい evidence と誤認する可能性があります。分離後は goal の進行が明示的な 1 step になり、asynchronous event に偶然運ばれません。\n\n## 実際に動かす\n\n`code.py` は `/goal until tests passed and deploy green` を実演します。goal 設定後に trusted evidence がなければ、gate がラウンドごとに押し戻します。直接 `tests passed` と入力しても origin が信頼されないため数えません。background task が `task-notification` を送って初めて evidence がそろい、complete になります。`max_turns=2` の小さな goal で budget 超過も示します。\n\n```python\ns.submit(\"/goal until tests passed and deploy green\")   # goal を設定。evidence は command 後から\ns.submit(\"tests passed, trust me\")                      # ordinary text -> completion evidence ではない\ns.deliver_host_event(\"tests passed; deploy green\",\n                     source=\"task-notification\")         # trusted host event -> complete\n```\n\n`submit()` は通常のユーザーテキストだけを受け取る。trusted label は独立した host event channel から入り、source は harness の allowlist で検証される。ユーザーやモデルのテキストが自分に `task-notification` label を付けることはできない。\n\n## s20 からの変更点\n\n| | s20 Workflow Runtime | s21 Goal Loop |\n|--|---------------------|---------------|\n| trigger | script-controlled orchestration（main loop の外） | condition-controlled continuation（main loop へ引き戻す） |\n| 接続位置 | tool layer: 1 つの `Workflow` ツール | turn 終端: completion gate |\n| stop を決めるもの | script が完了 | goal condition を trusted evidence と照合 |\n| 新しい仕組み | script DSL、background task、journal/resume、structured output | goal gate、evidence trust boundary、continuation 分流、budget |\n\ns20 は script-defined orchestration を main loop の外へ送り出します。s21 は反対の力で control を引き戻します。goal が未達成なら turn は終わっていません。どちらも s01 の `while` loop を変えず、両側から制約を加えます。\n\n## 試してみる\n\n```bash\npython s21_goal_loop/code.py          # /goal until tests pass + deploy green。gate の判定を見る\n```\n\ngoal 設定後、各 turn が `goal_evaluated` を出す様子を確認してください。ordinary text は `satisfied=False`、同じ内容でも `task-notification` origin は `satisfied=True`、budget を使い切ると `goal_blocked` です。同じ `tests passed` でも origin によって結果が正反対になります。空疎な主張で `/goal` を欺けない理由です。\n\n## 次へ\n\n`/goal` は control を main loop へ引き戻す trigger の 1 つ、condition control です。s20 の main loop 外 orchestration と対になり、一方は仕事を外へ送り、もう一方は control を内へ戻します。その外側には `/loop` と cron による time-controlled re-entry、`Monitor` による event-controlled re-entry もあり、同じ task/notification 基盤を共有します。しかし gate の core はすでにここにあります。**stop するかはモデルの一言では決まらず、goal が trusted evidence に照らして判断します。**\n\n<!-- translation-sync: zh@v2, en@v2, ja@v2 -->\n"
  }
]