feat: consolidate course into 21 lessons

2026-09-20 12:13:38 +08:00 · 2026-07-31 03:15:58 +08:00
parent 4bc33ec858
commit 2d69019342
200 changed files with 7338 additions and 10829 deletions
--- a/s19_comprehensive/README.ja.md
+++ b/s19_comprehensive/README.ja.md
@@ -0,0 +1,254 @@
+# s19: Comprehensive Agent — すべての仕組みを 1 つのループへ
+
+[English](README.md) · [中文](README.zh.md) · [日本語](README.ja.md)
+
+s01 → ... → s17 → s18 → `s19` → [s20](../s20_workflow_runtime/) → s21
+
+> *"仕組みは多い、ループは 1 つ"* — tools、permissions、memory、tasks、teams、plugins はすべて同じ `while True` に接続される。
+>
+> **Harness レイヤー**: 総合 — s01-s18 の仕組みを 1 つの実行可能なシステムへ戻す。
+
+---
+
+## 問題
+
+前 18 章では、各境界を観察できるように仕組みを一つずつ追加した。本章では、それらを一つのランタイムへ接続する。
+
+長時間動く coding agent には、同時に次のものが必要になる：
+
+- tool dispatch と permission boundary
+- hook extension point
+- todo plan と task graph
+- skill、memory、runtime system prompt assembly
+- compaction と error recovery
+- background task と cron scheduling
+- team、protocol、autonomous claiming
+- worktree isolation
+- MCP external tool integration
+
+難しいのは機能を積み上げることではない。それぞれの仕組みが loop のどこに接続されるかを見抜くことだ。S19 は統合チェックポイントであり、これまでの component を 1 つの harness に戻してから、s20-s21 が編成と目標完了を外側に追加する。
+
+---
+
+## 解決策
+
+![System Architecture](images/system-architecture.ja.svg)
+
+S19 は新しい mechanism を追加せず、前章までの component を 1 つの完全な harness に統合する：
+
+```text
+user input
+  → UserPromptSubmit hooks
+  → cron/background notification injection
+  → context compact
+  → memory + skills + MCP state で system prompt を組み立てる
+  → LLM
+  → has tool_use block?
+      no  → Stop hooks → return
+      yes → PreToolUse hooks + permission
+          → TOOL_HANDLERS / MCP handlers / background dispatch
+          → PostToolUse hooks
+          → tool_result / task_notification を messages へ戻す
+          → next round
+```
+
+loop 自体は同じ構造のままだ。model を呼び、response に `tool_use` block があるかを見て、tool を実行し、結果を `messages` に戻す。tool 実行を続けるかどうかは、実際の `tool_use` block の有無で決まる。
+
+---
+
+## 各 Component の位置
+
+| 位置 | Component | 役割 |
+|------|-----------|------|
+| user input 周辺 | `UserPromptSubmit` hooks | user input の記録、注入、監査 |
+| LLM 前 | cron queue | scheduled prompt を `messages` へ注入 |
+| LLM 前 | background notifications | 完了した background work を `<task_notification>` として注入 |
+| LLM 前 | compaction pipeline | 大きな出力を予算化し、履歴を切り、古い tool_result を圧縮し、必要なら要約 |
+| LLM 前 | memory / skills / MCP state | current capabilities と long-term context を system prompt に組み込む |
+| LLM call | error recovery | 429/529 retry、`max_tokens` escalation、prompt-too-long compact |
+| tool 実行前 | `PreToolUse` hooks + permission | 危険な command、範囲外 write、destructive MCP tool を止める |
+| tool dispatch | `assemble_tool_pool` | built-in tools と dynamic MCP tools を組み立てる |
+| tool 実行中 | background dispatch | 遅い bash work を daemon thread に逃がし、placeholder result を返す |
+| tool 実行後 | `PostToolUse` hooks | large-output warning、log、後処理 |
+| loop へ戻る | tool_result | 1 つの `tool_use` に 1 つの `tool_result`、そして次の model round |
+| tool_use がない round / stop 時 | `Stop` hooks | 統計、cleanup、audit |
+
+---
+
+## code.py に含まれるもの
+
+### Tools と Dispatch
+
+built-in tool pool には 26 個の tool がある：
+
+```text
+bash, read_file, write_file, edit_file, glob
+todo_write, task, load_skill, compact
+create_task, list_tasks, get_task, claim_task, complete_task
+schedule_cron, list_crons, cancel_cron
+spawn_teammate, send_message
+request_shutdown, request_plan, review_plan
+create_worktree, remove_worktree, keep_worktree
+connect_mcp
+```
+
+`assemble_tool_pool()` は毎 round で次を組み立てる：
+
+```text
+BUILTIN_TOOLS + connected MCP tools
+BUILTIN_HANDLERS + mcp__server__tool handlers
+```
+
+`connect_mcp("docs")` のあと、次の round では `mcp__docs__search` のような tool が出現する。
+
+### Permission と Hooks
+
+permission は tool 実行行に直接埋め込まない。`PreToolUse` hook として扱う：
+
+```python
+blocked = trigger_hooks("PreToolUse", block)
+if blocked:
+    results.append(tool_result(block.id, blocked))
+    continue
+```
+
+これにより permission、logging、audit が同じ hook point に接続できる。実行後には `PostToolUse` hook が走る。
+
+### Plan と Task
+
+S19 には 2 層の plan がある：
+
+- `todo_write`: current session 用の軽量 plan。メモリに保持。
+- task graph: cross-session、dependency-aware、claimable な task file。`.tasks/task_*.json` に保存。
+
+前者は単独 agent の drift を防ぐ。後者は team coordination の土台になる。
+
+目的は近いが実装は別である。`todo_write` は現在のセッションのチェックリスト全体を置き換え、task record は安定 ID と個別のライフサイクル更新を持つ。次節の独立した `task` ツールは「隔離 subagent を一度派遣する」意味であり、Task System ではない。
+
+### Subagent と Team
+
+S19 には 2 種類の delegation がある：
+
+- `task`: one-shot subagent。独立した `messages[]` を使い、中間 context を捨て、final summary だけ返す。
+- `spawn_teammate`: persistent teammate thread。ランタイムが `MessageBus` event を自動配信し、teammate は idle 中に task board を確認して自律的に claim できる。
+
+one-shot subagent は context isolation を解決する。persistent teammate は長期並列協作を解決する。
+
+### Memory、Skills、Prompt
+
+`assemble_system_prompt(context)` は毎 round 次を組み立てる：
+
+- identity と tool guidance
+- workspace
+- skills catalog
+- `.memory/MEMORY.md`
+- connected MCP servers
+
+skills は system prompt には catalog だけ置く。全文は `load_skill(name)` で必要な時に読む。
+
+### Compaction と Recovery
+
+LLM call の前に compaction pipeline を走らせる：
+
+```text
+tool_result_budget → snip_compact → micro_compact → compact_history
+```
+
+model call は recovery で包む：
+
+- 429: exponential backoff retry
+- 529: exponential backoff、連続失敗時は fallback model へ切替可能
+- `max_tokens`: max tokens を上げ、その後 continuation を要求
+- prompt too long: reactive compact 後に retry
+
+### Background と Cron
+
+遅い bash work は main loop を止めない：
+
+```text
+should_run_background → start_background_task → placeholder tool_result
+background done → task_notification → next round injects messages
+```
+
+cron scheduler は daemon thread として動き、1 秒ごとに確認する。CLI は `cron_queue` を監視し、発火した job を `[Scheduled] ...` として注入して Agent を 1 turn 自動実行する。
+
+### Worktree と MCP
+
+worktree isolation は directory を担当する：
+
+- `create_worktree(name, task_id)` が isolated branch と directory を作る
+- task の `worktree` field が task と directory を紐付ける
+- teammate が worktree 付き task を claim すると、bash/read/write はその directory で実行される
+
+MCP は external capability を担当する：
+
+- `connect_mcp(name)` が mock server に接続する
+- `assemble_tool_pool()` が MCP tools を tool pool に組み立てる
+- tool name は `mcp__server__tool` 形式に統一する
+
+---
+
+## s18 からの変化
+
+| Component | s18 | s19 |
+|-----------|-----|-----|
+| tool pool | built-in + MCP | built-in + MCP、s01-s17 の tool を補完 |
+| permission | s18 の対象外 | `PreToolUse` hook で実行 |
+| hooks | s18 の対象外 | UserPromptSubmit / PreToolUse / PostToolUse / Stop |
+| todo | s18 の対象外 | `todo_write` + reminder |
+| skill | s18 の対象外 | system prompt の catalog + `load_skill` |
+| compact | s18 の対象外 | LLM 前 compaction + `compact` tool + reactive compact |
+| error recovery | simple try/except | retry / max_tokens / prompt too long |
+| background | s18 の対象外 | slow-operation thread + task notification |
+| cron | s18 の対象外 | daemon scheduler + durable jobs |
+| multi-agent | 維持 | 維持。teammate は isolated directory 上の basic tools を使う |
+| worktree | 維持 | 維持 |
+| MCP | 新規 | final tool pool の一部として維持 |
+
+---
+
+## 試す
+
+```sh
+cd learn-claude-code
+python s19_comprehensive/code.py
+```
+
+試す prompt：
+
+1. `このリポジトリを調べ、重要な Python ファイルを教えてください。`
+2. `接続済みのドキュメントから agent loop の説明を探してください。`
+3. `認証モジュールとログインページを隔離した worktree で並行してリファクタリングし、編集前にそれぞれのプランを見せてください。`
+4. `3 分後に会議を知らせてください。`
+5. `依存関係をバックグラウンドでインストールしながら README.md を読んでください。`
+
+見るポイント：
+
+- tool call の前に hooks/permission を通るか
+- `connect_mcp` 後の次 round で MCP tool が出るか
+- 遅い operation が background placeholder を返すか
+- cron が時刻到達時に自動で reminder を返すか
+- teammate が plan を提出し、approval 前に停止するか
+- plan approval 後、teammate が task を claim できるか
+- worktree binding 後、teammate が対応 directory に切り替わるか
+
+---
+
+## 終わりは始まり
+
+s01 から s19 まで、コードの能力は増えていく。しかし中心は変わらない：
+
+```python
+while True:
+    response = LLM(messages, tools)
+    if not has_tool_use(response.content):
+        return
+    results = execute_tools(response.content)
+    messages.append(tool_results)
+```
+
+成熟した harness の複雑さは model 周辺の協調機構から生まれる。model は判断と action selection を担当し、harness は environment、tools、permissions、memory、teams、external capabilities を整理する。
+
+これは本コースの統合チェックポイントだ：仕組みは多い、ループは 1 つ。
+
+次へ：[s20 Workflow Runtime](../s20_workflow_runtime/) — 編成の形が固定なら、多数の会話ターンではなく、決定的で再開可能なコードへ移す。
--- a/s19_comprehensive/README.md
+++ b/s19_comprehensive/README.md
@@ -0,0 +1,254 @@
+# s19: Comprehensive Agent — All Mechanisms, One Loop
+
+[English](README.md) · [中文](README.zh.md) · [日本語](README.ja.md)
+
+s01 → ... → s17 → s18 → `s19` → [s20](../s20_workflow_runtime/) → s21
+
+> *"Many mechanisms, one loop"* — tools, permissions, memory, tasks, teams, and plugins all hang off the same `while True`.
+>
+> **Harness layer**: Comprehensive — put the mechanisms from s01-s18 into one runnable system.
+
+---
+
+## Problem
+
+The first 18 chapters add one mechanism at a time so each boundary stays visible. This chapter connects them in one runtime.
+
+A long-running coding agent needs all of these at once:
+
+- tool dispatch and permission boundaries
+- hook extension points
+- todo planning and task graphs
+- skills, memory, and runtime system prompt assembly
+- compaction and error recovery
+- background tasks and cron scheduling
+- teams, protocols, autonomous claiming
+- worktree isolation
+- MCP external tool integration
+
+The 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.
+
+---
+
+## Solution
+
+![System Architecture](images/system-architecture.en.svg)
+
+S19 does not introduce a new mechanism. It connects the components from the earlier chapters in one complete harness:
+
+```text
+user input
+  → UserPromptSubmit hooks
+  → cron/background notification injection
+  → context compact
+  → memory + skills + MCP state assemble the system prompt
+  → LLM
+  → has tool_use block?
+      no  → Stop hooks → return
+      yes → PreToolUse hooks + permission
+          → TOOL_HANDLERS / MCP handlers / background dispatch
+          → PostToolUse hooks
+          → tool_result / task_notification back to messages
+          → next round
+```
+
+The 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.
+
+---
+
+## Where Each Component Sits
+
+| Position | Component | Role |
+|----------|-----------|------|
+| Around user input | `UserPromptSubmit` hooks | Log, inject, or audit user input |
+| Before LLM | cron queue | Inject scheduled prompts into `messages` |
+| Before LLM | background notifications | Inject completed background work as `<task_notification>` |
+| Before LLM | compaction pipeline | Budget large outputs, trim history, compact old tool results, summarize when needed |
+| Before LLM | memory / skills / MCP state | Assemble the system prompt so the model sees current capabilities and long-term context |
+| LLM call | error recovery | Retry 429/529, escalate `max_tokens`, compact on prompt-too-long |
+| Before tool execution | `PreToolUse` hooks + permission | Block dangerous commands, out-of-bounds writes, destructive MCP tools |
+| Tool dispatch | `assemble_tool_pool` | Assemble built-in tools and dynamic MCP tools |
+| During tool execution | background dispatch | Move slow bash work into a daemon thread and return a placeholder result |
+| After tool execution | `PostToolUse` hooks | Large-output warnings, logs, post-processing |
+| Back to loop | tool_result | One `tool_result` per `tool_use`, then the next model round |
+| No tool_use this round / on stop | `Stop` hooks | Stats, cleanup, audit |
+
+---
+
+## What code.py Contains
+
+### Tools and Dispatch
+
+The built-in tool pool contains 26 tools:
+
+```text
+bash, read_file, write_file, edit_file, glob
+todo_write, task, load_skill, compact
+create_task, list_tasks, get_task, claim_task, complete_task
+schedule_cron, list_crons, cancel_cron
+spawn_teammate, send_message
+request_shutdown, request_plan, review_plan
+create_worktree, remove_worktree, keep_worktree
+connect_mcp
+```
+
+`assemble_tool_pool()` assembles these every round:
+
+```text
+BUILTIN_TOOLS + connected MCP tools
+BUILTIN_HANDLERS + mcp__server__tool handlers
+```
+
+After `connect_mcp("docs")`, the next round exposes tools like `mcp__docs__search`.
+
+### Permissions and Hooks
+
+Permission is not hardcoded into the tool execution line. It is a `PreToolUse` hook:
+
+```python
+blocked = trigger_hooks("PreToolUse", block)
+if blocked:
+    results.append(tool_result(block.id, blocked))
+    continue
+```
+
+That means permission, logging, and audit logic all attach to the same hook point. After execution, `PostToolUse` hooks run.
+
+### Planning and Tasks
+
+S19 keeps two planning layers:
+
+- `todo_write`: lightweight plan for the current session, kept in memory
+- task graph: cross-session, dependency-aware, claimable task files under `.tasks/task_*.json`
+
+The first keeps a single agent from drifting. The second supports team coordination.
+
+They 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.
+
+### Subagents and Teams
+
+S19 has two kinds of delegation:
+
+- `task`: one-shot subagent. It uses an isolated `messages[]`, discards intermediate context, and returns only a final summary.
+- `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.
+
+One-shot subagents solve context isolation. Persistent teammates solve long-running parallel collaboration.
+
+### Memory, Skills, and Prompt
+
+`assemble_system_prompt(context)` assembles each round from:
+
+- identity and tool guidance
+- workspace
+- skills catalog
+- `.memory/MEMORY.md`
+- connected MCP servers
+
+Skills only put their catalog into the system prompt. Full content is loaded on demand through `load_skill(name)`.
+
+### Compaction and Recovery
+
+Before the LLM call, S19 runs the compaction pipeline:
+
+```text
+tool_result_budget → snip_compact → micro_compact → compact_history
+```
+
+The model call is wrapped with recovery:
+
+- 429: exponential backoff retry
+- 529: exponential backoff, optionally switch to fallback model after repeated failures
+- `max_tokens`: raise max tokens, then request continuation
+- prompt too long: reactive compact and retry
+
+### Background and Cron
+
+Slow bash work does not block the main loop:
+
+```text
+should_run_background → start_background_task → placeholder tool_result
+background done → task_notification → next round injects messages
+```
+
+The 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.
+
+### Worktree and MCP
+
+Worktree isolation owns directories:
+
+- `create_worktree(name, task_id)` creates an isolated branch and directory
+- the task `worktree` field binds a task to that directory
+- when a teammate claims a task with a worktree, its bash/read/write tools run in that directory
+
+MCP owns external capability:
+
+- `connect_mcp(name)` connects a mock server
+- `assemble_tool_pool()` assembles MCP tools into the tool pool
+- tool names use `mcp__server__tool`
+
+---
+
+## Changes from s18
+
+| Component | s18 | s19 |
+|-----------|-----|-----|
+| tool pool | built-in + MCP | built-in + MCP, with s01-s17 tools restored |
+| permission | outside s18's scope | runs inside `PreToolUse` hook |
+| hooks | outside s18's scope | UserPromptSubmit / PreToolUse / PostToolUse / Stop |
+| todo | outside s18's scope | `todo_write` + reminder |
+| skill | outside s18's scope | catalog in system prompt + `load_skill` |
+| compact | outside s18's scope | pre-LLM compaction + `compact` tool + reactive compact |
+| error recovery | simple try/except | retry / max_tokens / prompt too long |
+| background | outside s18's scope | slow-operation thread + task notification |
+| cron | outside s18's scope | daemon scheduler + durable jobs |
+| multi-agent | kept | kept; teammates use basic tools in isolated directories |
+| worktree | kept | kept |
+| MCP | new | kept as part of the final tool pool |
+
+---
+
+## Try It
+
+```sh
+cd learn-claude-code
+python s19_comprehensive/code.py
+```
+
+Try:
+
+1. `Inspect this repository and tell me which Python files matter most.`
+2. `Search the connected documentation for agent loop guidance.`
+3. `Refactor the authentication module and login page in parallel in isolated worktrees. Show me each plan before editing.`
+4. `Remind me about the meeting in 3 minutes.`
+5. `Install the dependencies in the background while you read README.md.`
+
+Watch for:
+
+- whether each tool call passes through hooks/permission
+- whether MCP tools appear on the next round after `connect_mcp`
+- whether slow operations return a background placeholder
+- whether cron automatically reminds you when the time arrives
+- whether teammates submit plans and pause before approval
+- whether teammates can claim tasks after plan approval
+- whether teammates switch to the bound worktree directory
+
+---
+
+## The End Is the Beginning
+
+From s01 to s19, the code gets more capable, but the core remains unchanged:
+
+```python
+while True:
+    response = LLM(messages, tools)
+    if not has_tool_use(response.content):
+        return
+    results = execute_tools(response.content)
+    messages.append(tool_results)
+```
+
+A 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.
+
+This is the course's integration checkpoint: many mechanisms, one loop.
+
+Next: [s20 Workflow Runtime](../s20_workflow_runtime/) — when the orchestration shape is fixed, move it out of chat turns and into deterministic, resumable code.
--- a/s19_comprehensive/README.zh.md
+++ b/s19_comprehensive/README.zh.md
@@ -0,0 +1,254 @@
+# s19: Comprehensive Agent — 全部机制，归到一个循环
+
+[English](README.md) · [中文](README.zh.md) · [日本語](README.ja.md)
+
+s01 → ... → s17 → s18 → `s19` → [s20](../s20_workflow_runtime/) → s21
+
+> *"机制很多，循环一个"* — 工具、权限、记忆、任务、团队、插件都挂在同一个 while True 上。
+>
+> **Harness 层**: 综合 — 把 s01-s18 的机制放回同一个可运行系统。
+
+---
+
+## 问题
+
+前 18 章每章只加一个机制，让每个边界都能单独观察。本章把它们接入同一个运行时。
+
+一个能长期工作的 coding agent 需要同时拥有：
+
+- 工具分发和权限边界
+- hooks 扩展点
+- todo 计划和任务图
+- 技能、记忆、系统 prompt 组装
+- 压缩和错误恢复
+- 后台任务和 cron 调度
+- 团队、协议、自治认领
+- worktree 隔离
+- MCP 外部工具接入
+
+难点不是把功能堆起来，而是看清楚它们都挂在循环的哪个位置。S19 是集成检查点：先把此前组件归位，再由 s20-s21 在外层加入编排与目标闭环。
+
+---
+
+## 解决方案
+
+![System Architecture](images/system-architecture.svg)
+
+S19 不再引入新机制，而是把前面各章的组件接入一个完整 harness：
+
+```text
+用户输入
+  → UserPromptSubmit hooks
+  → cron/background 通知注入
+  → context compact
+  → memory + skills + MCP 状态组装 system prompt
+  → LLM
+  → has tool_use block?
+      否 → Stop hooks → 返回
+      是 → PreToolUse hooks + permission
+          → TOOL_HANDLERS / MCP handlers / background dispatch
+          → PostToolUse hooks
+          → tool_result / task_notification 回 messages
+          → 下一轮
+```
+
+循环仍是同一个结构：调用模型，检查响应里是否出现 `tool_use` block，执行工具，再把结果追加回 `messages`。是否继续工具轮，由响应中有没有实际的 `tool_use` block 决定。
+
+---
+
+## 组件在循环中的位置
+
+| 位置 | 组件 | 作用 |
+|------|------|------|
+| 用户输入前后 | `UserPromptSubmit` hooks | 记录、注入、审计用户输入 |
+| LLM 前 | cron queue | 把定时触发的 prompt 注入 `messages` |
+| LLM 前 | background notifications | 后台任务完成后以 `<task_notification>` 注入 |
+| LLM 前 | compaction pipeline | 先压大输出，再裁历史，再压旧 tool_result，必要时摘要 |
+| LLM 前 | memory / skills / MCP state | 组装 system prompt，让模型看到当前能力和长期上下文 |
+| LLM 调用 | error recovery | 429/529 重试，`max_tokens` 升级，prompt too long 触发 reactive compact |
+| 工具执行前 | `PreToolUse` hooks + permission | 拦截危险命令、写越界、破坏性 MCP 工具 |
+| 工具分发 | `assemble_tool_pool` | 组装内置工具和 MCP 动态工具 |
+| 工具执行时 | background dispatch | 慢 bash 操作放 daemon thread，主循环先返回占位结果 |
+| 工具执行后 | `PostToolUse` hooks | 大输出告警、日志等后处理 |
+| 返回循环 | tool_result | 每个 `tool_use` 对应一个 `tool_result`，再回到下一轮 |
+| 本轮没有 tool_use / 停止时 | `Stop` hooks | 统计、清理、审计 |
+
+---
+
+## code.py 包含什么
+
+### 工具与分发
+
+内置工具池包含 26 个工具：
+
+```text
+bash, read_file, write_file, edit_file, glob
+todo_write, task, load_skill, compact
+create_task, list_tasks, get_task, claim_task, complete_task
+schedule_cron, list_crons, cancel_cron
+spawn_teammate, send_message
+request_shutdown, request_plan, review_plan
+create_worktree, remove_worktree, keep_worktree
+connect_mcp
+```
+
+`assemble_tool_pool()` 每轮组装：
+
+```text
+BUILTIN_TOOLS + connected MCP tools
+BUILTIN_HANDLERS + mcp__server__tool handlers
+```
+
+所以 `connect_mcp("docs")` 后，下一轮工具池里会出现 `mcp__docs__search`。
+
+### 权限和 hooks
+
+权限不写死在工具执行行里，而是作为 `PreToolUse` hook：
+
+```python
+blocked = trigger_hooks("PreToolUse", block)
+if blocked:
+    results.append(tool_result(block.id, blocked))
+    continue
+```
+
+这样 permission、log、审计都可以挂在同一个 hook 点上。执行后再触发 `PostToolUse`。
+
+### 计划与任务
+
+S19 同时保留两层计划：
+
+- `todo_write`：当前会话内的轻量计划，保存在内存中
+- task graph：跨会话、可依赖、可认领的任务文件，写入 `.tasks/task_*.json`
+
+前者帮助单个 Agent 不漂移；后者支撑团队协作。
+
+两者目标相近，但实现不同：`todo_write` 整表替换当前会话清单，task record 则有稳定 ID 和单条生命周期更新。下面单独出现的 `task` 工具表示“一次性派发隔离 subagent”，不是 Task System。
+
+### 子 agent 与团队
+
+S19 有两种 delegation：
+
+- `task`：一次性 subagent。独立 `messages[]`，中间过程丢弃，只返回最终摘要。
+- `spawn_teammate`：持久队友线程。运行时自动投递 MessageBus 事件，队友在 idle 时扫描任务板并自主认领。
+
+一次性 subagent 解决“上下文隔离”；持久队友解决“长期并行协作”。
+
+### 记忆、技能和 prompt
+
+`assemble_system_prompt(context)` 每轮组装：
+
+- 身份和工具说明
+- workspace
+- skills catalog
+- `.memory/MEMORY.md`
+- 已连接 MCP server
+
+技能只在 system prompt 里放目录。完整内容通过 `load_skill(name)` 按需加载。
+
+### 压缩和恢复
+
+LLM 前先跑压缩管线：
+
+```text
+tool_result_budget → snip_compact → micro_compact → compact_history
+```
+
+调用模型时再包一层恢复：
+
+- 429：指数退避重试
+- 529：指数退避，连续失败可切 fallback model
+- `max_tokens`：先提高 max_tokens，再要求 continuation
+- prompt too long：reactive compact 后重试
+
+### 后台和 cron
+
+慢 bash 操作不会阻塞主循环：
+
+```text
+should_run_background → start_background_task → placeholder tool_result
+后台完成 → task_notification → 下一轮注入 messages
+```
+
+cron 调度器独立 daemon thread 每秒检查一次。CLI 会监听 `cron_queue`，命中后主动把 `[Scheduled] ...` 注入并运行一轮 Agent。
+
+### worktree 与 MCP
+
+worktree 负责隔离目录：
+
+- `create_worktree(name, task_id)` 创建独立分支和目录
+- task 的 `worktree` 字段绑定目录
+- 队友 claim 到带 worktree 的 task 后，bash/read/write 自动在对应目录下执行
+
+MCP 负责外部能力：
+
+- `connect_mcp(name)` 连接 mock server
+- `assemble_tool_pool()` 把 MCP 工具组装进工具池
+- 工具名统一为 `mcp__server__tool`
+
+---
+
+## 相对 s18 的变化
+
+| 组件 | s18 | s19 |
+|------|-----|-----|
+| 工具池 | 内置 + MCP | 内置 + MCP，补齐 s01-s17 的工具 |
+| 权限 | 不在 s18 范围内 | `PreToolUse` hook 中执行 |
+| hooks | 不在 s18 范围内 | UserPromptSubmit / PreToolUse / PostToolUse / Stop |
+| todo | 不在 s18 范围内 | `todo_write` + reminder |
+| skill | 不在 s18 范围内 | catalog in system prompt + `load_skill` |
+| compact | 不在 s18 范围内 | LLM 前压缩 + `compact` 工具 + reactive compact |
+| error recovery | 简化 try/except | retry / max_tokens / prompt too long |
+| background | 不在 s18 范围内 | 慢操作后台线程 + task notification |
+| cron | 不在 s18 范围内 | daemon scheduler + durable jobs |
+| multi-agent | 保留 | 保留；队友使用隔离目录下的基础工具 |
+| worktree | 保留 | 保留 |
+| MCP | 新增 | 保留，作为最终工具池的一部分 |
+
+---
+
+## 试一下
+
+```sh
+cd learn-claude-code
+python s19_comprehensive/code.py
+```
+
+可以试：
+
+1. `检查这个仓库，告诉我哪些 Python 文件最重要。`
+2. `从已连接的文档中查一下 agent loop 的相关说明。`
+3. `请在隔离的 worktree 中并行重构认证模块和登录页，修改前先把各自的计划给我看。`
+4. `3 分钟后提醒我开会。`
+5. `在后台安装依赖，同时继续阅读 README.md。`
+
+观察重点：
+
+- 工具调用前是否经过 hooks/permission
+- `connect_mcp` 后下一轮是否出现 MCP 工具
+- 慢操作是否返回 background placeholder
+- 到点是不是自动提醒开会
+- 队友是否提交 plan，并在 approval 前暂停
+- plan 批准后，队友是否能认领任务
+- worktree 绑定后，队友是否切到对应目录
+
+---
+
+## 结束亦是开始
+
+从 s01 到 s19，代码表面越来越复杂，但核心始终没变：
+
+```python
+while True:
+    response = LLM(messages, tools)
+    if not has_tool_use(response.content):
+        return
+    results = execute_tools(response.content)
+    messages.append(tool_results)
+```
+
+成熟 harness 的复杂性来自模型周围的协作机制。模型负责判断和行动选择，harness 负责组织环境、工具、权限、记忆、团队和外部能力。
+
+这是课程的集成检查点：机制很多，循环一个。
+
+下一章：[s20 Workflow Runtime](../s20_workflow_runtime/) — 当编排形状固定时，把它从多轮对话移入确定性、可恢复的代码。
--- a/s19_comprehensive/code.py
+++ b/s19_comprehensive/code.py
--- a/s19_comprehensive/images/system-architecture.en.svg
+++ b/s19_comprehensive/images/system-architecture.en.svg
@@ -0,0 +1,85 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 920 620" font-family="'Noto Sans CJK SC', 'Droid Sans Fallback', system-ui, -apple-system, sans-serif">
+  <defs>
+    <linearGradient id="header" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#1e3a5f"/>
+      <stop offset="100%" stop-color="#0f766e"/>
+    </linearGradient>
+    <marker id="arrow" viewBox="0 0 10 10" refX="10" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#475569"/>
+    </marker>
+    <marker id="arrow-green" viewBox="0 0 10 10" refX="10" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#059669"/>
+    </marker>
+    <marker id="arrow-purple" viewBox="0 0 10 10" refX="10" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#7c3aed"/>
+    </marker>
+    <marker id="arrow-orange" viewBox="0 0 10 10" refX="10" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#ea580c"/>
+    </marker>
+  </defs>
+  <rect width="920" height="620" rx="8" fill="#fafbfc"/>
+  <rect x="0" y="0" width="920" height="46" rx="8" fill="url(#header)"/>
+  <rect x="0" y="38" width="920" height="8" fill="url(#header)"/>
+  <text x="460" y="29" text-anchor="middle" fill="#fff" font-size="17" font-weight="700">s19 Comprehensive Agent — Every Mechanism Around One Loop</text>
+  <rect x="40" y="76" width="840" height="212" rx="8" fill="#eef2ff" stroke="#2563eb" stroke-width="1.8"/>
+  <text x="460" y="101" text-anchor="middle" fill="#1e3a8a" font-size="13" font-weight="700">Core Agent Loop</text>
+  <rect x="70" y="128" width="110" height="48" rx="7" fill="#fff" stroke="#2563eb" stroke-width="1.4"/>
+  <text x="125" y="157" text-anchor="middle" fill="#1e3a5f" font-size="11" font-weight="700">messages[]</text>
+  <line x1="180" y1="152" x2="222" y2="152" stroke="#475569" stroke-width="1.5" marker-end="url(#arrow)"/>
+  <rect x="225" y="118" width="150" height="68" rx="7" fill="#ecfdf5" stroke="#059669" stroke-width="1.6"/>
+  <text x="300" y="140" text-anchor="middle" fill="#065f46" font-size="11" font-weight="700">Before LLM</text>
+  <text x="240" y="158" fill="#047857" font-size="8.5">cron/background injection</text>
+  <text x="240" y="171" fill="#047857" font-size="8.5">compact + memory + prompt</text>
+  <line x1="375" y1="152" x2="417" y2="152" stroke="#475569" stroke-width="1.5" marker-end="url(#arrow)"/>
+  <rect x="420" y="118" width="110" height="68" rx="7" fill="#fff" stroke="#2563eb" stroke-width="1.4"/>
+  <text x="475" y="146" text-anchor="middle" fill="#1e3a5f" font-size="12" font-weight="700">LLM</text>
+  <text x="475" y="164" text-anchor="middle" fill="#64748b" font-size="8.5">stop_reason=tool_use?</text>
+  <line x1="530" y1="152" x2="572" y2="152" stroke="#475569" stroke-width="1.5" marker-end="url(#arrow)"/>
+  <rect x="575" y="118" width="150" height="68" rx="7" fill="#fff7ed" stroke="#ea580c" stroke-width="1.6"/>
+  <text x="650" y="140" text-anchor="middle" fill="#9a3412" font-size="11" font-weight="700">Before Tools</text>
+  <text x="590" y="158" fill="#c2410c" font-size="8.5">PreToolUse hooks</text>
+  <text x="590" y="171" fill="#c2410c" font-size="8.5">permission pipeline</text>
+  <line x1="725" y1="152" x2="767" y2="152" stroke="#475569" stroke-width="1.5" marker-end="url(#arrow)"/>
+  <rect x="770" y="118" width="80" height="68" rx="7" fill="#fff" stroke="#2563eb" stroke-width="1.4"/>
+  <text x="810" y="147" text-anchor="middle" fill="#1e3a5f" font-size="10" font-weight="700">handlers</text>
+  <text x="810" y="164" text-anchor="middle" fill="#64748b" font-size="8">builtin + MCP</text>
+  <path d="M 810 186 L 810 244 L 125 244 L 125 176" fill="none" stroke="#475569" stroke-width="1.4" stroke-dasharray="6,4" marker-end="url(#arrow)"/>
+  <text x="460" y="263" text-anchor="middle" fill="#64748b" font-size="9">tool_result / task_notification → messages[] → next turn</text>
+  <rect x="40" y="318" width="190" height="104" rx="8" fill="#ecfdf5" stroke="#059669" stroke-width="1.4"/>
+  <text x="135" y="341" text-anchor="middle" fill="#065f46" font-size="11" font-weight="700">Context &amp; Knowledge</text>
+  <text x="58" y="362" fill="#047857" font-size="9">s07 skills + load_skill</text>
+  <text x="58" y="377" fill="#047857" font-size="9">s09 memory selection</text>
+  <text x="58" y="392" fill="#047857" font-size="9">s10 prompt sections</text>
+  <text x="58" y="407" fill="#047857" font-size="9">s08 compact pipeline</text>
+  <path d="M 230 350 L 282 186" fill="none" stroke="#059669" stroke-width="1.3" marker-end="url(#arrow-green)" stroke-dasharray="5,3"/>
+  <rect x="260" y="318" width="190" height="104" rx="8" fill="#fff7ed" stroke="#ea580c" stroke-width="1.4"/>
+  <text x="355" y="341" text-anchor="middle" fill="#9a3412" font-size="11" font-weight="700">Governance</text>
+  <text x="278" y="362" fill="#c2410c" font-size="9">s03 permission</text>
+  <text x="278" y="377" fill="#c2410c" font-size="9">s04 hooks</text>
+  <text x="278" y="392" fill="#c2410c" font-size="9">s11 retry / fallback</text>
+  <text x="278" y="407" fill="#c2410c" font-size="9">Stop hooks</text>
+  <path d="M 450 350 L 592 186" fill="none" stroke="#ea580c" stroke-width="1.3" marker-end="url(#arrow-orange)" stroke-dasharray="5,3"/>
+  <rect x="480" y="318" width="190" height="104" rx="8" fill="#f5f3ff" stroke="#7c3aed" stroke-width="1.4"/>
+  <text x="575" y="341" text-anchor="middle" fill="#5b21b6" font-size="11" font-weight="700">Durable Work</text>
+  <text x="498" y="362" fill="#6d28d9" font-size="9">s05 todo_write</text>
+  <text x="498" y="377" fill="#6d28d9" font-size="9">s12 task graph</text>
+  <text x="498" y="392" fill="#6d28d9" font-size="9">s13 background</text>
+  <text x="498" y="407" fill="#6d28d9" font-size="9">s14 cron scheduler</text>
+  <path d="M 575 318 L 575 188" fill="none" stroke="#7c3aed" stroke-width="1.3" marker-end="url(#arrow-purple)" stroke-dasharray="5,3"/>
+  <rect x="700" y="318" width="180" height="104" rx="8" fill="#f0fdfa" stroke="#0d9488" stroke-width="1.4"/>
+  <text x="790" y="341" text-anchor="middle" fill="#0f766e" font-size="11" font-weight="700">Teams &amp; Plugins</text>
+  <text x="718" y="362" fill="#0f766e" font-size="9">s06 subagent</text>
+  <text x="718" y="377" fill="#0f766e" font-size="9">s15-s16 team protocols</text>
+  <text x="718" y="392" fill="#0f766e" font-size="9">s17 worktree isolation</text>
+  <text x="718" y="407" fill="#0f766e" font-size="9">s18 MCP tools</text>
+  <path d="M 790 318 L 790 188" fill="none" stroke="#0d9488" stroke-width="1.3" marker-end="url(#arrow-green)" stroke-dasharray="5,3"/>
+  <rect x="70" y="462" width="780" height="112" rx="8" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2"/>
+  <text x="460" y="487" text-anchor="middle" fill="#1e293b" font-size="12" font-weight="700">TOOL POOL: 27 builtins + dynamic mcp__server__tool</text>
+  <text x="95" y="512" fill="#334155" font-size="9">file/shell: bash · read · write · edit · glob</text>
+  <text x="95" y="530" fill="#334155" font-size="9">single-agent: todo_write · task · load_skill · compact</text>
+  <text x="95" y="548" fill="#334155" font-size="9">durable work: task tools · cron tools</text>
+  <text x="510" y="512" fill="#334155" font-size="9">team: spawn_teammate · send_message · typed protocols</text>
+  <text x="510" y="530" fill="#334155" font-size="9">protocol: request_shutdown · request_plan · review_plan</text>
+  <text x="510" y="548" fill="#334155" font-size="9">isolation/plugin: worktree tools · connect_mcp</text>
+  <path d="M 850 518 L 890 518 L 890 152 L 850 152" fill="none" stroke="#475569" stroke-width="1.2" marker-end="url(#arrow)" stroke-dasharray="4,4"/>
+</svg>
--- a/s19_comprehensive/images/system-architecture.ja.svg
+++ b/s19_comprehensive/images/system-architecture.ja.svg
@@ -0,0 +1,85 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 920 620" font-family="'Noto Sans CJK JP', 'Noto Sans CJK SC', 'Droid Sans Fallback', system-ui, -apple-system, sans-serif">
+  <defs>
+    <linearGradient id="header" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#1e3a5f"/>
+      <stop offset="100%" stop-color="#0f766e"/>
+    </linearGradient>
+    <marker id="arrow" viewBox="0 0 10 10" refX="10" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#475569"/>
+    </marker>
+    <marker id="arrow-green" viewBox="0 0 10 10" refX="10" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#059669"/>
+    </marker>
+    <marker id="arrow-purple" viewBox="0 0 10 10" refX="10" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#7c3aed"/>
+    </marker>
+    <marker id="arrow-orange" viewBox="0 0 10 10" refX="10" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#ea580c"/>
+    </marker>
+  </defs>
+  <rect width="920" height="620" rx="8" fill="#fafbfc"/>
+  <rect x="0" y="0" width="920" height="46" rx="8" fill="url(#header)"/>
+  <rect x="0" y="38" width="920" height="8" fill="url(#header)"/>
+  <text x="460" y="29" text-anchor="middle" fill="#fff" font-size="17" font-weight="700">s19 Comprehensive Agent — すべての仕組みを 1 つのループへ</text>
+  <rect x="40" y="76" width="840" height="212" rx="8" fill="#eef2ff" stroke="#2563eb" stroke-width="1.8"/>
+  <text x="460" y="101" text-anchor="middle" fill="#1e3a8a" font-size="13" font-weight="700">Core Agent Loop</text>
+  <rect x="70" y="128" width="110" height="48" rx="7" fill="#fff" stroke="#2563eb" stroke-width="1.4"/>
+  <text x="125" y="157" text-anchor="middle" fill="#1e3a5f" font-size="11" font-weight="700">messages[]</text>
+  <line x1="180" y1="152" x2="222" y2="152" stroke="#475569" stroke-width="1.5" marker-end="url(#arrow)"/>
+  <rect x="225" y="118" width="150" height="68" rx="7" fill="#ecfdf5" stroke="#059669" stroke-width="1.6"/>
+  <text x="300" y="140" text-anchor="middle" fill="#065f46" font-size="11" font-weight="700">LLM 前</text>
+  <text x="240" y="158" fill="#047857" font-size="8.5">cron/background 注入</text>
+  <text x="240" y="171" fill="#047857" font-size="8.5">compact + memory + prompt</text>
+  <line x1="375" y1="152" x2="417" y2="152" stroke="#475569" stroke-width="1.5" marker-end="url(#arrow)"/>
+  <rect x="420" y="118" width="110" height="68" rx="7" fill="#fff" stroke="#2563eb" stroke-width="1.4"/>
+  <text x="475" y="146" text-anchor="middle" fill="#1e3a5f" font-size="12" font-weight="700">LLM</text>
+  <text x="475" y="164" text-anchor="middle" fill="#64748b" font-size="8.5">stop_reason=tool_use?</text>
+  <line x1="530" y1="152" x2="572" y2="152" stroke="#475569" stroke-width="1.5" marker-end="url(#arrow)"/>
+  <rect x="575" y="118" width="150" height="68" rx="7" fill="#fff7ed" stroke="#ea580c" stroke-width="1.6"/>
+  <text x="650" y="140" text-anchor="middle" fill="#9a3412" font-size="11" font-weight="700">Tool 前</text>
+  <text x="590" y="158" fill="#c2410c" font-size="8.5">PreToolUse hooks</text>
+  <text x="590" y="171" fill="#c2410c" font-size="8.5">permission pipeline</text>
+  <line x1="725" y1="152" x2="767" y2="152" stroke="#475569" stroke-width="1.5" marker-end="url(#arrow)"/>
+  <rect x="770" y="118" width="80" height="68" rx="7" fill="#fff" stroke="#2563eb" stroke-width="1.4"/>
+  <text x="810" y="147" text-anchor="middle" fill="#1e3a5f" font-size="10" font-weight="700">handlers</text>
+  <text x="810" y="164" text-anchor="middle" fill="#64748b" font-size="8">builtin + MCP</text>
+  <path d="M 810 186 L 810 244 L 125 244 L 125 176" fill="none" stroke="#475569" stroke-width="1.4" stroke-dasharray="6,4" marker-end="url(#arrow)"/>
+  <text x="460" y="263" text-anchor="middle" fill="#64748b" font-size="9">tool_result / task_notification → messages[] → 次のターン</text>
+  <rect x="40" y="318" width="190" height="104" rx="8" fill="#ecfdf5" stroke="#059669" stroke-width="1.4"/>
+  <text x="135" y="341" text-anchor="middle" fill="#065f46" font-size="11" font-weight="700">Context / Knowledge</text>
+  <text x="58" y="362" fill="#047857" font-size="9">s07 skills + load_skill</text>
+  <text x="58" y="377" fill="#047857" font-size="9">s09 memory selection</text>
+  <text x="58" y="392" fill="#047857" font-size="9">s10 prompt sections</text>
+  <text x="58" y="407" fill="#047857" font-size="9">s08 compact pipeline</text>
+  <path d="M 230 350 L 282 186" fill="none" stroke="#059669" stroke-width="1.3" marker-end="url(#arrow-green)" stroke-dasharray="5,3"/>
+  <rect x="260" y="318" width="190" height="104" rx="8" fill="#fff7ed" stroke="#ea580c" stroke-width="1.4"/>
+  <text x="355" y="341" text-anchor="middle" fill="#9a3412" font-size="11" font-weight="700">Governance</text>
+  <text x="278" y="362" fill="#c2410c" font-size="9">s03 permission</text>
+  <text x="278" y="377" fill="#c2410c" font-size="9">s04 hooks</text>
+  <text x="278" y="392" fill="#c2410c" font-size="9">s11 retry / fallback</text>
+  <text x="278" y="407" fill="#c2410c" font-size="9">Stop hooks</text>
+  <path d="M 450 350 L 592 186" fill="none" stroke="#ea580c" stroke-width="1.3" marker-end="url(#arrow-orange)" stroke-dasharray="5,3"/>
+  <rect x="480" y="318" width="190" height="104" rx="8" fill="#f5f3ff" stroke="#7c3aed" stroke-width="1.4"/>
+  <text x="575" y="341" text-anchor="middle" fill="#5b21b6" font-size="11" font-weight="700">Durable Work</text>
+  <text x="498" y="362" fill="#6d28d9" font-size="9">s05 todo_write</text>
+  <text x="498" y="377" fill="#6d28d9" font-size="9">s12 task graph</text>
+  <text x="498" y="392" fill="#6d28d9" font-size="9">s13 background</text>
+  <text x="498" y="407" fill="#6d28d9" font-size="9">s14 cron scheduler</text>
+  <path d="M 575 318 L 575 188" fill="none" stroke="#7c3aed" stroke-width="1.3" marker-end="url(#arrow-purple)" stroke-dasharray="5,3"/>
+  <rect x="700" y="318" width="180" height="104" rx="8" fill="#f0fdfa" stroke="#0d9488" stroke-width="1.4"/>
+  <text x="790" y="341" text-anchor="middle" fill="#0f766e" font-size="11" font-weight="700">Teams / Plugins</text>
+  <text x="718" y="362" fill="#0f766e" font-size="9">s06 subagent</text>
+  <text x="718" y="377" fill="#0f766e" font-size="9">s15-s16 team protocols</text>
+  <text x="718" y="392" fill="#0f766e" font-size="9">s17 worktree isolation</text>
+  <text x="718" y="407" fill="#0f766e" font-size="9">s18 MCP tools</text>
+  <path d="M 790 318 L 790 188" fill="none" stroke="#0d9488" stroke-width="1.3" marker-end="url(#arrow-green)" stroke-dasharray="5,3"/>
+  <rect x="70" y="462" width="780" height="112" rx="8" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2"/>
+  <text x="460" y="487" text-anchor="middle" fill="#1e293b" font-size="12" font-weight="700">TOOL POOL: 27 builtins + dynamic mcp__server__tool</text>
+  <text x="95" y="512" fill="#334155" font-size="9">file/shell: bash · read · write · edit · glob</text>
+  <text x="95" y="530" fill="#334155" font-size="9">single-agent: todo_write · task · load_skill · compact</text>
+  <text x="95" y="548" fill="#334155" font-size="9">durable work: task tools · cron tools</text>
+  <text x="510" y="512" fill="#334155" font-size="9">team: spawn_teammate · send_message · typed protocols</text>
+  <text x="510" y="530" fill="#334155" font-size="9">protocol: request_shutdown · request_plan · review_plan</text>
+  <text x="510" y="548" fill="#334155" font-size="9">isolation/plugin: worktree tools · connect_mcp</text>
+  <path d="M 850 518 L 890 518 L 890 152 L 850 152" fill="none" stroke="#475569" stroke-width="1.2" marker-end="url(#arrow)" stroke-dasharray="4,4"/>
+</svg>
--- a/s19_comprehensive/images/system-architecture.svg
+++ b/s19_comprehensive/images/system-architecture.svg
@@ -0,0 +1,105 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 920 620" font-family="'Noto Sans CJK SC', 'Droid Sans Fallback', system-ui, -apple-system, sans-serif">
+  <defs>
+    <linearGradient id="header" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#1e3a5f"/>
+      <stop offset="100%" stop-color="#0f766e"/>
+    </linearGradient>
+    <marker id="arrow" viewBox="0 0 10 10" refX="10" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#475569"/>
+    </marker>
+    <marker id="arrow-green" viewBox="0 0 10 10" refX="10" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#059669"/>
+    </marker>
+    <marker id="arrow-purple" viewBox="0 0 10 10" refX="10" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#7c3aed"/>
+    </marker>
+    <marker id="arrow-orange" viewBox="0 0 10 10" refX="10" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#ea580c"/>
+    </marker>
+  </defs>
+
+  <rect width="920" height="620" rx="8" fill="#fafbfc"/>
+  <rect x="0" y="0" width="920" height="46" rx="8" fill="url(#header)"/>
+  <rect x="0" y="38" width="920" height="8" fill="url(#header)"/>
+  <text x="460" y="29" text-anchor="middle" fill="#fff" font-size="17" font-weight="700">s19 Comprehensive Agent — 全部机制挂在同一个循环上</text>
+
+  <!-- Main loop band -->
+  <rect x="40" y="76" width="840" height="212" rx="8" fill="#eef2ff" stroke="#2563eb" stroke-width="1.8"/>
+  <text x="460" y="101" text-anchor="middle" fill="#1e3a8a" font-size="13" font-weight="700">核心 Agent Loop</text>
+
+  <rect x="70" y="128" width="110" height="48" rx="7" fill="#fff" stroke="#2563eb" stroke-width="1.4"/>
+  <text x="125" y="157" text-anchor="middle" fill="#1e3a5f" font-size="11" font-weight="700">messages[]</text>
+
+  <line x1="180" y1="152" x2="222" y2="152" stroke="#475569" stroke-width="1.5" marker-end="url(#arrow)"/>
+
+  <rect x="225" y="118" width="150" height="68" rx="7" fill="#ecfdf5" stroke="#059669" stroke-width="1.6"/>
+  <text x="300" y="140" text-anchor="middle" fill="#065f46" font-size="11" font-weight="700">LLM 前处理</text>
+  <text x="240" y="158" fill="#047857" font-size="8.5">cron / background 注入</text>
+  <text x="240" y="171" fill="#047857" font-size="8.5">compact + memory + prompt</text>
+
+  <line x1="375" y1="152" x2="417" y2="152" stroke="#475569" stroke-width="1.5" marker-end="url(#arrow)"/>
+
+  <rect x="420" y="118" width="110" height="68" rx="7" fill="#fff" stroke="#2563eb" stroke-width="1.4"/>
+  <text x="475" y="146" text-anchor="middle" fill="#1e3a5f" font-size="12" font-weight="700">LLM</text>
+  <text x="475" y="164" text-anchor="middle" fill="#64748b" font-size="8.5">stop_reason=tool_use?</text>
+
+  <line x1="530" y1="152" x2="572" y2="152" stroke="#475569" stroke-width="1.5" marker-end="url(#arrow)"/>
+
+  <rect x="575" y="118" width="150" height="68" rx="7" fill="#fff7ed" stroke="#ea580c" stroke-width="1.6"/>
+  <text x="650" y="140" text-anchor="middle" fill="#9a3412" font-size="11" font-weight="700">工具前闸门</text>
+  <text x="590" y="158" fill="#c2410c" font-size="8.5">PreToolUse hooks</text>
+  <text x="590" y="171" fill="#c2410c" font-size="8.5">permission pipeline</text>
+
+  <line x1="725" y1="152" x2="767" y2="152" stroke="#475569" stroke-width="1.5" marker-end="url(#arrow)"/>
+
+  <rect x="770" y="118" width="80" height="68" rx="7" fill="#fff" stroke="#2563eb" stroke-width="1.4"/>
+  <text x="810" y="147" text-anchor="middle" fill="#1e3a5f" font-size="10" font-weight="700">handlers</text>
+  <text x="810" y="164" text-anchor="middle" fill="#64748b" font-size="8">builtin + MCP</text>
+
+  <path d="M 810 186 L 810 244 L 125 244 L 125 176" fill="none" stroke="#475569" stroke-width="1.4" stroke-dasharray="6,4" marker-end="url(#arrow)"/>
+  <text x="460" y="263" text-anchor="middle" fill="#64748b" font-size="9">tool_result / task_notification → messages[] → 下一轮</text>
+
+  <!-- Top sidecars -->
+  <rect x="40" y="318" width="190" height="104" rx="8" fill="#ecfdf5" stroke="#059669" stroke-width="1.4"/>
+  <text x="135" y="341" text-anchor="middle" fill="#065f46" font-size="11" font-weight="700">上下文与知识</text>
+  <text x="58" y="362" fill="#047857" font-size="9">s07 skills catalog + load_skill</text>
+  <text x="58" y="377" fill="#047857" font-size="9">s09 memory selection</text>
+  <text x="58" y="392" fill="#047857" font-size="9">s10 prompt sections</text>
+  <text x="58" y="407" fill="#047857" font-size="9">s08 compact pipeline</text>
+  <path d="M 230 350 L 282 186" fill="none" stroke="#059669" stroke-width="1.3" marker-end="url(#arrow-green)" stroke-dasharray="5,3"/>
+
+  <rect x="260" y="318" width="190" height="104" rx="8" fill="#fff7ed" stroke="#ea580c" stroke-width="1.4"/>
+  <text x="355" y="341" text-anchor="middle" fill="#9a3412" font-size="11" font-weight="700">治理与扩展点</text>
+  <text x="278" y="362" fill="#c2410c" font-size="9">s03 permission</text>
+  <text x="278" y="377" fill="#c2410c" font-size="9">s04 hooks</text>
+  <text x="278" y="392" fill="#c2410c" font-size="9">s11 retry / fallback</text>
+  <text x="278" y="407" fill="#c2410c" font-size="9">Stop hooks</text>
+  <path d="M 450 350 L 592 186" fill="none" stroke="#ea580c" stroke-width="1.3" marker-end="url(#arrow-orange)" stroke-dasharray="5,3"/>
+
+  <rect x="480" y="318" width="190" height="104" rx="8" fill="#f5f3ff" stroke="#7c3aed" stroke-width="1.4"/>
+  <text x="575" y="341" text-anchor="middle" fill="#5b21b6" font-size="11" font-weight="700">持久工作</text>
+  <text x="498" y="362" fill="#6d28d9" font-size="9">s05 todo_write</text>
+  <text x="498" y="377" fill="#6d28d9" font-size="9">s12 task graph</text>
+  <text x="498" y="392" fill="#6d28d9" font-size="9">s13 background</text>
+  <text x="498" y="407" fill="#6d28d9" font-size="9">s14 cron scheduler</text>
+  <path d="M 575 318 L 575 188" fill="none" stroke="#7c3aed" stroke-width="1.3" marker-end="url(#arrow-purple)" stroke-dasharray="5,3"/>
+
+  <rect x="700" y="318" width="180" height="104" rx="8" fill="#f0fdfa" stroke="#0d9488" stroke-width="1.4"/>
+  <text x="790" y="341" text-anchor="middle" fill="#0f766e" font-size="11" font-weight="700">团队与插件</text>
+  <text x="718" y="362" fill="#0f766e" font-size="9">s06 subagent</text>
+  <text x="718" y="377" fill="#0f766e" font-size="9">s15-s16 team protocols</text>
+  <text x="718" y="392" fill="#0f766e" font-size="9">s17 worktree isolation</text>
+  <text x="718" y="407" fill="#0f766e" font-size="9">s18 MCP tools</text>
+  <path d="M 790 318 L 790 188" fill="none" stroke="#0d9488" stroke-width="1.3" marker-end="url(#arrow-green)" stroke-dasharray="5,3"/>
+
+  <!-- Tool pool -->
+  <rect x="70" y="462" width="780" height="112" rx="8" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2"/>
+  <text x="460" y="487" text-anchor="middle" fill="#1e293b" font-size="12" font-weight="700">TOOL POOL: 27 builtins + dynamic mcp__server__tool</text>
+  <text x="95" y="512" fill="#334155" font-size="9">file/shell: bash · read · write · edit · glob</text>
+  <text x="95" y="530" fill="#334155" font-size="9">single-agent: todo_write · task · load_skill · compact</text>
+  <text x="95" y="548" fill="#334155" font-size="9">durable work: create/list/get/claim/complete_task · schedule/list/cancel_cron</text>
+  <text x="510" y="512" fill="#334155" font-size="9">team: spawn_teammate · send_message · typed protocols</text>
+  <text x="510" y="530" fill="#334155" font-size="9">protocol: request_shutdown · request_plan · review_plan</text>
+  <text x="510" y="548" fill="#334155" font-size="9">isolation/plugin: create/remove/keep_worktree · connect_mcp</text>
+  <path d="M 850 518 L 890 518 L 890 152 L 850 152" fill="none" stroke="#475569" stroke-width="1.2" marker-end="url(#arrow)" stroke-dasharray="4,4"/>
+</svg>