learn-claude-code/web/src/data/generated/docs.json

[
  {
    "version": null,
    "slug": "data-structures",
    "locale": "en",
    "title": "Core Data Structures",
    "kind": "bridge",
    "filename": "data-structures.md",
    "content": "# Core Data Structures\n\n> **Reference** -- Use this when you lose track of where state lives. Each record has one clear job.\n\nThe easiest way to get lost in an agent system is not feature count -- it is losing track of where the state actually lives. This document collects the core records that appear again and again across the mainline and bridge docs so you always have one place to look them up.\n\n## Recommended Reading Together\n\n- [`glossary.md`](./glossary.md) for term meanings\n- [`entity-map.md`](./entity-map.md) for layer boundaries\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) for task vs runtime-slot separation\n- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md) for MCP beyond tools\n\n## Two Principles To Keep In Mind\n\n### Principle 1: separate content state from process-control state\n\n- `messages`, `tool_result`, and memory text are content state\n- `turn_count`, `transition`, and retry flags are process-control state\n\n### Principle 2: separate durable state from runtime-only state\n\n- tasks, memory, and schedules are usually durable\n- runtime slots, permission decisions, and live MCP connections are usually runtime state\n\n## Query And Conversation State\n\n### `Message`\n\nStores conversation and tool round-trip history.\n\n### `NormalizedMessage`\n\nStable message shape ready for the model API.\n\n### `QueryParams`\n\nExternal input used to start one query process.\n\n### `QueryState`\n\nMutable state that changes across turns.\n\n### `TransitionReason`\n\nExplains why the next turn exists.\n\n### `CompactSummary`\n\nCompressed carry-forward summary when old context leaves the hot window.\n\n## Prompt And Input State\n\n### `SystemPromptBlock`\n\nOne stable prompt fragment.\n\n### `PromptParts`\n\nSeparated prompt fragments before final assembly.\n\n### `ReminderMessage`\n\nTemporary one-turn or one-mode injection.\n\n## Tool And Control-Plane State\n\n### `ToolSpec`\n\nWhat the model knows about one tool.\n\n### `ToolDispatchMap`\n\nName-to-handler routing table.\n\n### `ToolUseContext`\n\nShared execution environment visible to tools.\n\n### `ToolResultEnvelope`\n\nNormalized result returned into the main loop.\n\n### `PermissionRule`\n\nPolicy that decides allow / deny / ask.\n\n### `PermissionDecision`\n\nStructured output of the permission gate.\n\n### `HookEvent`\n\nNormalized lifecycle event emitted around the loop.\n\n## Durable Work State\n\n### `TaskRecord`\n\nDurable work-graph node with goal, status, and dependency edges.\n\n### `ScheduleRecord`\n\nRule describing when work should trigger.\n\n### `MemoryEntry`\n\nCross-session fact worth keeping.\n\n## Runtime Execution State\n\n### `RuntimeTaskState`\n\nLive execution-slot record for background or long-running work.\n\n### `Notification`\n\nSmall result bridge that carries runtime outcomes back into the main loop.\n\n### `RecoveryState`\n\nState used to continue coherently after failures.\n\n## Team And Platform State\n\n### `TeamMember`\n\nPersistent teammate identity.\n\n### `MessageEnvelope`\n\nStructured message between teammates.\n\n### `RequestRecord`\n\nDurable record for approvals, shutdowns, handoffs, or other protocol workflows.\n\n### `WorktreeRecord`\n\nRecord for one isolated execution lane.\n\n### `MCPServerConfig`\n\nConfiguration for one external capability provider.\n\n### `CapabilityRoute`\n\nRouting decision for native, plugin, or MCP-backed capability.\n\n## A Useful Quick Map\n\n| Record | Main Job | Usually Lives In |\n|---|---|---|\n| `Message` | conversation history | `messages[]` |\n| `QueryState` | turn-by-turn control | query engine |\n| `ToolUseContext` | tool execution environment | tool control plane |\n| `PermissionDecision` | execution gate outcome | permission layer |\n| `TaskRecord` | durable work goal | task board |\n| `RuntimeTaskState` | live execution slot | runtime manager |\n| `TeamMember` | persistent teammate | team config |\n| `RequestRecord` | protocol state | request tracker |\n| `WorktreeRecord` | isolated execution lane | worktree index |\n| `MCPServerConfig` | external capability config | settings / plugin config |\n\n## Key Takeaway\n\n**High-completion systems become much easier to understand when every important record has one clear job and one clear layer.**\n"
  },
  {
    "version": null,
    "slug": "entity-map",
    "locale": "en",
    "title": "Entity Map",
    "kind": "bridge",
    "filename": "entity-map.md",
    "content": "# Entity Map\n\n> **Reference** -- Use this when concepts start to blur together. It tells you which layer each thing belongs to.\n\nAs you move into the second half of the repo, you will notice that the main source of confusion is often not code. It is the fact that many entities look similar while living on different layers. This map helps you keep them straight.\n\n## How This Map Differs From Other Docs\n\n- this map answers: **which layer does this thing belong to?**\n- [`glossary.md`](./glossary.md) answers: **what does the word mean?**\n- [`data-structures.md`](./data-structures.md) answers: **what does the state shape look like?**\n\n## A Fast Layered Picture\n\n```text\nconversation layer\n  - message\n  - prompt block\n  - reminder\n\naction layer\n  - tool call\n  - tool result\n  - hook event\n\nwork layer\n  - work-graph task\n  - runtime task\n  - protocol request\n\nexecution layer\n  - subagent\n  - teammate\n  - worktree lane\n\nplatform layer\n  - MCP server\n  - memory record\n  - capability router\n```\n\n## The Most Commonly Confused Pairs\n\n### `Message` vs `PromptBlock`\n\n| Entity | What It Is | What It Is Not |\n|---|---|---|\n| `Message` | conversational content in history | not a stable system rule |\n| `PromptBlock` | stable prompt instruction fragment | not one turn's latest event |\n\n### `Todo / Plan` vs `Task`\n\n| Entity | What It Is | What It Is Not |\n|---|---|---|\n| `todo / plan` | temporary session guidance | not a durable work graph |\n| `task` | durable work node | not one turn's local thought |\n\n### `Work-Graph Task` vs `RuntimeTaskState`\n\n| Entity | What It Is | What It Is Not |\n|---|---|---|\n| work-graph task | durable goal and dependency node | not the live executor |\n| runtime task | currently running execution slot | not the durable dependency node |\n\n### `Subagent` vs `Teammate`\n\n| Entity | What It Is | What It Is Not |\n|---|---|---|\n| subagent | one-shot delegated worker | not a long-lived team member |\n| teammate | persistent collaborator with identity and inbox | not a disposable summary tool |\n\n### `ProtocolRequest` vs normal message\n\n| Entity | What It Is | What It Is Not |\n|---|---|---|\n| normal message | free-form communication | not a traceable approval workflow |\n| protocol request | structured request with `request_id` | not casual chat text |\n\n### `Task` vs `Worktree`\n\n| Entity | What It Is | What It Is Not |\n|---|---|---|\n| task | what should be done | not a directory |\n| worktree | where isolated execution happens | not the goal itself |\n\n### `Memory` vs `CLAUDE.md`\n\n| Entity | What It Is | What It Is Not |\n|---|---|---|\n| memory | durable cross-session facts | not the project rule file |\n| `CLAUDE.md` | stable local rule / instruction surface | not user-specific long-term fact storage |\n\n### `MCPServer` vs `MCPTool`\n\n| Entity | What It Is | What It Is Not |\n|---|---|---|\n| MCP server | external capability provider | not one specific tool |\n| MCP tool | one exposed capability | not the whole connection surface |\n\n## Quick \"What / Where\" Table\n\n| Entity | Main Job | Typical Place |\n|---|---|---|\n| `Message` | visible conversation context | `messages[]` |\n| `PromptParts` | input assembly fragments | prompt builder |\n| `PermissionRule` | execution decision rules | settings / session state |\n| `HookEvent` | lifecycle extension point | hook system |\n| `MemoryEntry` | durable fact | memory store |\n| `TaskRecord` | work goal node | task board |\n| `RuntimeTaskState` | live execution slot | runtime manager |\n| `TeamMember` | persistent worker identity | team config |\n| `MessageEnvelope` | structured teammate message | inbox |\n| `RequestRecord` | protocol workflow state | request tracker |\n| `WorktreeRecord` | isolated execution lane | worktree index |\n| `MCPServerConfig` | external capability provider config | plugin / settings |\n\n## Key Takeaway\n\n**The more capable the system becomes, the more important clear entity boundaries become.**\n"
  },
  {
    "version": null,
    "slug": "glossary",
    "locale": "en",
    "title": "Glossary",
    "kind": "bridge",
    "filename": "glossary.md",
    "content": "# Glossary\n\n> **Reference** -- Bookmark this page. Come back whenever you hit an unfamiliar term.\n\nThis glossary collects the terms that matter most to the teaching mainline -- the ones that most often trip up beginners. If you find yourself staring at a word mid-chapter and thinking \"wait, what does that mean again?\", this is the page to return to.\n\n## Recommended Companion Docs\n\n- [`entity-map.md`](./entity-map.md) for layer boundaries\n- [`data-structures.md`](./data-structures.md) for record shapes\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) if you keep mixing up different kinds of \"task\"\n\n## Agent\n\nA model that can reason over input and call tools to complete work. (Think of it as the \"brain\" that decides what to do next.)\n\n## Harness\n\nThe working environment prepared around the model -- everything the model needs but cannot provide for itself:\n\n- tools\n- filesystem\n- permissions\n- prompt assembly\n- memory\n- task runtime\n\n## Agent Loop\n\nThe repeating core cycle that drives every agent session. Each iteration looks like this:\n\n1. send current input to the model\n2. inspect whether it answered or asked for tools\n3. execute tools if needed\n4. write results back\n5. continue or stop\n\n## Message / `messages[]`\n\nThe visible conversation and tool-result history used as working context. (This is the rolling transcript the model sees on every turn.)\n\n## Tool\n\nAn action the model may request, such as reading a file, writing a file, editing content, or running a shell command.\n\n## Tool Schema\n\nThe description shown to the model:\n\n- name\n- purpose\n- input parameters\n- input types\n\n## Dispatch Map\n\nA routing table from tool names to handlers. (Like a phone switchboard: the name comes in, and the map connects it to the right function.)\n\n## Stop Reason\n\nWhy the current model turn ended. Common values:\n\n- `end_turn`\n- `tool_use`\n- `max_tokens`\n\n## Context\n\nThe total information currently visible to the model. (Everything inside the model's \"window\" on a given turn.)\n\n## Compaction\n\nThe process of shrinking active context while preserving the important storyline and next-step information. (Like summarizing meeting notes so you keep the action items but drop the small talk.)\n\n## Subagent\n\nA one-shot delegated worker that runs in a separate context and usually returns a summary. (A temporary helper spun up for one job, then discarded.)\n\n## Permission\n\nThe decision layer that determines whether a requested action may execute.\n\n## Hook\n\nAn extension point that lets the system observe or add side effects around the loop without rewriting the loop itself. (Like event listeners -- the loop fires a signal, and hooks respond.)\n\n## Memory\n\nCross-session information worth keeping because it remains valuable later and is not cheap to re-derive.\n\n## System Prompt\n\nThe stable system-level instruction surface that defines identity, rules, and long-lived constraints.\n\n## Query\n\nThe full multi-turn process used to complete one user request. (One query may span many loop turns before the answer is ready.)\n\n## Transition Reason\n\nThe reason the system continues into another turn.\n\n## Task\n\nA durable work goal node in the work graph. (Unlike a todo item that disappears when the session ends, a task persists.)\n\n## Runtime Task / Runtime Slot\n\nA live execution slot representing something currently running. (The task says \"what should happen\"; the runtime slot says \"it is happening right now.\")\n\n## Teammate\n\nA persistent collaborator inside a multi-agent system. (Unlike a subagent that is fire-and-forget, a teammate sticks around.)\n\n## Protocol Request\n\nA structured request with explicit identity, status, and tracking, usually backed by a `request_id`. (A formal envelope rather than a casual message.)\n\n## Worktree\n\nAn isolated execution directory lane used so parallel work does not collide. (Each lane gets its own copy of the workspace, like separate desks for separate tasks.)\n\n## MCP\n\nModel Context Protocol. In this repo it represents an external capability integration surface, not only a tool list. (The bridge that lets your agent talk to outside services.)\n\n## DAG\n\nDirected Acyclic Graph. A set of nodes connected by one-way edges with no cycles. (If you draw arrows between tasks showing \"A must finish before B\", and no arrow path ever loops back to where it started, you have a DAG.) Used in this repo for task dependency graphs.\n\n## FSM / State Machine\n\nFinite State Machine. A system that is always in exactly one state from a known set, and transitions between states based on defined events. (Think of a traffic light cycling through red, green, and yellow.) The agent loop's turn logic is modeled as a state machine.\n\n## Control Plane\n\nThe layer that decides what should happen next, as opposed to the layer that actually does the work. (Air traffic control versus the airplane.) In this repo, the query engine and tool dispatch act as control planes.\n\n## Tokens\n\nThe atomic units a language model reads and writes. One token is roughly 3/4 of an English word. Context limits and compaction thresholds are measured in tokens.\n"
  },
  {
    "version": null,
    "slug": "s00-architecture-overview",
    "locale": "en",
    "title": "s00: Architecture Overview",
    "kind": "bridge",
    "filename": "s00-architecture-overview.md",
    "content": "# s00: Architecture Overview\n\nWelcome to the map. Before diving into building piece by piece, it helps to see the whole picture from above. This document shows you what the full system contains, why the chapters are ordered this way, and what you will actually learn.\n\n## The Big Picture\n\nThe mainline of this repo is reasonable because it grows the system in four dependency-driven stages:\n\n1. build a real single-agent loop\n2. harden that loop with safety, memory, and recovery\n3. turn temporary session work into durable runtime work\n4. grow the single executor into a multi-agent platform with isolated lanes and external capability routing\n\nThis order follows **mechanism dependencies**, not file order and not product glamour.\n\nIf the learner does not already understand:\n\n`user input -> model -> tools -> write-back -> next turn`\n\nthen permissions, hooks, memory, tasks, teams, worktrees, and MCP all become disconnected vocabulary.\n\n## What This Repo Is Trying To Reconstruct\n\nThis repository is not trying to mirror a production codebase line by line.\n\nIt is trying to reconstruct the parts that determine whether an agent system actually works:\n\n- what the main modules are\n- how those modules cooperate\n- what each module is responsible for\n- where the important state lives\n- how one request flows through the system\n\nThat means the goal is:\n\n**high fidelity to the design backbone, not 1:1 fidelity to every outer implementation detail.**\n\n## Three Tips Before You Start\n\n### Tip 1: Learn the smallest correct version first\n\nFor example, a subagent does not need every advanced capability on day one.\n\nThe smallest correct version already teaches the core lesson:\n\n- the parent defines the subtask\n- the child gets a separate `messages[]`\n- the child returns a summary\n\nOnly after that is stable should you add:\n\n- inherited context\n- separate permissions\n- background runtime\n- worktree isolation\n\n### Tip 2: New terms should be explained before they are used\n\nThis repo uses terms such as:\n\n- state machine\n- dispatch map\n- dependency graph\n- worktree\n- protocol envelope\n- MCP\n\nIf a term is unfamiliar, pause and check the reference docs rather than pushing forward blindly.\n\nRecommended companions:\n\n- [`glossary.md`](./glossary.md)\n- [`entity-map.md`](./entity-map.md)\n- [`data-structures.md`](./data-structures.md)\n- [`teaching-scope.md`](./teaching-scope.md)\n\n### Tip 3: Do not let peripheral complexity pretend to be core mechanism\n\nGood teaching does not try to include everything.\n\nIt explains the important parts completely and keeps low-value complexity out of your way:\n\n- packaging and release flow\n- enterprise integration glue\n- telemetry\n- product-specific compatibility branches\n- file-name / line-number reverse-engineering trivia\n\n## Bridge Docs That Matter\n\nTreat these as cross-chapter maps:\n\n| Doc | What It Clarifies |\n|---|---|\n| [`s00d-chapter-order-rationale.md`](./s00d-chapter-order-rationale.md) (Deep Dive) | why the curriculum order is what it is |\n| [`s00e-reference-module-map.md`](./s00e-reference-module-map.md) (Deep Dive) | how the reference repo's real module clusters map onto the current curriculum |\n| [`s00a-query-control-plane.md`](./s00a-query-control-plane.md) (Deep Dive) | why a high-completion agent needs more than `messages[] + while True` |\n| [`s00b-one-request-lifecycle.md`](./s00b-one-request-lifecycle.md) (Deep Dive) | how one request moves through the full system |\n| [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) (Deep Dive) | why tools become a control plane, not just a function table |\n| [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md) (Deep Dive) | why system prompt is only one input surface |\n| [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) (Deep Dive) | why durable tasks and live runtime slots must split |\n| [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md) (Deep Dive) | why MCP is more than a remote tool list |\n\n## The Four Learning Stages\n\n### Stage 1: Core Single-Agent (`s01-s06`)\n\nGoal: build a single agent that can actually do work.\n\n| Chapter | New Layer |\n|---|---|\n| `s01` | loop and write-back |\n| `s02` | tools and dispatch |\n| `s03` | session planning |\n| `s04` | delegated subtask isolation |\n| `s05` | skill discovery and loading |\n| `s06` | context compaction |\n\n### Stage 2: Hardening (`s07-s11`)\n\nGoal: make the loop safer, more stable, and easier to extend.\n\n| Chapter | New Layer |\n|---|---|\n| `s07` | permission gate |\n| `s08` | hooks and side effects |\n| `s09` | durable memory |\n| `s10` | prompt assembly |\n| `s11` | recovery and continuation |\n\n### Stage 3: Runtime Work (`s12-s14`)\n\nGoal: upgrade session work into durable, background, and scheduled runtime work.\n\n| Chapter | New Layer |\n|---|---|\n| `s12` | persistent task graph |\n| `s13` | runtime execution slots |\n| `s14` | time-based triggers |\n\n### Stage 4: Platform (`s15-s19`)\n\nGoal: grow from one executor into a larger platform.\n\n| Chapter | New Layer |\n|---|---|\n| `s15` | persistent teammates |\n| `s16` | structured team protocols |\n| `s17` | autonomous claiming and resuming |\n| `s18` | isolated execution lanes |\n| `s19` | external capability routing |\n\n## Quick Reference: What Each Chapter Adds\n\n| Chapter | Core Structure | What You Should Be Able To Build |\n|---|---|---|\n| `s01` | `LoopState`, `tool_result` write-back | a minimal working agent loop |\n| `s02` | `ToolSpec`, dispatch map | stable tool routing |\n| `s03` | `TodoItem`, `PlanState` | visible session planning |\n| `s04` | isolated child context | delegated subtasks without polluting the parent |\n| `s05` | `SkillRegistry` | cheap discovery and deep on-demand loading |\n| `s06` | compaction records | long sessions that stay usable |\n| `s07` | permission decisions | execution behind a gate |\n| `s08` | lifecycle events | extension without rewriting the loop |\n| `s09` | memory records | selective long-term memory |\n| `s10` | prompt parts | staged input assembly |\n| `s11` | continuation reasons | recovery branches that stay legible |\n| `s12` | `TaskRecord` | durable work graphs |\n| `s13` | `RuntimeTaskState` | background execution with later write-back |\n| `s14` | `ScheduleRecord` | time-triggered work |\n| `s15` | `TeamMember`, inboxes | persistent teammates |\n| `s16` | protocol envelopes | structured request / response coordination |\n| `s17` | claim policy | self-claim and self-resume |\n| `s18` | `WorktreeRecord` | isolated execution lanes |\n| `s19` | capability routing | unified native + plugin + MCP routing |\n\n## Key Takeaway\n\n**A good chapter order is not a list of features. It is a path where each mechanism grows naturally out of the last one.**\n"
  },
  {
    "version": null,
    "slug": "s00a-query-control-plane",
    "locale": "en",
    "title": "s00a: Query Control Plane",
    "kind": "bridge",
    "filename": "s00a-query-control-plane.md",
    "content": "# s00a: Query Control Plane\n\n> **Deep Dive** -- Best read after completing Stage 1 (s01-s06). It explains why the simple loop needs a coordination layer as the system grows.\n\n### When to Read This\n\nAfter you've built the basic loop and tools, and before you start Stage 2's hardening chapters.\n\n---\n\n> This bridge document answers one foundational question:\n>\n> **Why is `messages[] + while True` not enough for a high-completion agent?**\n\n## Why This Document Exists\n\n`s01` correctly teaches the smallest working loop:\n\n```text\nuser input\n  ->\nmodel response\n  ->\nif tool_use then execute\n  ->\nappend result\n  ->\ncontinue\n```\n\nThat is the right starting point.\n\nBut once the system grows, the harness needs a separate layer that manages the **query process itself**. A \"control plane\" (the part of a system that coordinates behavior rather than performing the work directly) sits above the data path and decides when, why, and how the loop should keep running:\n\n- current turn\n- continuation reason\n- recovery state\n- compaction state\n- budget changes\n- hook-driven continuation\n\nThat layer is the **query control plane**.\n\n## Terms First\n\n### What is a query?\n\nHere, a query is not a database lookup.\n\nIt means:\n\n> the full multi-turn process the system runs in order to finish one user request\n\n### What is a control plane?\n\nA control plane does not perform the business action itself.\n\nIt coordinates:\n\n- when execution continues\n- why it continues\n- what state is patched before the next turn\n\nIf you have worked with networking or infrastructure, the term is familiar -- the control plane decides where traffic goes, while the data plane carries the actual packets. The same idea applies here: the control plane decides whether the loop should keep running and why, while the execution layer does the actual model calls and tool work.\n\n### What is a transition?\n\nA transition explains:\n\n> why the previous turn did not end and why the next turn exists\n\nCommon reasons:\n\n- tool result write-back\n- truncated output recovery\n- retry after compaction\n- retry after transport failure\n\n## The Smallest Useful Mental Model\n\nThink of the query path in three layers:\n\n```text\n1. Input layer\n   - messages\n   - system prompt\n   - user/system context\n\n2. Control layer\n   - query state\n   - turn count\n   - transition reason\n   - recovery / compaction / budget flags\n\n3. Execution layer\n   - model call\n   - tool execution\n   - write-back\n```\n\nThe control plane does not replace the loop.\n\nIt makes the loop capable of handling more than one happy-path branch.\n\n## Why `messages[]` Alone Stops Being Enough\n\nAt demo scale, many learners put everything into `messages[]`.\n\nThat breaks down once the system needs to know:\n\n- whether reactive compaction already ran\n- how many continuation attempts happened\n- whether this turn is a retry or a normal write-back\n- whether a temporary output budget is active\n\nThose are not conversation contents.\n\nThey are **process-control state**.\n\n## Core Structures\n\n### `QueryParams`\n\nExternal input passed into the query engine:\n\n```python\nparams = {\n    \"messages\": [...],\n    \"system_prompt\": \"...\",\n    \"tool_use_context\": {...},\n    \"max_output_tokens_override\": None,\n    \"max_turns\": None,\n}\n```\n\n### `QueryState`\n\nMutable state that changes across turns:\n\n```python\nstate = {\n    \"messages\": [...],\n    \"tool_use_context\": {...},\n    \"turn_count\": 1,\n    \"continuation_count\": 0,\n    \"has_attempted_compact\": False,\n    \"max_output_tokens_override\": None,\n    \"transition\": None,\n}\n```\n\n### `TransitionReason`\n\nAn explicit reason for continuing:\n\n```python\nTRANSITIONS = (\n    \"tool_result_continuation\",\n    \"max_tokens_recovery\",\n    \"compact_retry\",\n    \"transport_retry\",\n)\n```\n\nThis is not ceremony. It makes logs, testing, debugging, and teaching much clearer.\n\n## Minimal Implementation Pattern\n\n### 1. Split entry params from live state\n\n```python\ndef query(params):\n    state = {\n        \"messages\": params[\"messages\"],\n        \"tool_use_context\": params[\"tool_use_context\"],\n        \"turn_count\": 1,\n        \"transition\": None,\n    }\n```\n\n### 2. Let every continue-site patch state explicitly\n\n```python\nstate[\"transition\"] = \"tool_result_continuation\"\nstate[\"turn_count\"] += 1\n```\n\n### 3. Make the next turn enter with a reason\n\nThe next loop iteration should know whether it exists because of:\n\n- normal write-back\n- retry\n- compaction\n- continuation after truncated output\n\n## What This Changes For You\n\nOnce you see the query control plane clearly, later chapters stop feeling like random features.\n\n- `s06` compaction becomes a state patch, not a magic jump\n- `s11` recovery becomes structured continuation, not just `try/except`\n- `s17` autonomy becomes another controlled continuation path, not a separate mystery loop\n\n## Key Takeaway\n\n**A query is not just messages flowing through a loop. It is a controlled process with explicit continuation state.**\n"
  },
  {
    "version": null,
    "slug": "s00b-one-request-lifecycle",
    "locale": "en",
    "title": "s00b: One Request Lifecycle",
    "kind": "bridge",
    "filename": "s00b-one-request-lifecycle.md",
    "content": "# s00b: One Request Lifecycle\n\n> **Deep Dive** -- Best read after Stage 2 (s07-s11) when you want to see how all the pieces connect end-to-end.\n\n### When to Read This\n\nWhen you've learned several subsystems and want to see the full vertical flow of a single request.\n\n---\n\n> This bridge document connects the whole system into one continuous execution chain.\n>\n> It answers:\n>\n> **What really happens after one user message enters the system?**\n\n## Why This Document Exists\n\nWhen you read chapter by chapter, you can understand each mechanism in isolation:\n\n- `s01` loop\n- `s02` tools\n- `s07` permissions\n- `s09` memory\n- `s12-s19` tasks, teams, worktrees, MCP\n\nBut implementation gets difficult when you cannot answer:\n\n- what comes first?\n- when do memory and prompt assembly happen?\n- where do permissions sit relative to tools?\n- when do tasks, runtime slots, teammates, worktrees, and MCP enter?\n\nThis document gives you the vertical flow.\n\n## The Most Important Full Picture\n\n```text\nuser request\n  |\n  v\ninitialize query state\n  |\n  v\nassemble system prompt / messages / reminders\n  |\n  v\ncall model\n  |\n  +-- normal answer --------------------------> finish request\n  |\n  +-- tool_use\n        |\n        v\n    tool router\n        |\n        +-- permission gate\n        +-- hooks\n        +-- native tool / MCP / agent / task / team\n        |\n        v\n    execution result\n        |\n        +-- may update task / runtime / memory / worktree state\n        |\n        v\n    write tool_result back to messages\n        |\n        v\n    patch query state\n        |\n        v\n    continue next turn\n```\n\n## Segment 1: A User Request Becomes Query State\n\nThe system does not treat one user request as one API call.\n\nIt first creates a query state for a process that may span many turns:\n\n```python\nquery_state = {\n    \"messages\": [{\"role\": \"user\", \"content\": user_text}],\n    \"turn_count\": 1,\n    \"transition\": None,\n    \"tool_use_context\": {...},\n}\n```\n\nThe key mental shift:\n\n**a request is a multi-turn runtime process, not a single model response.**\n\nRelated reading:\n\n- [`s01-the-agent-loop.md`](./s01-the-agent-loop.md)\n- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)\n\n## Segment 2: The Real Model Input Is Assembled\n\nThe harness usually does not send raw `messages` directly.\n\nIt assembles:\n\n- system prompt blocks\n- normalized messages\n- memory attachments\n- reminders\n- tool definitions\n\nSo the actual payload is closer to:\n\n```text\nsystem prompt\n+ normalized messages\n+ tools\n+ optional reminders and attachments\n```\n\nRelated chapters:\n\n- `s09`\n- `s10`\n- [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md)\n\n## Segment 3: The Model Produces Either an Answer or an Action Intent\n\nThere are two important output classes.\n\n### Normal answer\n\nThe request may end here.\n\n### Action intent\n\nThis usually means a tool call, for example:\n\n- `read_file(...)`\n- `bash(...)`\n- `task_create(...)`\n- `mcp__server__tool(...)`\n\nThe system is no longer receiving only text.\n\nIt is receiving an instruction that should affect the real world.\n\n## Segment 4: The Tool Control Plane Takes Over\n\nOnce `tool_use` appears, the system enters the tool control plane (the layer that decides how a tool call gets routed, checked, and executed).\n\nIt answers:\n\n1. which tool is this?\n2. where should it route?\n3. should it pass a permission gate?\n4. do hooks observe or modify the action?\n5. what shared runtime context can it access?\n\nMinimal picture:\n\n```text\ntool_use\n  |\n  v\ntool router\n  |\n  +-- native handler\n  +-- MCP client\n  +-- agent / team / task runtime\n```\n\nRelated reading:\n\n- [`s02-tool-use.md`](./s02-tool-use.md)\n- [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)\n\n## Segment 5: Execution May Update More Than Messages\n\nA tool result does not only return text.\n\nExecution may also update:\n\n- task board state\n- runtime task state\n- memory records\n- request records\n- worktree records\n\nThat is why middle and late chapters are not optional side features. They become part of the request lifecycle.\n\n## Segment 6: Results Rejoin the Main Loop\n\nThe crucial step is always the same:\n\n```text\nreal execution result\n  ->\ntool_result or structured write-back\n  ->\nmessages / query state updated\n  ->\nnext turn\n```\n\nIf the result never re-enters the loop, the model cannot reason over reality.\n\n## A Useful Compression\n\nWhen you get lost, compress the whole lifecycle into three layers:\n\n### Query loop\n\nOwns the multi-turn request process.\n\n### Tool control plane\n\nOwns routing, permissions, hooks, and execution context.\n\n### Platform state\n\nOwns durable records such as tasks, runtime slots, teammates, worktrees, and external capability configuration.\n\n## Key Takeaway\n\n**A user request enters as query state, moves through assembled input, becomes action intent, crosses the tool control plane, touches platform state, and then returns to the loop as new visible context.**\n"
  },
  {
    "version": null,
    "slug": "s00c-query-transition-model",
    "locale": "en",
    "title": "s00c: Query Transition Model",
    "kind": "bridge",
    "filename": "s00c-query-transition-model.md",
    "content": "# s00c: Query Transition Model\n\n> **Deep Dive** -- Best read alongside s11 (Error Recovery). It deepens the transition model introduced in s00a.\n\n### When to Read This\n\nWhen you're working on error recovery and want to understand why each continuation needs an explicit reason.\n\n---\n\n> This bridge note answers one narrow but important question:\n>\n> **Why does a high-completion agent need to know _why_ a query continues into the next turn, instead of treating every `continue` as the same thing?**\n\n## Why This Note Exists\n\nThe mainline already teaches:\n\n- `s01`: the smallest loop\n- `s06`: compaction and context control\n- `s11`: error recovery\n\nThat sequence is correct.\n\nThe problem is what you often carry in your head after reading those chapters separately:\n\n> \"The loop continues because it continues.\"\n\nThat is enough for a toy demo, but it breaks down quickly in a larger system.\n\nA query can continue for very different reasons:\n\n- a tool just finished and the model needs the result\n- the output hit a token limit and the model should continue\n- compaction changed the active context and the system should retry\n- the transport layer failed and backoff says \"try again\"\n- a stop hook said the turn should not fully end yet\n- a budget policy still allows the system to keep going\n\nIf all of those collapse into one vague `continue`, three things get worse fast:\n\n- logs stop being readable\n- tests stop being precise\n- the teaching mental model becomes blurry\n\n## Terms First\n\n### What is a transition\n\nHere, a transition means:\n\n> the reason the previous turn became the next turn\n\nIt is not the message content itself. It is the control-flow cause.\n\n### What is a continuation\n\nA continuation means:\n\n> this query is still alive and should keep advancing\n\nBut continuation is not one thing. It is a family of reasons.\n\n### What is a query boundary\n\nA query boundary is the edge between one turn and the next.\n\nWhenever the system crosses that boundary, it should know:\n\n- why it is crossing\n- what state was changed before the crossing\n- how the next turn should interpret that change\n\n## The Minimum Mental Model\n\nDo not picture a query as a single straight line.\n\nA better mental model is:\n\n```text\none query\n  = a chain of state transitions\n    with explicit continuation reasons\n```\n\nFor example:\n\n```text\nuser input\n  ->\nmodel emits tool_use\n  ->\ntool finishes\n  ->\ntool_result_continuation\n  ->\nmodel output is truncated\n  ->\nmax_tokens_recovery\n  ->\ncompaction happens\n  ->\ncompact_retry\n  ->\nfinal completion\n```\n\nThat is why the real lesson is not:\n\n> \"the loop keeps spinning\"\n\nThe real lesson is:\n\n> \"the system is advancing through typed transition reasons\"\n\n## Core Records\n\n### 1. `transition` inside query state\n\nEven a teaching implementation should carry an explicit transition field:\n\n```python\nstate = {\n    \"messages\": [...],\n    \"turn_count\": 3,\n    \"continuation_count\": 1,\n    \"has_attempted_compact\": False,\n    \"transition\": None,\n}\n```\n\nThis field is not decoration.\n\nIt tells you:\n\n- why this turn exists\n- how the log should explain it\n- what path a test should assert\n\n### 2. `TransitionReason`\n\nA minimal teaching set can look like this:\n\n```python\nTRANSITIONS = (\n    \"tool_result_continuation\",\n    \"max_tokens_recovery\",\n    \"compact_retry\",\n    \"transport_retry\",\n    \"stop_hook_continuation\",\n    \"budget_continuation\",\n)\n```\n\nThese reasons are not equivalent:\n\n- `tool_result_continuation`\n  is normal loop progress\n- `max_tokens_recovery`\n  is continuation after truncated output\n- `compact_retry`\n  is continuation after context reshaping\n- `transport_retry`\n  is continuation after infrastructure failure\n- `stop_hook_continuation`\n  is continuation forced by external control logic\n- `budget_continuation`\n  is continuation allowed by policy and remaining budget\n\n### 3. Continuation budget\n\nHigh-completion systems do not just continue. They limit continuation.\n\nTypical fields look like:\n\n```python\nstate = {\n    \"max_output_tokens_recovery_count\": 2,\n    \"has_attempted_reactive_compact\": True,\n}\n```\n\nThe principle is:\n\n> continuation is a controlled resource, not an infinite escape hatch\n\n## Minimum Implementation Steps\n\n### Step 1: make every continue site explicit\n\nMany beginner loops still look like this:\n\n```python\ncontinue\n```\n\nMove one step forward:\n\n```python\nstate[\"transition\"] = \"tool_result_continuation\"\ncontinue\n```\n\n### Step 2: pair each continuation with its state patch\n\n```python\nif response.stop_reason == \"tool_use\":\n    state[\"messages\"] = append_tool_results(...)\n    state[\"turn_count\"] += 1\n    state[\"transition\"] = \"tool_result_continuation\"\n    continue\n\nif response.stop_reason == \"max_tokens\":\n    state[\"messages\"].append({\n        \"role\": \"user\",\n        \"content\": CONTINUE_MESSAGE,\n    })\n    state[\"max_output_tokens_recovery_count\"] += 1\n    state[\"transition\"] = \"max_tokens_recovery\"\n    continue\n```\n\nThe important part is not \"one more line of code.\"\n\nThe important part is:\n\n> before every continuation, the system knows both the reason and the state mutation\n\n### Step 3: separate normal progress from recovery\n\n```python\nif should_retry_transport(error):\n    time.sleep(backoff(...))\n    state[\"transition\"] = \"transport_retry\"\n    continue\n\nif should_recompact(error):\n    state[\"messages\"] = compact_messages(state[\"messages\"])\n    state[\"transition\"] = \"compact_retry\"\n    continue\n```\n\nOnce you do this, \"continue\" stops being a vague action and becomes a typed control transition.\n\n## What to Test\n\nYour teaching repo should make these assertions straightforward:\n\n- a tool result writes `tool_result_continuation`\n- a truncated model output writes `max_tokens_recovery`\n- compaction retry does not silently reuse the old reason\n- transport retry increments retry state and does not look like a normal turn\n\nIf those paths are not easy to test, the model is probably still too implicit.\n\n## What Not to Over-Teach\n\nYou do not need to bury yourself in vendor-specific transport details or every corner-case enum.\n\nFor a teaching repo, the core lesson is narrower:\n\n> one query is a sequence of explicit transitions, and each transition should carry a reason, a state patch, and a budget rule\n\nThat is the part you actually need if you want to rebuild a high-completion agent from zero.\n\n## Key Takeaway\n\n**Every continuation needs a typed reason. Without one, logs blur, tests weaken, and the mental model collapses into \"the loop keeps spinning.\"**\n"
  },
  {
    "version": null,
    "slug": "s00d-chapter-order-rationale",
    "locale": "en",
    "title": "s00d: Chapter Order Rationale",
    "kind": "bridge",
    "filename": "s00d-chapter-order-rationale.md",
    "content": "# s00d: Chapter Order Rationale\n\n> **Deep Dive** -- Read this after completing Stage 1 (s01-s06) or whenever you wonder \"why is the course ordered this way?\"\n\nThis note is not about one mechanism. It answers a more basic teaching question: why does this curriculum teach the system in the current order instead of following source-file order, feature hype, or raw implementation complexity?\n\n## Conclusion First\n\nThe current `s01 -> s19` order is structurally sound.\n\nIts strength is not just breadth. Its strength is that it grows the system in the same order you should understand it:\n\n1. Build the smallest working agent loop.\n2. Add the control-plane and hardening layers around that loop.\n3. Upgrade session planning into durable work and runtime state.\n4. Only then expand into persistent teams, isolated execution lanes, and external capability buses.\n\nThat is the right teaching order because it follows:\n\n**dependency order between mechanisms**\n\nnot file order or product packaging order.\n\n## The Four Dependency Lines\n\nThis curriculum is really organized by four dependency lines:\n\n1. `core loop dependency`\n2. `control-plane dependency`\n3. `work-state dependency`\n4. `platform-boundary dependency`\n\nIn plain English:\n\n```text\nfirst make the agent run\n  -> then make it run safely\n  -> then make it run durably\n  -> then make it run as a platform\n```\n\n## The Real Shape of the Sequence\n\n```text\ns01-s06\n  build one working single-agent system\n\ns07-s11\n  harden and control that system\n\ns12-s14\n  turn temporary planning into durable work + runtime\n\ns15-s19\n  expand into teammates, protocols, autonomy, isolated lanes, and external capability\n```\n\nAfter each stage, you should be able to say:\n\n- after `s06`: \"I can build one real single-agent harness\"\n- after `s11`: \"I can make that harness safer, steadier, and easier to extend\"\n- after `s14`: \"I can manage durable work, background execution, and time-triggered starts\"\n- after `s19`: \"I understand the platform boundary of a high-completion agent system\"\n\n## Why The Early Chapters Must Stay In Their Current Order\n\n### `s01` must stay first\n\nBecause it establishes:\n\n- the minimal entry point\n- the turn-by-turn loop\n- why tool results must flow back into the next model call\n\nWithout this, everything later becomes disconnected feature talk.\n\n### `s02` must immediately follow `s01`\n\nBecause an agent that cannot route intent into tools is still only talking, not acting.\n\n`s02` is where learners first see the harness become real:\n\n- model emits `tool_use`\n- the system dispatches to a handler\n- the tool executes\n- `tool_result` flows back into the loop\n\n### `s03` should stay before `s04`\n\nThis is an important guardrail.\n\nYou should first understand:\n\n- how the current agent organizes its own work\n\nbefore learning:\n\n- when to delegate work into a separate sub-context\n\nIf `s04` comes too early, subagents become an escape hatch instead of a clear isolation mechanism.\n\n### `s05` should stay before `s06`\n\nThese two chapters solve two halves of the same problem:\n\n- `s05`: prevent unnecessary knowledge from entering the context\n- `s06`: manage the context that still must remain active\n\nThat order matters. A good system first avoids bloat, then compacts what is still necessary.\n\n## Why `s07-s11` Form One Hardening Block\n\nThese chapters all answer the same larger question:\n\n**the loop already works, so how does it become stable, safe, and legible as a real system?**\n\n### `s07` should stay before `s08`\n\nPermission comes first because the system must first answer:\n\n- may this action happen at all\n- should it be denied\n- should it ask the user first\n\nOnly after that should you teach hooks, which answer:\n\n- what extra behavior attaches around the loop\n\nSo the correct teaching order is:\n\n**gate first, extend second**\n\n### `s09` should stay before `s10`\n\nThis is another very important ordering decision.\n\n`s09` teaches:\n\n- what durable information exists\n- which facts deserve long-term storage\n\n`s10` teaches:\n\n- how multiple information sources are assembled into model input\n\nThat means:\n\n- memory defines one content source\n- prompt assembly explains how all content sources are combined\n\nIf you reverse them, prompt construction starts to feel arbitrary and mysterious.\n\n### `s11` is the right closing chapter for this block\n\nError recovery is not an isolated feature.\n\nIt is where the system finally needs to explain:\n\n- why it is continuing\n- why it is retrying\n- why it is stopping\n\nThat only becomes legible after the input path, tool path, state path, and control path already exist.\n\n## Why `s12-s14` Must Stay Goal -> Runtime -> Schedule\n\nThis is the easiest part of the curriculum to teach badly if the order is wrong.\n\n### `s12` must stay before `s13`\n\n`s12` teaches:\n\n- what work exists\n- dependency relations between work nodes\n- when downstream work unlocks\n\n`s13` teaches:\n\n- what live execution is currently running\n- where background results go\n- how runtime state writes back\n\nThat is the crucial distinction:\n\n- `task` is the durable work goal\n- `runtime task` is the live execution slot\n\nIf `s13` comes first, you will almost certainly collapse those two into one concept.\n\n### `s14` must stay after `s13`\n\nCron does not add another kind of task.\n\nIt adds a new start condition:\n\n**time becomes one more way to launch work into the runtime**\n\nSo the right order is:\n\n`durable task graph -> runtime slot -> schedule trigger`\n\n## Why `s15-s19` Should Stay Team -> Protocol -> Autonomy -> Worktree -> Capability Bus\n\n### `s15` defines who persists in the system\n\nBefore protocols or autonomy make sense, the system needs durable actors:\n\n- who teammates are\n- what identity they carry\n- how they persist across work\n\n### `s16` then defines how those actors coordinate\n\nProtocols should not come before actors.\n\nProtocols exist to structure:\n\n- who requests\n- who approves\n- who responds\n- how requests remain traceable\n\n### `s17` only makes sense after both\n\nAutonomy is easy to teach vaguely.\n\nBut in a real system it only becomes clear after:\n\n- persistent teammates exist\n- structured coordination already exists\n\nOtherwise \"autonomous claiming\" sounds like magic instead of the bounded mechanism it really is.\n\n### `s18` should stay before `s19`\n\nWorktree isolation is a local execution-boundary problem:\n\n- where parallel work actually runs\n- how one work lane stays isolated from another\n\nThat should become clear before moving outward into:\n\n- plugins\n- MCP servers\n- external capability routing\n\nOtherwise you risk over-focusing on external capability and under-learning the local platform boundary.\n\n### `s19` is correctly last\n\nIt is the outer platform boundary.\n\nIt only becomes clean once you already understand:\n\n- local actors\n- local work lanes\n- local durable work\n- local runtime execution\n- then external capability providers\n\n## Five Reorders That Would Make The Course Worse\n\n1. Moving `s04` before `s03`\n   This teaches delegation before local planning.\n\n2. Moving `s10` before `s09`\n   This teaches prompt assembly before the learner understands one of its core inputs.\n\n3. Moving `s13` before `s12`\n   This collapses durable goals and live runtime slots into one confused idea.\n\n4. Moving `s17` before `s15` or `s16`\n   This turns autonomy into vague polling magic.\n\n5. Moving `s19` before `s18`\n   This makes the external platform look more important than the local execution boundary.\n\n## A Good Maintainer Check Before Reordering\n\nBefore moving chapters around, ask:\n\n1. Does the learner already understand the prerequisite concept?\n2. Will this reorder blur two concepts that should stay separate?\n3. Is this chapter mainly about goals, runtime state, actors, or capability boundaries?\n4. If I move it earlier, will the reader still be able to build the minimal correct version?\n5. Am I optimizing for understanding, or merely copying source-file order?\n\nIf the honest answer to the last question is \"source-file order\", the reorder is probably a mistake.\n\n## Key Takeaway\n\n**A good chapter order is not just a list of mechanisms. It is a sequence where each chapter feels like the next natural layer grown from the previous one.**\n"
  },
  {
    "version": null,
    "slug": "s00e-reference-module-map",
    "locale": "en",
    "title": "s00e: Reference Module Map",
    "kind": "bridge",
    "filename": "s00e-reference-module-map.md",
    "content": "# s00e: Reference Module Map\n\n> **Deep Dive** -- Read this when you want to verify how the teaching chapters map to the real production codebase.\n\nThis is a calibration note for maintainers and serious learners. It does not turn the reverse-engineered source into required reading. Instead, it answers one narrow but important question: if you compare the high-signal module clusters in the reference repo with this teaching repo, is the current chapter order actually rational?\n\n## Verdict First\n\nYes.\n\nThe current `s01 -> s19` order is broadly correct, and it is closer to the real design backbone than any naive \"follow the source tree\" order would be.\n\nThe reason is simple:\n\n- the reference repo contains many surface-level directories\n- but the real design weight is concentrated in a smaller set of control, state, task, team, worktree, and capability modules\n- those modules line up with the current four-stage teaching path\n\nSo the right move is **not** to flatten the teaching repo into source-tree order.\n\nThe right move is:\n\n- keep the current dependency-driven order\n- make the mapping to the reference repo explicit\n- keep removing low-value product detail from the mainline\n\n## How This Comparison Was Done\n\nThe comparison was based on the reference repo's higher-signal clusters, especially modules around:\n\n- `Tool.ts`\n- `state/AppStateStore.ts`\n- `coordinator/coordinatorMode.ts`\n- `memdir/*`\n- `services/SessionMemory/*`\n- `services/toolUseSummary/*`\n- `constants/prompts.ts`\n- `tasks/*`\n- `tools/TodoWriteTool/*`\n- `tools/AgentTool/*`\n- `tools/ScheduleCronTool/*`\n- `tools/EnterWorktreeTool/*`\n- `tools/ExitWorktreeTool/*`\n- `tools/MCPTool/*`\n- `services/mcp/*`\n- `plugins/*`\n- `hooks/toolPermission/*`\n\nThis is enough to judge the backbone without dragging you through every product-facing command, compatibility branch, or UI detail.\n\n## The Real Mapping\n\n| Reference repo cluster | Typical examples | Teaching chapter(s) | Why this placement is right |\n|---|---|---|---|\n| Query loop + control state | `Tool.ts`, `AppStateStore.ts`, query/coordinator state | `s00`, `s00a`, `s00b`, `s01`, `s11` | The real system is not just `messages[] + while True`. The teaching repo is right to start with the tiny loop first, then add the control plane later. |\n| Tool routing and execution plane | `Tool.ts`, native tools, tool context, execution helpers | `s02`, `s02a`, `s02b` | The source clearly treats tools as a shared execution surface, not a toy dispatch table. The teaching split is correct. |\n| Session planning | `TodoWriteTool` | `s03` | Session planning is a small but central layer. It belongs early, before durable tasks. |\n| One-shot delegation | `AgentTool` in its simplest form | `s04` | The reference repo's agent spawning machinery is large, but the teaching repo is right to teach the smallest clean subagent first: fresh context, bounded task, summary return. |\n| Skill discovery and loading | `DiscoverSkillsTool`, `skills/*`, prompt sections | `s05` | Skills are not random extras. They are a selective knowledge-loading layer, so they belong before prompt and context pressure become severe. |\n| Context pressure and collapse | `services/toolUseSummary/*`, `services/contextCollapse/*`, compact logic | `s06` | The reference repo clearly has explicit compaction machinery. Teaching this before later platform features is correct. |\n| Permission gate | `types/permissions.ts`, `hooks/toolPermission/*`, approval handlers | `s07` | Execution safety is a distinct gate, not \"just another hook\". Keeping it before hooks is the right teaching choice. |\n| Hooks and side effects | `types/hooks.ts`, hook runners, lifecycle integrations | `s08` | The source separates extension points from the primary gate. Teaching them after permissions preserves that boundary. |\n| Durable memory selection | `memdir/*`, `services/SessionMemory/*`, extract/select memory helpers | `s09` | The source makes memory a selective cross-session layer, not a generic notebook. Teaching this before prompt assembly is correct. |\n| Prompt assembly | `constants/prompts.ts`, prompt sections, memory prompt loading | `s10`, `s10a` | The source builds inputs from many sections. The teaching repo is right to present prompt assembly as a pipeline instead of one giant string. |\n| Recovery and continuation | query transition reasons, retry branches, compaction retry, token recovery | `s11`, `s00c` | The reference repo has explicit continuation logic. This belongs after loop, tools, compaction, permissions, memory, and prompt assembly already exist. |\n| Durable work graph | task records, task board concepts, dependency unlocks | `s12` | The teaching repo correctly separates durable work goals from temporary session planning. |\n| Live runtime tasks | `tasks/types.ts`, `LocalShellTask`, `LocalAgentTask`, `RemoteAgentTask`, `MonitorMcpTask` | `s13`, `s13a` | The source has a clear runtime-task union. This strongly validates the teaching split between `TaskRecord` and `RuntimeTaskState`. |\n| Scheduled triggers | `ScheduleCronTool/*`, `useScheduledTasks` | `s14` | Scheduling appears after runtime work exists, which is exactly the correct dependency order. |\n| Persistent teammates | `InProcessTeammateTask`, team tools, agent registries | `s15` | The source clearly grows from one-shot subagents into durable actors. Teaching teammates later is correct. |\n| Structured team coordination | message envelopes, send-message flows, request tracking, coordinator mode | `s16` | Protocols make sense only after durable actors exist. The current order matches the real dependency. |\n| Autonomous claiming and resuming | coordinator mode, task claiming, async worker lifecycle, resume logic | `s17` | Autonomy in the source is not magic. It is layered on top of actors, tasks, and coordination rules. The current placement is correct. |\n| Worktree execution lanes | `EnterWorktreeTool`, `ExitWorktreeTool`, agent worktree helpers | `s18` | The reference repo treats worktree as an execution-lane boundary with closeout logic. Teaching it after tasks and teammates prevents concept collapse. |\n| External capability bus | `MCPTool`, `services/mcp/*`, `plugins/*`, MCP resources/prompts/tools | `s19`, `s19a` | The source clearly places MCP and plugins at the outer platform boundary. Keeping this last is the right teaching choice. |\n\n## The Most Important Validation Points\n\nThe reference repo strongly confirms five teaching choices.\n\n### 1. `s03` should stay before `s12`\n\nThe source contains both:\n\n- small session planning\n- larger durable task/runtime machinery\n\nThose are not the same thing.\n\nThe teaching repo is correct to teach:\n\n`session planning first -> durable tasks later`\n\n### 2. `s09` should stay before `s10`\n\nThe source builds the model input from multiple sources, including memory.\n\nThat means:\n\n- memory is one input source\n- prompt assembly is the pipeline that combines sources\n\nSo memory should be explained before prompt assembly.\n\n### 3. `s12` must stay before `s13`\n\nThe runtime-task union in the reference repo is one of the strongest pieces of evidence in the whole comparison.\n\nIt shows that:\n\n- durable work definitions\n- live running executions\n\nmust stay conceptually separate.\n\nIf `s13` came first, you would almost certainly merge those two layers.\n\n### 4. `s15 -> s16 -> s17` is the right order\n\nThe source has:\n\n- durable actors\n- structured coordination\n- autonomous resume / claiming behavior\n\nAutonomy depends on the first two. So the current order is correct.\n\n### 5. `s18` should stay before `s19`\n\nThe reference repo treats worktree isolation as a local execution-boundary mechanism.\n\nThat should be understood before you are asked to reason about:\n\n- external capability providers\n- MCP servers\n- plugin-installed surfaces\n\nOtherwise external capability looks more central than it really is.\n\n## What This Teaching Repo Should Still Avoid Copying\n\nThe reference repo contains many things that are real, but should still not dominate the teaching mainline:\n\n- CLI command surface area\n- UI rendering details\n- telemetry and analytics branches\n- product integration glue\n- remote and enterprise wiring\n- platform-specific compatibility code\n- line-by-line naming trivia\n\nThese are valid implementation details.\n\nThey are not the right center of a 0-to-1 teaching path.\n\n## Where The Teaching Repo Must Be Extra Careful\n\nThe mapping also reveals several places where things can easily drift into confusion.\n\n### 1. Do not merge subagents and teammates into one vague concept\n\nThe reference repo's `AgentTool` spans:\n\n- one-shot delegation\n- async/background workers\n- teammate-like persistent workers\n- worktree-isolated workers\n\nThat is exactly why the teaching repo should split the story across:\n\n- `s04`\n- `s15`\n- `s17`\n- `s18`\n\n### 2. Do not teach worktree as \"just a git trick\"\n\nThe source shows closeout, resume, cleanup, and isolation state around worktrees.\n\nSo `s18` should keep teaching:\n\n- lane identity\n- task binding\n- keep/remove closeout\n- resume and cleanup concerns\n\nnot just `git worktree add`.\n\n### 3. Do not reduce MCP to \"remote tools\"\n\nThe source includes:\n\n- tools\n- resources\n- prompts\n- elicitation / connection state\n- plugin mediation\n\nSo `s19` should keep a tools-first teaching path, but still explain the wider capability-bus boundary.\n\n## Final Judgment\n\nCompared against the high-signal module clusters in the reference repo, the current chapter order is sound.\n\nThe biggest remaining quality gains do **not** come from another major reorder.\n\nThey come from:\n\n- cleaner bridge docs\n- stronger entity-boundary explanations\n- tighter multilingual consistency\n- web pages that expose the same learning map clearly\n\n## Key Takeaway\n\n**The best teaching order is not the order files appear in a repo. It is the order in which dependencies become understandable to a learner who wants to rebuild the system.**\n"
  },
  {
    "version": null,
    "slug": "s00f-code-reading-order",
    "locale": "en",
    "title": "s00f: Code Reading Order",
    "kind": "bridge",
    "filename": "s00f-code-reading-order.md",
    "content": "# s00f: Code Reading Order\n\n> **Deep Dive** -- Read this when you're about to open the Python agent files and want a strategy for reading them.\n\nThis page is not about reading more code. It answers a narrower question: once the chapter order is stable, what is the cleanest order for reading this repository's code without scrambling your mental model again?\n\n## Conclusion First\n\nDo not read the code like this:\n\n- do not start with the longest file\n- do not jump straight into the most \"advanced\" chapter\n- do not open `web/` first and then guess the mainline\n- do not treat all `agents/*.py` files like one flat source pool\n\nThe stable rule is simple:\n\n**read the code in the same order as the curriculum.**\n\nInside each chapter file, keep the same reading order:\n\n1. state structures\n2. tool definitions or registries\n3. the function that advances one turn\n4. the CLI entry last\n\n## Why This Page Exists\n\nYou will probably not get lost in the prose first. You will get lost when you finally open the code and immediately start scanning the wrong things.\n\nTypical mistakes:\n\n- staring at the bottom half of a long file first\n- reading a pile of `run_*` helpers before knowing where they connect\n- jumping into late platform chapters and treating early chapters as \"too simple\"\n- collapsing `task`, `runtime task`, `teammate`, and `worktree` back into one vague idea\n\n## Use The Same Reading Template For Every Agent File\n\nFor any `agents/sXX_*.py`, read in this order:\n\n### 1. File header\n\nAnswer two questions before anything else:\n\n- what is this chapter teaching\n- what is it intentionally not teaching yet\n\n### 2. State structures or manager classes\n\nLook for things like:\n\n- `LoopState`\n- `PlanningState`\n- `CompactState`\n- `TaskManager`\n- `BackgroundManager`\n- `TeammateManager`\n- `WorktreeManager`\n\n### 3. Tool list or registry\n\nLook for:\n\n- `TOOLS`\n- `TOOL_HANDLERS`\n- `build_tool_pool()`\n- the important `run_*` entrypoints\n\n### 4. The turn-advancing function\n\nUsually this is one of:\n\n- `run_one_turn(...)`\n- `agent_loop(...)`\n- a chapter-specific `handle_*`\n\n### 5. CLI entry last\n\n`if __name__ == \"__main__\"` matters, but it should not be the first thing you study.\n\n## Stage 1: `s01-s06`\n\nThis stage is the single-agent backbone taking shape.\n\n| Chapter | File | Read First | Then Read | Confirm Before Moving On |\n|---|---|---|---|---|\n| `s01` | `agents/s01_agent_loop.py` | `LoopState` | `TOOLS` -> `execute_tool_calls()` -> `run_one_turn()` -> `agent_loop()` | You can trace `messages -> model -> tool_result -> next turn` |\n| `s02` | `agents/s02_tool_use.py` | `safe_path()` | tool handlers -> `TOOL_HANDLERS` -> `agent_loop()` | You understand how tools grow without rewriting the loop |\n| `s03` | `agents/s03_todo_write.py` | planning state types | todo handler path -> reminder injection -> `agent_loop()` | You understand visible session planning state |\n| `s04` | `agents/s04_subagent.py` | `AgentTemplate` | `run_subagent()` -> parent `agent_loop()` | You understand that subagents are mainly context isolation |\n| `s05` | `agents/s05_skill_loading.py` | skill registry types | registry methods -> `agent_loop()` | You understand discover light, load deep |\n| `s06` | `agents/s06_context_compact.py` | `CompactState` | persist / micro compact / history compact -> `agent_loop()` | You understand that compaction relocates detail instead of deleting continuity |\n\n## Stage 2: `s07-s11`\n\nThis stage hardens the control plane around a working single agent.\n\n| Chapter | File | Read First | Then Read | Confirm Before Moving On |\n|---|---|---|---|---|\n| `s07` | `agents/s07_permission_system.py` | validator / manager | permission path -> `run_bash()` -> `agent_loop()` | You understand gate before execute |\n| `s08` | `agents/s08_hook_system.py` | `HookManager` | hook registration and dispatch -> `agent_loop()` | You understand fixed extension points |\n| `s09` | `agents/s09_memory_system.py` | memory managers | save path -> prompt build -> `agent_loop()` | You understand memory as a long-term information layer |\n| `s10` | `agents/s10_system_prompt.py` | `SystemPromptBuilder` | reminder builder -> `agent_loop()` | You understand input assembly as a pipeline |\n| `s11` | `agents/s11_error_recovery.py` | compact / backoff helpers | recovery branches -> `agent_loop()` | You understand continuation after failure |\n\n## Stage 3: `s12-s14`\n\nThis stage turns the harness into a work runtime.\n\n| Chapter | File | Read First | Then Read | Confirm Before Moving On |\n|---|---|---|---|---|\n| `s12` | `agents/s12_task_system.py` | `TaskManager` | task create / dependency / unlock -> `agent_loop()` | You understand durable work goals |\n| `s13` | `agents/s13_background_tasks.py` | `NotificationQueue` / `BackgroundManager` | background registration -> notification drain -> `agent_loop()` | You understand runtime slots |\n| `s14` | `agents/s14_cron_scheduler.py` | `CronLock` / `CronScheduler` | cron match -> trigger -> `agent_loop()` | You understand future start conditions |\n\n## Stage 4: `s15-s19`\n\nThis stage is about platform boundaries.\n\n| Chapter | File | Read First | Then Read | Confirm Before Moving On |\n|---|---|---|---|---|\n| `s15` | `agents/s15_agent_teams.py` | `MessageBus` / `TeammateManager` | roster / inbox / loop -> `agent_loop()` | You understand persistent teammates |\n| `s16` | `agents/s16_team_protocols.py` | `RequestStore` / `TeammateManager` | request handlers -> `agent_loop()` | You understand request-response plus `request_id` |\n| `s17` | `agents/s17_autonomous_agents.py` | claim and identity helpers | claim path -> resume path -> `agent_loop()` | You understand idle check -> safe claim -> resume work |\n| `s18` | `agents/s18_worktree_task_isolation.py` | `TaskManager` / `WorktreeManager` / `EventBus` | worktree lifecycle -> `agent_loop()` | You understand goals versus execution lanes |\n| `s19` | `agents/s19_mcp_plugin.py` | capability gate / MCP client / plugin loader / router | tool pool build -> route -> normalize -> `agent_loop()` | You understand how external capability enters the same control plane |\n\n## Best Doc + Code Loop\n\nFor each chapter:\n\n1. read the chapter prose\n2. read the bridge note for that chapter\n3. open the matching `agents/sXX_*.py`\n4. follow the order: state -> tools -> turn driver -> CLI entry\n5. run the demo once\n6. rewrite the smallest version from scratch\n\n## Key Takeaway\n\n**Code reading order must obey teaching order: read boundaries first, then state, then the path that advances the loop.**\n"
  },
  {
    "version": "s01",
    "slug": "s01-the-agent-loop",
    "locale": "en",
    "title": "s01: The Agent Loop",
    "kind": "chapter",
    "filename": "s01-the-agent-loop.md",
    "content": "# s01: The Agent Loop\n\n`[ s01 ] > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n## What You'll Learn\n\n- How the core agent loop works: send messages, run tools, feed results back\n- Why the \"write-back\" step is the single most important idea in agent design\n- How to build a working agent in under 30 lines of Python\n\nImagine you have a brilliant assistant who can reason about code, plan solutions, and write great answers -- but cannot touch anything. Every time it suggests running a command, you have to copy it, run it yourself, paste the output back, and wait for the next suggestion. You are the loop. This chapter removes you from that loop.\n\n## The Problem\n\nWithout a loop, every tool call requires a human in the middle. The model says \"run this test.\" You run it. You paste the output. The model says \"now fix line 12.\" You fix it. You tell the model what happened. This manual back-and-forth might work for a single question, but it falls apart completely when a task requires 10, 20, or 50 tool calls in a row.\n\nThe solution is simple: let the code do the looping.\n\n## The Solution\n\nHere's the entire system in one picture:\n\n```\n+--------+      +-------+      +---------+\n|  User  | ---> |  LLM  | ---> |  Tool   |\n| prompt |      |       |      | execute |\n+--------+      +---+---+      +----+----+\n                    ^                |\n                    |   tool_result  |\n                    +----------------+\n                    (loop until the model stops calling tools)\n```\n\nThe model talks, the harness (the code wrapping the model) executes tools, and the results go right back into the conversation. The loop keeps spinning until the model decides it's done.\n\n## How It Works\n\n**Step 1.** The user's prompt becomes the first message.\n\n```python\nmessages.append({\"role\": \"user\", \"content\": query})\n```\n\n**Step 2.** Send the conversation to the model, along with tool definitions.\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.** Add the model's response to the conversation. Then check: did it call a tool, or is it done?\n\n```python\nmessages.append({\"role\": \"assistant\", \"content\": response.content})\n\n# If the model didn't call a tool, the task is finished\nif response.stop_reason != \"tool_use\":\n    return\n```\n\n**Step 4.** Execute each tool call, collect the results, and put them back into the conversation as a new message. Then loop back to Step 2.\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,  # links result to the tool call\n            \"content\": output,\n        })\n# This is the \"write-back\" -- the model can now see the real-world result\nmessages.append({\"role\": \"user\", \"content\": results})\n```\n\nPut it all together, and the entire agent fits in one function:\n\n```python\ndef agent_loop(query):\n    messages = [{\"role\": \"user\", \"content\": query}]\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  # model is done\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\nThat's the entire agent in under 30 lines. Everything else in this course layers on top of this loop -- without changing its core shape.\n\n> **A note about real systems:** Production agents typically use streaming responses, where the model's output arrives token by token instead of all at once. That changes the user experience (you see text appearing in real time), but the fundamental loop -- send, execute, write back -- stays exactly the same. We skip streaming here to keep the core idea crystal clear.\n\n## What Changed\n\n| Component     | Before     | After                          |\n|---------------|------------|--------------------------------|\n| Agent loop    | (none)     | `while True` + stop_reason     |\n| Tools         | (none)     | `bash` (one tool)              |\n| Messages      | (none)     | Accumulating list              |\n| Control flow  | (none)     | `stop_reason != \"tool_use\"`    |\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s01_agent_loop.py\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?`\n4. `Create a directory called test_output and write 3 files in it`\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Build a working agent loop from scratch\n- Explain why tool results must flow back into the conversation (the \"write-back\")\n- Redraw the loop from memory: messages -> model -> tool execution -> write-back -> next turn\n\n## What's Next\n\nRight now, the agent can only run bash commands. That means every file read uses `cat`, every edit uses `sed`, and there's no safety boundary at all. In the next chapter, you'll add dedicated tools with a clean routing system -- and the loop itself won't need to change at all.\n\n## Key Takeaway\n\n> An agent is just a loop: send messages to the model, execute the tools it asks for, feed the results back, and repeat until it's done.\n"
  },
  {
    "version": "s02",
    "slug": "s02-tool-use",
    "locale": "en",
    "title": "s02: Tool Use",
    "kind": "chapter",
    "filename": "s02-tool-use.md",
    "content": "# s02: Tool Use\n\n`s01 > [ s02 ] > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n## What You'll Learn\n\n- How to build a dispatch map (a routing table that maps tool names to handler functions)\n- How path sandboxing prevents the model from escaping its workspace\n- How to add new tools without touching the agent loop\n\nIf you ran the s01 agent for more than a few minutes, you probably noticed the cracks. `cat` silently truncates long files. `sed` chokes on special characters. Every bash command is an open door -- nothing stops the model from running `rm -rf /` or reading your SSH keys. You need dedicated tools with guardrails, and you need a clean way to add them.\n\n## The Problem\n\nWith only `bash`, the agent shells out for everything. There is no way to limit what it reads, where it writes, or how much output it returns. A single bad command can corrupt files, leak secrets, or blow past your token budget with a massive stdout dump. What you really want is a small set of purpose-built tools -- `read_file`, `write_file`, `edit_file` -- each with its own safety checks. The question is: how do you wire them in without rewriting the loop every time?\n\n## The Solution\n\nThe answer is a dispatch map -- one dictionary that routes tool names to handler functions. Adding a tool means adding one entry. The loop itself never changes.\n\n```\n+--------+      +-------+      +------------------+\n|  User  | ---> |  LLM  | ---> | Tool Dispatch    |\n| prompt |      |       |      | {                |\n+--------+      +---+---+      |   bash: run_bash |\n                    ^           |   read: run_read |\n                    |           |   write: run_wr  |\n                    +-----------+   edit: run_edit |\n                    tool_result | }                |\n                                +------------------+\n\nThe dispatch map is a dict: {tool_name: handler_function}.\nOne lookup replaces any if/elif chain.\n```\n\n## How It Works\n\n**Step 1.** Each tool gets a handler function. Path sandboxing prevents the model from escaping the workspace -- every requested path is resolved and checked against the working directory before any I/O happens.\n\n```python\ndef safe_path(p: str) -> Path:\n    path = (WORKDIR / p).resolve()\n    if not path.is_relative_to(WORKDIR):\n        raise ValueError(f\"Path escapes workspace: {p}\")\n    return path\n\ndef run_read(path: str, limit: int = None) -> str:\n    text = safe_path(path).read_text()\n    lines = text.splitlines()\n    if limit and limit < len(lines):\n        lines = lines[:limit]\n    return \"\\n\".join(lines)[:50000]  # hard cap to avoid blowing up the context\n```\n\n**Step 2.** The dispatch map links tool names to handlers. This is the entire routing layer -- no if/elif chain, no class hierarchy, just a dictionary.\n\n```python\nTOOL_HANDLERS = {\n    \"bash\":       lambda **kw: run_bash(kw[\"command\"]),\n    \"read_file\":  lambda **kw: run_read(kw[\"path\"], kw.get(\"limit\")),\n    \"write_file\": lambda **kw: run_write(kw[\"path\"], kw[\"content\"]),\n    \"edit_file\":  lambda **kw: run_edit(kw[\"path\"], kw[\"old_text\"],\n                                        kw[\"new_text\"]),\n}\n```\n\n**Step 3.** In the loop, look up the handler by name. The loop body itself is unchanged from s01 -- only the dispatch line is new.\n\n```python\nfor block in response.content:\n    if block.type == \"tool_use\":\n        handler = TOOL_HANDLERS.get(block.name)\n        output = handler(**block.input) if handler \\\n            else f\"Unknown tool: {block.name}\"\n        results.append({\n            \"type\": \"tool_result\",\n            \"tool_use_id\": block.id,\n            \"content\": output,\n        })\n```\n\nAdd a tool = add a handler + add a schema entry. The loop never changes.\n\n## What Changed From s01\n\n| Component      | Before (s01)       | After (s02)                |\n|----------------|--------------------|----------------------------|\n| Tools          | 1 (bash only)      | 4 (bash, read, write, edit)|\n| Dispatch       | Hardcoded bash call | `TOOL_HANDLERS` dict       |\n| Path safety    | None               | `safe_path()` sandbox      |\n| Agent loop     | Unchanged          | Unchanged                  |\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s02_tool_use.py\n```\n\n1. `Read the file requirements.txt`\n2. `Create a file called greet.py with a greet(name) function`\n3. `Edit greet.py to add a docstring to the function`\n4. `Read greet.py to verify the edit worked`\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Wire any new tool into the agent by adding one handler and one schema entry -- without touching the loop.\n- Enforce path sandboxing so the model cannot read or write outside its workspace.\n- Explain why a dispatch map scales better than an if/elif chain.\n\nKeep the boundary clean: a tool schema is enough for now. You do not need policy layers, approval UIs, or plugin ecosystems yet. If you can add one new tool without rewriting the loop, you have the core pattern down.\n\n## What's Next\n\nYour agent can now read, write, and edit files safely. But what happens when you ask it to do a 10-step refactoring? It finishes steps 1 through 3 and then starts improvising because it forgot the rest. In s03, you will give the agent a session plan -- a structured todo list that keeps it on track through complex, multi-step tasks.\n\n## Key Takeaway\n\n> The loop should not care how a tool works internally. It only needs a reliable route from tool name to handler.\n"
  },
  {
    "version": null,
    "slug": "s02a-tool-control-plane",
    "locale": "en",
    "title": "s02a: Tool Control Plane",
    "kind": "bridge",
    "filename": "s02a-tool-control-plane.md",
    "content": "# s02a: Tool Control Plane\n\n> **Deep Dive** -- Best read after s02 and before s07. It shows why tools become more than a simple lookup table.\n\n### When to Read This\n\nAfter you understand basic tool dispatch and before you add permissions.\n\n---\n\n> This bridge document answers another key question:\n>\n> **Why is a tool system more than a `tool_name -> handler` table?**\n\n## Why This Document Exists\n\n`s02` correctly teaches tool registration and dispatch first.\n\nThat is the right teaching move because you should first understand how the model turns intent into action.\n\nBut later the tool layer starts carrying much more responsibility:\n\n- permission checks\n- MCP routing\n- notifications\n- shared runtime state\n- message access\n- app state\n- capability-specific restrictions\n\nAt that point, the tool layer is no longer just a function table.\n\nIt becomes a control plane (the coordination layer that decides *how* each tool call gets routed and executed, rather than performing the tool work itself).\n\n## Terms First\n\n### Tool control plane\n\nThe part of the system that decides **how** a tool call executes:\n\n- where it runs\n- whether it is allowed\n- what state it can access\n- whether it is native or external\n\n### Execution context\n\nThe runtime environment visible to the tool:\n\n- current working directory\n- current permission mode\n- current messages\n- available MCP clients\n- app state and notification channels\n\n### Capability source\n\nNot every tool comes from the same place. Common sources:\n\n- native local tools\n- MCP tools\n- agent/team/task/worktree platform tools\n\n## The Smallest Useful Mental Model\n\nThink of the tool system as four layers:\n\n```text\n1. ToolSpec\n   what the model sees\n\n2. Tool Router\n   where the request gets sent\n\n3. ToolUseContext\n   what environment the tool can access\n\n4. Tool Result Envelope\n   how the output returns to the main loop\n```\n\nThe biggest step up is layer 3:\n\n**high-completion systems are defined less by the dispatch table and more by the shared execution context.**\n\n## Core Structures\n\n### `ToolSpec`\n\n```python\ntool = {\n    \"name\": \"read_file\",\n    \"description\": \"Read file contents.\",\n    \"input_schema\": {...},\n}\n```\n\n### `ToolDispatchMap`\n\n```python\nhandlers = {\n    \"read_file\": read_file,\n    \"write_file\": write_file,\n    \"bash\": run_bash,\n}\n```\n\nNecessary, but not sufficient.\n\n### `ToolUseContext`\n\n```python\ntool_use_context = {\n    \"tools\": handlers,\n    \"permission_context\": {...},\n    \"mcp_clients\": {},\n    \"messages\": [...],\n    \"app_state\": {...},\n    \"notifications\": [],\n    \"cwd\": \"...\",\n}\n```\n\nThe key point:\n\nTools stop receiving only input parameters.\nThey start receiving a shared runtime environment.\n\n### `ToolResultEnvelope`\n\n```python\nresult = {\n    \"ok\": True,\n    \"content\": \"...\",\n    \"is_error\": False,\n    \"attachments\": [],\n}\n```\n\nThis makes it easier to support:\n\n- plain text output\n- structured output\n- error output\n- attachment-like results\n\n## Why `ToolUseContext` Eventually Becomes Necessary\n\nCompare two systems.\n\n### System A: dispatch map only\n\n```python\noutput = handlers[tool_name](**tool_input)\n```\n\nFine for a demo.\n\n### System B: dispatch map plus execution context\n\n```python\noutput = handlers[tool_name](tool_input, tool_use_context)\n```\n\nCloser to a real platform.\n\nWhy?\n\nBecause now:\n\n- `bash` needs permissions\n- `mcp__...` needs a client\n- `agent` tools need execution environment setup\n- `task_output` may need file writes plus notification write-back\n\n## Minimal Implementation Path\n\n### 1. Keep `ToolSpec` and handlers\n\nDo not throw away the simple model.\n\n### 2. Introduce one shared context object\n\n```python\nclass ToolUseContext:\n    def __init__(self):\n        self.handlers = {}\n        self.permission_context = {}\n        self.mcp_clients = {}\n        self.messages = []\n        self.app_state = {}\n        self.notifications = []\n```\n\n### 3. Let all handlers receive the context\n\n```python\ndef run_tool(tool_name: str, tool_input: dict, ctx: ToolUseContext):\n    handler = ctx.handlers[tool_name]\n    return handler(tool_input, ctx)\n```\n\n### 4. Route by capability source\n\n```python\ndef route_tool(tool_name: str, tool_input: dict, ctx: ToolUseContext):\n    if tool_name.startswith(\"mcp__\"):\n        return run_mcp_tool(tool_name, tool_input, ctx)\n    return run_native_tool(tool_name, tool_input, ctx)\n```\n\n## Key Takeaway\n\n**A mature tool system is not just a name-to-function map. It is a shared execution plane that decides how model action intent becomes real work.**\n"
  },
  {
    "version": null,
    "slug": "s02b-tool-execution-runtime",
    "locale": "en",
    "title": "s02b: Tool Execution Runtime",
    "kind": "bridge",
    "filename": "s02b-tool-execution-runtime.md",
    "content": "# s02b: Tool Execution Runtime\n\n> **Deep Dive** -- Best read after s02, when you want to understand concurrent tool execution.\n\n### When to Read This\n\nWhen you start wondering how multiple tool calls in one turn get executed safely.\n\n---\n\n> This bridge note is not about how tools are registered.\n>\n> It is about a deeper question:\n>\n> **When the model emits multiple tool calls, what rules decide concurrency, progress updates, result ordering, and context merging?**\n\n## Why This Note Exists\n\n`s02` correctly teaches:\n\n- tool schema\n- dispatch map\n- `tool_result` flowing back into the loop\n\nThat is the right starting point.\n\nBut once the system grows, the hard questions move one layer deeper:\n\n- which tools can run in parallel\n- which tools should stay serial\n- whether long-running tools should emit progress first\n- whether concurrent results should write back in completion order or original order\n- whether tool execution mutates shared context\n- how concurrent mutations should merge safely\n\nThose questions are not about registration anymore.\n\nThey belong to the **tool execution runtime** -- the set of rules the system follows once tool calls actually start executing, including scheduling, tracking, yielding progress, and merging results.\n\n## Terms First\n\n### What \"tool execution runtime\" means here\n\nThis is not the programming language runtime.\n\nHere it means:\n\n> the rules the system uses once tool calls actually start executing\n\nThose rules include scheduling, tracking, yielding progress, and merging results.\n\n### What \"concurrency safe\" means\n\nA tool is concurrency safe when:\n\n> it can run alongside similar work without corrupting shared state\n\nTypical read-only tools are often safe:\n\n- `read_file`\n- some search tools\n- query-only MCP tools\n\nMany write tools are not:\n\n- `write_file`\n- `edit_file`\n- tools that modify shared application state\n\n### What a progress message is\n\nA progress message means:\n\n> the tool is not done yet, but the system already surfaces what it is doing\n\nThis keeps the user informed during long-running operations rather than leaving them staring at silence.\n\n### What a context modifier is\n\nSome tools do more than return text.\n\nThey also modify shared runtime context, for example:\n\n- update a notification queue\n- record active tools\n- mutate app state\n\nThat shared-state mutation is called a context modifier.\n\n## The Minimum Mental Model\n\nDo not flatten tool execution into:\n\n```text\ntool_use -> handler -> result\n```\n\nA better mental model is:\n\n```text\ntool_use blocks\n  ->\npartition by concurrency safety\n  ->\nchoose concurrent or serial execution\n  ->\nemit progress if needed\n  ->\nwrite results back in stable order\n  ->\nmerge queued context modifiers\n```\n\nTwo upgrades matter most:\n\n- concurrency is not \"all tools run together\"\n- shared context should not be mutated in random completion order\n\n## Core Records\n\n### 1. `ToolExecutionBatch`\n\nA minimal teaching batch can look like:\n\n```python\nbatch = {\n    \"is_concurrency_safe\": True,\n    \"blocks\": [tool_use_1, tool_use_2, tool_use_3],\n}\n```\n\nThe point is simple:\n\n- tools are not always handled one by one\n- the runtime groups them into execution batches first\n\n### 2. `TrackedTool`\n\nIf you want a higher-completion execution layer, track each tool explicitly:\n\n```python\ntracked_tool = {\n    \"id\": \"toolu_01\",\n    \"name\": \"read_file\",\n    \"status\": \"queued\",   # queued / executing / completed / yielded\n    \"is_concurrency_safe\": True,\n    \"pending_progress\": [],\n    \"results\": [],\n    \"context_modifiers\": [],\n}\n```\n\nThis makes the runtime able to answer:\n\n- what is still waiting\n- what is already running\n- what has completed\n- what has already yielded progress\n\n### 3. `MessageUpdate`\n\nTool execution may produce more than one final result.\n\nA minimal update can be treated as:\n\n```python\nupdate = {\n    \"message\": maybe_message,\n    \"new_context\": current_context,\n}\n```\n\nIn a larger runtime, updates usually split into two channels:\n\n- messages that should surface upstream immediately\n- context changes that should stay internal until merge time\n\n### 4. Queued context modifiers\n\nThis is easy to skip, but it is one of the most important ideas.\n\nIn a concurrent batch, the safer strategy is not:\n\n> \"whichever tool finishes first mutates shared context first\"\n\nThe safer strategy is:\n\n> queue context modifiers first, then merge them later in the original tool order\n\nFor example:\n\n```python\nqueued_context_modifiers = {\n    \"toolu_01\": [modify_ctx_a],\n    \"toolu_02\": [modify_ctx_b],\n}\n```\n\n## Minimum Implementation Steps\n\n### Step 1: classify concurrency safety\n\n```python\ndef is_concurrency_safe(tool_name: str, tool_input: dict) -> bool:\n    return tool_name in {\"read_file\", \"search_files\"}\n```\n\n### Step 2: partition before execution\n\n```python\nbatches = partition_tool_calls(tool_uses)\n\nfor batch in batches:\n    if batch[\"is_concurrency_safe\"]:\n        run_concurrently(batch[\"blocks\"])\n    else:\n        run_serially(batch[\"blocks\"])\n```\n\n### Step 3: let concurrent batches emit progress\n\n```python\nfor update in run_concurrently(...):\n    if update.get(\"message\"):\n        yield update[\"message\"]\n```\n\n### Step 4: merge context in stable order\n\n```python\nqueued_modifiers = {}\n\nfor update in concurrent_updates:\n    if update.get(\"context_modifier\"):\n        queued_modifiers[update[\"tool_id\"]].append(update[\"context_modifier\"])\n\nfor tool in original_batch_order:\n    for modifier in queued_modifiers.get(tool[\"id\"], []):\n        context = modifier(context)\n```\n\nThis is one of the places where a teaching repo can still stay simple while remaining honest about the real system shape.\n\n## The Picture You Should Hold\n\n```text\ntool_use blocks\n  |\n  v\npartition by concurrency safety\n  |\n  +-- safe batch ----------> concurrent execution\n  |                            |\n  |                            +-- progress updates\n  |                            +-- final results\n  |                            +-- queued context modifiers\n  |\n  +-- exclusive batch -----> serial execution\n                               |\n                               +-- direct result\n                               +-- direct context update\n```\n\n## Why This Matters More Than the Dispatch Map\n\nIn a tiny demo:\n\n```python\nhandlers[tool_name](tool_input)\n```\n\nis enough.\n\nBut in a higher-completion agent, the hard part is no longer calling the right handler.\n\nThe hard part is:\n\n- scheduling multiple tools safely\n- keeping progress visible\n- making result ordering stable\n- preventing shared context from becoming nondeterministic\n\nThat is why tool execution runtime deserves its own deep dive.\n\n## Key Takeaway\n\n**Once the model emits multiple tool calls per turn, the hard problem shifts from dispatch to safe concurrent execution with stable result ordering.**\n"
  },
  {
    "version": "s03",
    "slug": "s03-todo-write",
    "locale": "en",
    "title": "s03: TodoWrite",
    "kind": "chapter",
    "filename": "s03-todo-write.md",
    "content": "# s03: TodoWrite\n\n`s01 > s02 > [ s03 ] > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n## What You'll Learn\n\n- How session planning keeps the model on track during multi-step tasks\n- How a structured todo list with status tracking replaces fragile free-form plans\n- How gentle reminders (nag injection) pull the model back when it drifts\n\nHave you ever asked an AI to do a complex task and watched it lose track halfway through? You say \"refactor this module: add type hints, docstrings, tests, and a main guard\" and it nails the first two steps, then wanders off into something you never asked for. This is not a model intelligence problem -- it is a working memory problem. As tool results pile up in the conversation, the original plan fades. By step 4, the model has effectively forgotten steps 5 through 10. You need a way to keep the plan visible.\n\n## The Problem\n\nOn multi-step tasks, the model drifts. It repeats work, skips steps, or improvises once the system prompt fades behind pages of tool output. The context window (the total amount of text the model can hold in working memory at once) is finite, and earlier instructions get pushed further away with every tool call. A 10-step refactoring might complete steps 1-3, then the model starts making things up because it simply cannot \"see\" steps 4-10 anymore.\n\n## The Solution\n\nGive the model a `todo` tool that maintains a structured checklist. Then inject gentle reminders when the model goes too long without updating its plan.\n\n```\n+--------+      +-------+      +---------+\n|  User  | ---> |  LLM  | ---> | Tools   |\n| prompt |      |       |      | + todo  |\n+--------+      +---+---+      +----+----+\n                    ^                |\n                    |   tool_result  |\n                    +----------------+\n                          |\n              +-----------+-----------+\n              | TodoManager state     |\n              | [ ] task A            |\n              | [>] task B  <- doing  |\n              | [x] task C            |\n              +-----------------------+\n                          |\n              if rounds_since_todo >= 3:\n                inject <reminder> into tool_result\n```\n\n## How It Works\n\n**Step 1.** TodoManager stores items with statuses. The \"one `in_progress` at a time\" constraint forces the model to finish what it started before moving on.\n\n```python\nclass TodoManager:\n    def update(self, items: list) -> str:\n        validated, in_progress_count = [], 0\n        for item in items:\n            status = item.get(\"status\", \"pending\")\n            if status == \"in_progress\":\n                in_progress_count += 1\n            validated.append({\"id\": item[\"id\"], \"text\": item[\"text\"],\n                              \"status\": status})\n        if in_progress_count > 1:\n            raise ValueError(\"Only one task can be in_progress\")\n        self.items = validated\n        return self.render()  # returns the checklist as formatted text\n```\n\n**Step 2.** The `todo` tool goes into the dispatch map like any other tool -- no special wiring needed, just one more entry in the dictionary you built in s02.\n\n```python\nTOOL_HANDLERS = {\n    # ...base tools...\n    \"todo\": lambda **kw: TODO.update(kw[\"items\"]),\n}\n```\n\n**Step 3.** A nag reminder injects a nudge if the model goes 3+ rounds without calling `todo`. This is the write-back trick (feeding tool results back into the conversation) used for a new purpose: the harness (the code wrapping around the model) quietly inserts a reminder into the results payload before it is appended to messages.\n\n```python\nif rounds_since_todo >= 3:\n    results.insert(0, {\n        \"type\": \"text\",\n        \"text\": \"<reminder>Update your todos.</reminder>\",\n    })\nmessages.append({\"role\": \"user\", \"content\": results})\n```\n\nThe \"one in_progress at a time\" constraint forces sequential focus. The nag reminder creates accountability. Together, they keep the model working through its plan instead of drifting.\n\n## What Changed From s02\n\n| Component      | Before (s02)     | After (s03)                |\n|----------------|------------------|----------------------------|\n| Tools          | 4                | 5 (+todo)                  |\n| Planning       | None             | TodoManager with statuses  |\n| Nag injection  | None             | `<reminder>` after 3 rounds|\n| Agent loop     | Simple dispatch  | + rounds_since_todo counter|\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s03_todo_write.py\n```\n\n1. `Refactor the file hello.py: add type hints, docstrings, and a main guard`\n2. `Create a Python package with __init__.py, utils.py, and tests/test_utils.py`\n3. `Review all Python files and fix any style issues`\n\nWatch the model create a plan, work through it step by step, and check off items as it goes. If it forgets to update the plan for a few rounds, you will see the `<reminder>` nudge appear in the conversation.\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Add session planning to any agent by dropping a `todo` tool into the dispatch map.\n- Enforce sequential focus with the \"one in_progress at a time\" constraint.\n- Use nag injection to pull the model back on track when it drifts.\n- Explain why structured state beats free-form prose for multi-step plans.\n\nKeep three boundaries in mind: `todo` here means \"plan for the current conversation\", not a durable task database. The tiny schema `{id, text, status}` is enough. A direct reminder is enough -- you do not need a sophisticated planning UI yet.\n\n## What's Next\n\nYour agent can now plan its work and stay on track. But every file it reads, every bash output it produces -- all of it stays in the conversation forever, eating into the context window. A five-file investigation might burn thousands of tokens (roughly word-sized pieces -- a 1000-line file uses about 4000 tokens) that the parent conversation never needs again. In s04, you will learn how to spin up subagents with fresh, isolated context -- so the parent stays clean and the model stays sharp.\n\n## Key Takeaway\n\n> Once the plan lives in structured state instead of free-form prose, the agent drifts much less.\n"
  },
  {
    "version": "s04",
    "slug": "s04-subagent",
    "locale": "en",
    "title": "s04: Subagents",
    "kind": "chapter",
    "filename": "s04-subagent.md",
    "content": "# s04: Subagents\n\n`s01 > s02 > s03 > [ s04 ] > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n## What You'll Learn\n- Why exploring a side question can pollute the parent agent's context\n- How a subagent gets a fresh, empty message history\n- How only a short summary travels back to the parent\n- Why the child's full message history is discarded after use\n\nImagine you ask your agent \"What testing framework does this project use?\" To answer, it reads five files, parses config blocks, and compares import statements. All of that exploration is useful for a moment -- but once the answer is \"pytest,\" you really don't want those five file dumps sitting in the conversation forever. Every future API call now carries that dead weight, burning tokens and distracting the model. You need a way to ask a side question in a clean room and bring back only the answer.\n\n## The Problem\n\nAs the agent works, its `messages` array grows. Every file read, every bash output stays in context permanently. A simple question like \"what testing framework is this?\" might require reading five files, but the parent only needs one word back: \"pytest.\" Without isolation, those intermediate artifacts stay in context for the rest of the session, wasting tokens on every subsequent API call and muddying the model's attention. The longer a session runs, the worse this gets -- context fills with exploration debris that has nothing to do with the current task.\n\n## The Solution\n\nThe parent agent delegates side tasks to a child agent that starts with an empty `messages=[]`. The child does all the messy exploration, then only its final text summary travels back. The child's full history is discarded.\n\n```\nParent agent                     Subagent\n+------------------+             +------------------+\n| messages=[...]   |             | messages=[]      | <-- fresh\n|                  |  dispatch   |                  |\n| tool: task       | ----------> | while tool_use:  |\n|   prompt=\"...\"   |             |   call tools     |\n|                  |  summary    |   append results |\n|   result = \"...\" | <---------- | return last text |\n+------------------+             +------------------+\n\nParent context stays clean. Subagent context is discarded.\n```\n\n## How It Works\n\n**Step 1.** The parent gets a `task` tool that the child does not. This prevents recursive spawning -- a child cannot create its own children.\n\n```python\nPARENT_TOOLS = CHILD_TOOLS + [\n    {\"name\": \"task\",\n     \"description\": \"Spawn a subagent with fresh context.\",\n     \"input_schema\": {\n         \"type\": \"object\",\n         \"properties\": {\"prompt\": {\"type\": \"string\"}},\n         \"required\": [\"prompt\"],\n     }},\n]\n```\n\n**Step 2.** The subagent starts with `messages=[]` and runs its own agent loop. Only the final text block returns to the parent as a `tool_result`.\n\n```python\ndef run_subagent(prompt: str) -> str:\n    sub_messages = [{\"role\": \"user\", \"content\": prompt}]\n    for _ in range(30):  # safety limit\n        response = client.messages.create(\n            model=MODEL, system=SUBAGENT_SYSTEM,\n            messages=sub_messages,\n            tools=CHILD_TOOLS, max_tokens=8000,\n        )\n        sub_messages.append({\"role\": \"assistant\",\n                             \"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                handler = TOOL_HANDLERS.get(block.name)\n                output = handler(**block.input)\n                results.append({\"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": str(output)[:50000]})\n        sub_messages.append({\"role\": \"user\", \"content\": results})\n    # Extract only the final text -- everything else is thrown away\n    return \"\".join(\n        b.text for b in response.content if hasattr(b, \"text\")\n    ) or \"(no summary)\"\n```\n\nThe child's entire message history (possibly 30+ tool calls worth of file reads and bash outputs) is discarded the moment `run_subagent` returns. The parent receives a one-paragraph summary as a normal `tool_result`, keeping its own context clean.\n\n## What Changed From s03\n\n| Component      | Before (s03)     | After (s04)               |\n|----------------|------------------|---------------------------|\n| Tools          | 5                | 5 (base) + task (parent)  |\n| Context        | Single shared    | Parent + child isolation  |\n| Subagent       | None             | `run_subagent()` function |\n| Return value   | N/A              | Summary text only         |\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s04_subagent.py\n```\n\n1. `Use a subtask to find what testing framework this project uses`\n2. `Delegate: read all .py files and summarize what each one does`\n3. `Use a task to create a new module, then verify it from here`\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Explain why a subagent is primarily a **context boundary**, not a process trick\n- Spawn a one-shot child agent with a fresh `messages=[]`\n- Return only a summary to the parent, discarding all intermediate exploration\n- Decide which tools the child should and should not have access to\n\nYou don't need long-lived workers, resumable sessions, or worktree isolation yet. The core idea is simple: give the subtask a clean workspace in memory, then bring back only the answer the parent still needs.\n\n## What's Next\n\nSo far you've learned to keep context clean by isolating side tasks. But what about the knowledge the agent carries in the first place? In s05, you'll see how to avoid bloating the system prompt with domain expertise the model might never use -- loading skills on demand instead of upfront.\n\n## Key Takeaway\n\n> A subagent is a disposable scratch pad: fresh context in, short summary out, everything else discarded.\n"
  },
  {
    "version": "s05",
    "slug": "s05-skill-loading",
    "locale": "en",
    "title": "s05: Skills",
    "kind": "chapter",
    "filename": "s05-skill-loading.md",
    "content": "# s05: Skills\n\n`s01 > s02 > s03 > s04 > [ s05 ] > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n## What You'll Learn\n- Why stuffing all domain knowledge into the system prompt wastes tokens\n- The two-layer loading pattern: cheap names up front, expensive bodies on demand\n- How frontmatter (YAML metadata at the top of a file) gives each skill a name and description\n- How the model decides for itself which skill to load and when\n\nYou don't memorize every recipe in every cookbook you own. You know which shelf each cookbook sits on, and you pull one down only when you're actually cooking that dish. An agent's domain knowledge works the same way. You might have expertise files for git workflows, testing patterns, code review checklists, PDF processing -- dozens of topics. Loading all of them into the system prompt on every request is like reading every cookbook cover to cover before cracking a single egg. Most of that knowledge is irrelevant to any given task.\n\n## The Problem\n\nYou want your agent to follow domain-specific workflows: git conventions, testing best practices, code review checklists. The naive approach is to put everything in the system prompt. But 10 skills at 2,000 tokens each means 20,000 tokens of instructions on every API call -- most of which have nothing to do with the current question. You pay for those tokens every turn, and worse, all that irrelevant text competes for the model's attention with the content that actually matters.\n\n## The Solution\n\nSplit knowledge into two layers. Layer 1 lives in the system prompt and is cheap: just skill names and one-line descriptions (~100 tokens per skill). Layer 2 is the full skill body, loaded on demand through a tool call only when the model decides it needs that knowledge.\n\n```\nSystem prompt (Layer 1 -- always present):\n+--------------------------------------+\n| You are a coding agent.              |\n| Skills available:                    |\n|   - git: Git workflow helpers        |  ~100 tokens/skill\n|   - test: Testing best practices     |\n+--------------------------------------+\n\nWhen model calls load_skill(\"git\"):\n+--------------------------------------+\n| tool_result (Layer 2 -- on demand):  |\n| <skill name=\"git\">                   |\n|   Full git workflow instructions...  |  ~2000 tokens\n|   Step 1: ...                        |\n| </skill>                             |\n+--------------------------------------+\n```\n\n## How It Works\n\n**Step 1.** Each skill is a directory containing a `SKILL.md` file. The file starts with YAML frontmatter (a metadata block delimited by `---` lines) that declares the skill's name and description, followed by the full instruction body.\n\n```\nskills/\n  pdf/\n    SKILL.md       # ---\\n name: pdf\\n description: Process PDF files\\n ---\\n ...\n  code-review/\n    SKILL.md       # ---\\n name: code-review\\n description: Review code\\n ---\\n ...\n```\n\n**Step 2.** `SkillLoader` scans for all `SKILL.md` files at startup. It parses the frontmatter to extract names and descriptions, and stores the full body for later retrieval.\n\n```python\nclass SkillLoader:\n    def __init__(self, skills_dir: Path):\n        self.skills = {}\n        for f in sorted(skills_dir.rglob(\"SKILL.md\")):\n            text = f.read_text()\n            meta, body = self._parse_frontmatter(text)\n            # Use the frontmatter name, or fall back to the directory name\n            name = meta.get(\"name\", f.parent.name)\n            self.skills[name] = {\"meta\": meta, \"body\": body}\n\n    def get_descriptions(self) -> str:\n        \"\"\"Layer 1: cheap one-liners for the system prompt.\"\"\"\n        lines = []\n        for name, skill in self.skills.items():\n            desc = skill[\"meta\"].get(\"description\", \"\")\n            lines.append(f\"  - {name}: {desc}\")\n        return \"\\n\".join(lines)\n\n    def get_content(self, name: str) -> str:\n        \"\"\"Layer 2: full body, returned as a tool_result.\"\"\"\n        skill = self.skills.get(name)\n        if not skill:\n            return f\"Error: Unknown skill '{name}'.\"\n        return f\"<skill name=\\\"{name}\\\">\\n{skill['body']}\\n</skill>\"\n```\n\n**Step 3.** Layer 1 goes into the system prompt so the model always knows what skills exist. Layer 2 is wired up as a normal tool handler -- the model calls `load_skill` when it decides it needs the full instructions.\n\n```python\nSYSTEM = f\"\"\"You are a coding agent at {WORKDIR}.\nSkills available:\n{SKILL_LOADER.get_descriptions()}\"\"\"\n\nTOOL_HANDLERS = {\n    # ...base tools...\n    \"load_skill\": lambda **kw: SKILL_LOADER.get_content(kw[\"name\"]),\n}\n```\n\nThe model learns what skills exist (cheap, ~100 tokens each) and loads them only when relevant (expensive, ~2000 tokens each). On a typical turn, only one skill is loaded instead of all ten.\n\n## What Changed From s04\n\n| Component      | Before (s04)     | After (s05)                |\n|----------------|------------------|----------------------------|\n| Tools          | 5 (base + task)  | 5 (base + load_skill)      |\n| System prompt  | Static string    | + skill descriptions       |\n| Knowledge      | None             | skills/\\*/SKILL.md files   |\n| Injection      | None             | Two-layer (system + result)|\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s05_skill_loading.py\n```\n\n1. `What skills are available?`\n2. `Load the agent-builder skill and follow its instructions`\n3. `I need to do a code review -- load the relevant skill first`\n4. `Build an MCP server using the mcp-builder skill`\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Explain why \"list first, load later\" beats stuffing everything into the system prompt\n- Write a `SKILL.md` with YAML frontmatter that a `SkillLoader` can discover\n- Wire up two-layer loading: cheap descriptions in the system prompt, full bodies via `tool_result`\n- Let the model decide for itself when domain knowledge is worth loading\n\nYou don't need skill ranking systems, multi-provider merging, parameterized templates, or recovery-time restoration rules. The core pattern is simple: advertise cheaply, load on demand.\n\n## What's Next\n\nYou now know how to keep knowledge out of context until it's needed. But what happens when context grows large anyway -- after dozens of turns of real work? In s06, you'll learn how to compress a long conversation down to its essentials so the agent can keep working without hitting token limits.\n\n## Key Takeaway\n\n> Advertise skill names cheaply in the system prompt; load the full body through a tool call only when the model actually needs it.\n"
  },
  {
    "version": "s06",
    "slug": "s06-context-compact",
    "locale": "en",
    "title": "s06: Context Compact",
    "kind": "chapter",
    "filename": "s06-context-compact.md",
    "content": "# s06: Context Compact\n\n`s01 > s02 > s03 > s04 > s05 > [ s06 ] > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n## What You'll Learn\n\n- Why long sessions inevitably run out of context space, and what happens when they do\n- A four-lever compression strategy: persisted output, micro-compact, auto-compact, and manual compact\n- How to move detail out of active memory without losing it\n- How to keep a session alive indefinitely by summarizing and continuing\n\nYour agent from s05 is capable. It reads files, runs commands, edits code, and delegates subtasks. But try something ambitious -- ask it to refactor a module that touches 30 files. After reading all of them and running 20 shell commands, you will notice the responses get worse. The model starts forgetting what it already read. It repeats work. Eventually the API rejects your request entirely. You have hit the context window limit, and without a plan for that, your agent is stuck.\n\n## The Problem\n\nEvery API call to the model includes the entire conversation so far: every user message, every assistant response, every tool call and its result. The model's context window (the total amount of text it can hold in working memory at once) is finite. A single `read_file` on a 1000-line source file costs roughly 4,000 tokens (roughly word-sized pieces -- a 1,000-line file uses about 4,000 tokens). Read 30 files and run 20 bash commands, and you have burned through 100,000+ tokens. The context is full, but the work is only half done.\n\nThe naive fix -- just truncating old messages -- throws away information the agent might need later. A smarter approach compresses strategically: keep the important bits, move the bulky details to disk, and summarize when the conversation gets too long. That is what this chapter builds.\n\n## The Solution\n\nWe use four levers, each working at a different stage of the pipeline, from output-time filtering to full conversation summarization.\n\n```\nEvery tool call:\n+------------------+\n| Tool call result |\n+------------------+\n        |\n        v\n[Lever 0: persisted-output]     (at tool execution time)\n  Large outputs (>50KB, bash >30KB) are written to disk\n  and replaced with a <persisted-output> preview marker.\n        |\n        v\n[Lever 1: micro_compact]        (silent, every turn)\n  Replace tool_result > 3 turns old\n  with \"[Previous: used {tool_name}]\"\n  (preserves read_file results as reference material)\n        |\n        v\n[Check: tokens > 50000?]\n   |               |\n   no              yes\n   |               |\n   v               v\ncontinue    [Lever 2: auto_compact]\n              Save transcript to .transcripts/\n              LLM summarizes conversation.\n              Replace all messages with [summary].\n                    |\n                    v\n            [Lever 3: compact tool]\n              Model calls compact explicitly.\n              Same summarization as auto_compact.\n```\n\n## How It Works\n\n### Step 1: Lever 0 -- Persisted Output\n\nThe first line of defense runs at tool execution time, before a result even enters the conversation. When a tool result exceeds a size threshold, we write the full output to disk and replace it with a short preview. This prevents a single giant command output from consuming half the context window.\n\n```python\nPERSIST_OUTPUT_TRIGGER_CHARS_DEFAULT = 50000\nPERSIST_OUTPUT_TRIGGER_CHARS_BASH = 30000   # bash uses a lower threshold\n\ndef maybe_persist_output(tool_use_id, output, trigger_chars=None):\n    if len(output) <= trigger:\n        return output                                    # small enough -- keep inline\n    stored_path = _persist_tool_result(tool_use_id, output)\n    return _build_persisted_marker(stored_path, output)  # swap in a compact preview\n    # Returns: <persisted-output>\n    #   Output too large (48.8KB). Full output saved to: .task_outputs/tool-results/abc123.txt\n    #   Preview (first 2.0KB):\n    #   ... first 2000 chars ...\n    # </persisted-output>\n```\n\nThe model can later `read_file` the stored path to access the full content if needed. Nothing is lost -- the detail just lives on disk instead of in the conversation.\n\n### Step 2: Lever 1 -- Micro-Compact\n\nBefore each LLM call, we scan for old tool results and replace them with one-line placeholders. This is invisible to the user and runs every turn. The key subtlety: we preserve `read_file` results because those serve as reference material the model often needs to look back at.\n\n```python\nPRESERVE_RESULT_TOOLS = {\"read_file\"}\n\ndef micro_compact(messages: list) -> list:\n    tool_results = [...]  # collect all tool_result entries\n    if len(tool_results) <= KEEP_RECENT:\n        return messages                                  # not enough results to compact yet\n    for part in tool_results[:-KEEP_RECENT]:\n        if tool_name in PRESERVE_RESULT_TOOLS:\n            continue   # keep reference material\n        part[\"content\"] = f\"[Previous: used {tool_name}]\"  # replace with short placeholder\n    return messages\n```\n\n### Step 3: Lever 2 -- Auto-Compact\n\nWhen micro-compaction is not enough and the token count crosses a threshold, the harness takes a bigger step: it saves the full transcript to disk for recovery, asks the LLM to summarize the entire conversation, and then replaces all messages with that summary. The agent continues from the summary as if nothing happened.\n\n```python\ndef auto_compact(messages: list) -> list:\n    # Save transcript for recovery\n    transcript_path = TRANSCRIPT_DIR / f\"transcript_{int(time.time())}.jsonl\"\n    with open(transcript_path, \"w\") as f:\n        for msg in messages:\n            f.write(json.dumps(msg, default=str) + \"\\n\")\n    # LLM summarizes\n    response = client.messages.create(\n        model=MODEL,\n        messages=[{\"role\": \"user\", \"content\":\n            \"Summarize this conversation for continuity...\"\n            + json.dumps(messages, default=str)[:80000]}],  # cap at 80K chars for the summary call\n        max_tokens=2000,\n    )\n    return [\n        {\"role\": \"user\", \"content\": f\"[Compressed]\\n\\n{response.content[0].text}\"},\n    ]\n```\n\n### Step 4: Lever 3 -- Manual Compact\n\nThe `compact` tool lets the model itself trigger summarization on demand. It uses exactly the same mechanism as auto-compact. The difference is who decides: auto-compact fires on a threshold, manual compact fires when the agent judges it is the right time to compress.\n\n### Step 5: Integration in the Agent Loop\n\nAll four levers compose naturally inside the main loop:\n\n```python\ndef agent_loop(messages: list):\n    while True:\n        micro_compact(messages)                        # Lever 1\n        if estimate_tokens(messages) > THRESHOLD:\n            messages[:] = auto_compact(messages)       # Lever 2\n        response = client.messages.create(...)\n        # ... tool execution with persisted-output ... # Lever 0\n        if manual_compact:\n            messages[:] = auto_compact(messages)       # Lever 3\n```\n\nTranscripts preserve full history on disk. Large outputs are saved to `.task_outputs/tool-results/`. Nothing is truly lost -- just moved out of active context.\n\n## What Changed From s05\n\n| Component         | Before (s05)     | After (s06)                |\n|-------------------|------------------|----------------------------|\n| Tools             | 5                | 5 (base + compact)         |\n| Context mgmt      | None             | Four-lever compression     |\n| Persisted-output  | None             | Large outputs -> disk + preview |\n| Micro-compact     | None             | Old results -> placeholders|\n| Auto-compact      | None             | Token threshold trigger    |\n| Transcripts       | None             | Saved to .transcripts/     |\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s06_context_compact.py\n```\n\n1. `Read every Python file in the agents/ directory one by one` (watch micro-compact replace old results)\n2. `Keep reading files until compression triggers automatically`\n3. `Use the compact tool to manually compress the conversation`\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Explain why a long agent session degrades and eventually fails without compression\n- Intercept oversized tool outputs before they enter the context window\n- Silently replace stale tool results with lightweight placeholders each turn\n- Trigger a full conversation summarization -- automatically on a threshold or manually via a tool call\n- Preserve full transcripts on disk so nothing is permanently lost\n\n## Stage 1 Complete\n\nYou now have a complete single-agent system. Starting from a bare API call in s01, you have built up tool use, structured planning, sub-agent delegation, dynamic skill loading, and context compression. Your agent can read, write, execute, plan, delegate, and work indefinitely without running out of memory. That is a real coding agent.\n\nBefore moving on, consider going back to s01 and rebuilding the whole stack from scratch without looking at the code. If you can write all six layers from memory, you truly own the ideas -- not just the implementation.\n\nStage 2 begins with s07 and hardens this foundation. You will add permission controls, hook systems, persistent memory, error recovery, and more. The single agent you built here becomes the kernel that everything else wraps around.\n\n## Key Takeaway\n\n> Compaction is not deleting history -- it is relocating detail so the agent can keep working.\n"
  },
  {
    "version": "s07",
    "slug": "s07-permission-system",
    "locale": "en",
    "title": "s07: Permission System",
    "kind": "chapter",
    "filename": "s07-permission-system.md",
    "content": "# s07: Permission System\n\n`s01 > s02 > s03 > s04 > s05 > s06 > [ s07 ] > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n## What You'll Learn\n\n- A four-stage permission pipeline that every tool call must pass through before execution\n- Three permission modes that control how aggressively the agent auto-approves actions\n- How deny and allow rules use pattern matching to create a first-match-wins policy\n- Interactive approval with an \"always\" option that writes permanent allow rules at runtime\n\nYour agent from s06 is capable and long-lived. It reads files, writes code, runs shell commands, delegates subtasks, and compresses its own context to keep going. But there is no safety catch. Every tool call the model proposes goes straight to execution. Ask it to delete a directory and it will -- no questions asked. Before you give this agent access to anything that matters, you need a gate between \"the model wants to do X\" and \"the system actually does X.\"\n\n## The Problem\n\nImagine your agent is helping refactor a codebase. It reads a few files, proposes some edits, and then decides to run `rm -rf /tmp/old_build` to clean up. Except the model hallucinated the path -- the real directory is your home folder. Or it decides to `sudo` something because the model has seen that pattern in training data. Without a permission layer, intent becomes execution instantly. There is no moment where the system can say \"wait, that looks dangerous\" or where you can say \"no, do not do that.\" The agent needs a checkpoint -- a pipeline (a sequence of stages that every request passes through) between what the model asks for and what actually happens.\n\n## The Solution\n\nEvery tool call now passes through a four-stage permission pipeline before execution. The stages run in order, and the first one that produces a definitive answer wins.\n\n```\ntool_call from LLM\n     |\n     v\n[1. Deny rules]     -- blocklist: always block these\n     |\n     v\n[2. Mode check]     -- plan mode? auto mode? default?\n     |\n     v\n[3. Allow rules]    -- allowlist: always allow these\n     |\n     v\n[4. Ask user]       -- interactive y/n/always prompt\n     |\n     v\nexecute (or reject)\n```\n\n## Read Together\n\n- If you start blurring \"the model proposed an action\" with \"the system actually executed an action,\" you might find it helpful to revisit [`s00a-query-control-plane.md`](./s00a-query-control-plane.md).\n- If you are not yet clear on why tool requests should not drop straight into handlers, keeping [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) open beside this chapter may help.\n- If `PermissionRule`, `PermissionDecision`, and `tool_result` start to collapse into one vague idea, [`data-structures.md`](./data-structures.md) can reset them.\n\n## How It Works\n\n**Step 1.** Define three permission modes. Each mode changes how the pipeline treats tool calls that do not match any explicit rule. \"Default\" mode is the safest -- it asks you about everything. \"Plan\" mode blocks all writes outright, useful when you want the agent to explore without touching anything. \"Auto\" mode lets reads through silently and only asks about writes, good for fast exploration.\n\n| Mode | Behavior | Use Case |\n|------|----------|----------|\n| `default` | Ask user for every unmatched tool call | Normal interactive use |\n| `plan` | Block all writes, allow reads | Planning/review mode |\n| `auto` | Auto-allow reads, ask for writes | Fast exploration mode |\n\n**Step 2.** Set up deny and allow rules with pattern matching. Rules are checked in order -- first match wins. Deny rules catch dangerous patterns that should never execute, regardless of mode. Allow rules let known-safe operations pass without asking.\n\n```python\nrules = [\n    # Always deny dangerous patterns\n    {\"tool\": \"bash\", \"content\": \"rm -rf /\", \"behavior\": \"deny\"},\n    {\"tool\": \"bash\", \"content\": \"sudo *\",   \"behavior\": \"deny\"},\n    # Allow reading anything\n    {\"tool\": \"read_file\", \"path\": \"*\", \"behavior\": \"allow\"},\n]\n```\n\nWhen the user answers \"always\" at the interactive prompt, a permanent allow rule is added at runtime.\n\n**Step 3.** Implement the four-stage check. This is the core of the permission system. Notice that deny rules run first and cannot be bypassed -- this is intentional. No matter what mode you are in or what allow rules exist, a deny rule always wins.\n\n```python\ndef check(self, tool_name, tool_input):\n    # Step 1: Deny rules (bypass-immune, always checked first)\n    for rule in self.rules:\n        if rule[\"behavior\"] == \"deny\" and self._matches(rule, ...):\n            return {\"behavior\": \"deny\", \"reason\": \"...\"}\n\n    # Step 2: Mode-based decisions\n    if self.mode == \"plan\" and tool_name in WRITE_TOOLS:\n        return {\"behavior\": \"deny\", \"reason\": \"Plan mode: writes blocked\"}\n    if self.mode == \"auto\" and tool_name in READ_ONLY_TOOLS:\n        return {\"behavior\": \"allow\", \"reason\": \"Auto: read-only approved\"}\n\n    # Step 3: Allow rules\n    for rule in self.rules:\n        if rule[\"behavior\"] == \"allow\" and self._matches(rule, ...):\n            return {\"behavior\": \"allow\", \"reason\": \"...\"}\n\n    # Step 4: Fall through to ask user\n    return {\"behavior\": \"ask\", \"reason\": \"...\"}\n```\n\n**Step 4.** Integrate the permission check into the agent loop. Every tool call now goes through the pipeline before execution. The result is one of three outcomes: denied (with a reason), allowed (silently), or asked (interactively).\n\n```python\nfor block in response.content:\n    if block.type == \"tool_use\":\n        decision = perms.check(block.name, block.input)\n\n        if decision[\"behavior\"] == \"deny\":\n            output = f\"Permission denied: {decision['reason']}\"\n        elif decision[\"behavior\"] == \"ask\":\n            if perms.ask_user(block.name, block.input):\n                output = handler(**block.input)\n            else:\n                output = \"Permission denied by user\"\n        else:  # allow\n            output = handler(**block.input)\n\n        results.append({\"type\": \"tool_result\", ...})\n```\n\n**Step 5.** Add denial tracking as a simple circuit breaker. The `PermissionManager` tracks consecutive denials. After 3 in a row, it suggests switching to plan mode -- this prevents the agent from repeatedly hitting the same wall and wasting turns.\n\n## What Changed From s06\n\n| Component | Before (s06) | After (s07) |\n|-----------|-------------|-------------|\n| Safety | None | 4-stage permission pipeline |\n| Modes | None | 3 modes: default, plan, auto |\n| Rules | None | Deny/allow rules with pattern matching |\n| User control | None | Interactive approval with \"always\" option |\n| Denial tracking | None | Circuit breaker after 3 consecutive denials |\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s07_permission_system.py\n```\n\n1. Start in `default` mode -- every write tool asks for approval\n2. Try `plan` mode -- all writes are blocked, reads pass through\n3. Try `auto` mode -- reads auto-approved, writes still ask\n4. Answer \"always\" to permanently allow a tool\n5. Type `/mode plan` to switch modes at runtime\n6. Type `/rules` to inspect current rule set\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Explain why model intent must pass through a decision pipeline before it becomes execution\n- Build a four-stage permission check: deny, mode, allow, ask\n- Configure three permission modes that give you different safety/speed tradeoffs\n- Add rules dynamically at runtime when a user answers \"always\"\n- Implement a simple circuit breaker that catches repeated denial loops\n\n## What's Next\n\nYour permission system controls what the agent is allowed to do, but it lives entirely inside the agent's own code. What if you want to extend behavior -- add logging, auditing, or custom validation -- without modifying the agent loop at all? That is what s08 introduces: a hook system that lets external shell scripts observe and influence every tool call.\n\n## Key Takeaway\n\n> Safety is a pipeline, not a boolean -- deny first, then consider mode, then check allow rules, then ask the user.\n"
  },
  {
    "version": "s08",
    "slug": "s08-hook-system",
    "locale": "en",
    "title": "s08: Hook System",
    "kind": "chapter",
    "filename": "s08-hook-system.md",
    "content": "# s08: Hook System\n\n`s01 > s02 > s03 > s04 > s05 > s06 > s07 > [ s08 ] > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n## What You'll Learn\n\n- Three lifecycle events that let external code observe and influence the agent loop\n- How shell-based hooks run as subprocesses with full context about the current tool call\n- The exit code protocol: 0 means continue, 1 means block, 2 means inject a message\n- How to configure hooks in an external JSON file so you never touch the main loop code\n\nYour agent from s07 has a permission system that controls what it is allowed to do. But permissions are a yes/no gate -- they do not let you add new behavior. Suppose you want every bash command to be logged to an audit file, or you want a linter to run automatically after every file write, or you want a custom security scanner to inspect tool inputs before they execute. You could add if/else branches inside the main loop for each of these, but that turns your clean loop into a tangle of special cases. What you really want is a way to extend the agent's behavior from the outside, without modifying the loop itself.\n\n## The Problem\n\nYou are running your agent in a team environment. Different teams want different behaviors: the security team wants to scan every bash command, the QA team wants to auto-run tests after file edits, and the ops team wants an audit trail of every tool call. If each of these requires code changes to the agent loop, you end up with a mess of conditionals that nobody can maintain. Worse, every new requirement means redeploying the agent. You need a way for teams to plug in their own logic at well-defined moments -- without touching the core code.\n\n## The Solution\n\nThe agent loop exposes three fixed extension points (lifecycle events). At each point, it runs external shell commands called hooks. Each hook communicates its intent through its exit code: continue silently, block the operation, or inject a message into the conversation.\n\n```\ntool_call from LLM\n     |\n     v\n[PreToolUse hooks]\n     |  exit 0 -> continue\n     |  exit 1 -> block tool, return stderr as error\n     |  exit 2 -> inject stderr into conversation, continue\n     |\n     v\n[execute tool]\n     |\n     v\n[PostToolUse hooks]\n     |  exit 0 -> continue\n     |  exit 2 -> append stderr to result\n     |\n     v\nreturn result\n```\n\n## Read Together\n\n- If you still picture hooks as \"more if/else branches inside the main loop,\" you might find it helpful to revisit [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) first.\n- If the main loop, the tool handler, and hook side effects start to blur together, [`entity-map.md`](./entity-map.md) can help you separate who advances core state and who only watches from the side.\n- If you plan to continue into prompt assembly, recovery, or teams, keeping [`s00e-reference-module-map.md`](./s00e-reference-module-map.md) nearby is useful because this \"core loop plus sidecar extension\" pattern returns repeatedly.\n\n## How It Works\n\n**Step 1.** Define three lifecycle events. `SessionStart` fires once when the agent starts up -- useful for initialization, logging, or environment checks. `PreToolUse` fires before every tool call and is the only event that can block execution. `PostToolUse` fires after every tool call and can annotate the result but cannot undo it.\n\n| Event | When | Can Block? |\n|-------|------|-----------|\n| `SessionStart` | Once at session start | No |\n| `PreToolUse` | Before each tool call | Yes (exit 1) |\n| `PostToolUse` | After each tool call | No |\n\n**Step 2.** Configure hooks in an external `.hooks.json` file at the workspace root. Each hook specifies a shell command to run. An optional `matcher` field filters by tool name -- without a matcher, the hook fires for every tool.\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\"matcher\": \"bash\", \"command\": \"echo 'Checking bash command...'\"},\n      {\"matcher\": \"write_file\", \"command\": \"/path/to/lint-check.sh\"}\n    ],\n    \"PostToolUse\": [\n      {\"command\": \"echo 'Tool finished'\"}\n    ],\n    \"SessionStart\": [\n      {\"command\": \"echo 'Session started at $(date)'\"}\n    ]\n  }\n}\n```\n\n**Step 3.** Implement the exit code protocol. This is the heart of the hook system -- three exit codes, three meanings. The protocol is deliberately simple so that any language or script can participate. Write your hook in bash, Python, Ruby, whatever -- as long as it exits with the right code.\n\n| Exit Code | Meaning | PreToolUse | PostToolUse |\n|-----------|---------|-----------|------------|\n| 0 | Success | Continue to execute tool | Continue normally |\n| 1 | Block | Tool NOT executed, stderr returned as error | Warning logged |\n| 2 | Inject | stderr injected as message, tool still executes | stderr appended to result |\n\n**Step 4.** Pass context to hooks via environment variables. Hooks need to know what is happening -- which event triggered them, which tool is being called, and what the input looks like. For `PostToolUse` hooks, the tool output is also available.\n\n```\nHOOK_EVENT=PreToolUse\nHOOK_TOOL_NAME=bash\nHOOK_TOOL_INPUT={\"command\": \"npm test\"}\nHOOK_TOOL_OUTPUT=...  (PostToolUse only)\n```\n\n**Step 5.** Integrate hooks into the agent loop. The integration is clean: run pre-hooks before execution, check if any blocked, execute the tool, run post-hooks, and collect any injected messages. The loop still owns control flow -- hooks only observe, block, or annotate at named moments.\n\n```python\n# Before tool execution\npre_result = hooks.run_hooks(\"PreToolUse\", ctx)\nif pre_result[\"blocked\"]:\n    output = f\"Blocked by hook: {pre_result['block_reason']}\"\n    continue\n\n# Execute tool\noutput = handler(**tool_input)\n\n# After tool execution\npost_result = hooks.run_hooks(\"PostToolUse\", ctx)\nfor msg in post_result[\"messages\"]:\n    output += f\"\\n[Hook note]: {msg}\"\n```\n\n## What Changed From s07\n\n| Component | Before (s07) | After (s08) |\n|-----------|-------------|-------------|\n| Extensibility | None | Shell-based hook system |\n| Events | None | PreToolUse, PostToolUse, SessionStart |\n| Control flow | Permission pipeline only | Permission + hooks |\n| Configuration | In-code rules | External `.hooks.json` file |\n\n## Try It\n\n```sh\ncd learn-claude-code\n# Create a hook config\ncat > .hooks.json << 'EOF'\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\"matcher\": \"bash\", \"command\": \"echo 'Auditing bash command' >&2; exit 0\"}\n    ],\n    \"SessionStart\": [\n      {\"command\": \"echo 'Agent session started'\"}\n    ]\n  }\n}\nEOF\npython agents/s08_hook_system.py\n```\n\n1. Watch SessionStart hook fire at startup\n2. Ask the agent to run a bash command -- see PreToolUse hook fire\n3. Create a blocking hook (exit 1) and watch it prevent tool execution\n4. Create an injecting hook (exit 2) and watch it add messages to the conversation\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Explain why extension points are better than in-loop conditionals for adding new behavior\n- Define lifecycle events at the right moments in the agent loop\n- Write shell hooks that communicate intent through a three-code exit protocol\n- Configure hooks externally so different teams can customize behavior without touching the agent code\n- Maintain the boundary: the loop owns control flow, the handler owns execution, hooks only observe, block, or annotate\n\n## What's Next\n\nYour agent can now execute tools safely (s07) and be extended without code changes (s08). But it still has amnesia -- every new session starts from zero. The user's preferences, corrections, and project context are forgotten the moment the session ends. In s09, you will build a memory system that lets the agent carry durable facts across sessions.\n\n## Key Takeaway\n\n> The main loop can expose fixed extension points without giving up ownership of control flow -- hooks observe, block, or annotate, but the loop still decides what happens next.\n"
  },
  {
    "version": "s09",
    "slug": "s09-memory-system",
    "locale": "en",
    "title": "s09: Memory System",
    "kind": "chapter",
    "filename": "s09-memory-system.md",
    "content": "# s09: Memory System\n\n`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > [ s09 ] > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n## What You'll Learn\n\n- Four memory categories that cover what is worth remembering: user preferences, feedback, project facts, and references\n- How YAML frontmatter files give each memory record a name, type, and description\n- What should NOT go into memory -- and why getting this boundary wrong is the most common mistake\n- The difference between memory, tasks, plans, and CLAUDE.md\n\nYour agent from s08 is powerful and extensible. It can execute tools safely, be extended through hooks, and work for long sessions thanks to context compression. But it has amnesia. Every time you start a new session, the agent meets you for the first time. It does not remember that you prefer pnpm over npm, that you told it three times to stop modifying test snapshots, or that the legacy directory cannot be deleted because deployment depends on it. You end up repeating yourself every session. The fix is a small, durable memory store -- not a dump of everything the agent has seen, but a curated set of facts that should still matter next time.\n\n## The Problem\n\nWithout memory, a new session starts from zero. The agent keeps forgetting things like long-term user preferences, corrections you have repeated multiple times, project constraints that are not obvious from the code itself, and external references the project depends on. The result is an agent that always feels like it is meeting you for the first time. You waste time re-establishing context that should have been saved once and loaded automatically.\n\n## The Solution\n\nA small file-based memory store saves durable facts as individual markdown files with YAML frontmatter (a metadata block at the top of each file, delimited by `---` lines). At the start of each session, relevant memories are loaded and injected into the model's context.\n\n```text\nconversation\n   |\n   | durable fact appears\n   v\nsave_memory\n   |\n   v\n.memory/\n  ├── MEMORY.md\n  ├── prefer_pnpm.md\n  ├── ask_before_codegen.md\n  └── incident_dashboard.md\n   |\n   v\nnext session loads relevant entries\n```\n\n## Read Together\n\n- If you still think memory is just \"a longer context window,\" you might find it helpful to revisit [`s06-context-compact.md`](./s06-context-compact.md) and re-separate compaction from durable memory.\n- If `messages[]`, summary blocks, and the memory store start to blend together, keeping [`data-structures.md`](./data-structures.md) open while reading can help.\n- If you are about to continue into s10, reading [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md) alongside this chapter is useful because memory matters most when it re-enters the next model input.\n\n## How It Works\n\n**Step 1.** Define four memory categories. These are the types of facts worth keeping across sessions. Each category has a clear purpose -- if a fact does not fit one of these, it probably should not be in memory.\n\n### 1. `user` -- Stable user preferences\n\nExamples: prefers `pnpm`, wants concise answers, dislikes large refactors without a plan.\n\n### 2. `feedback` -- Corrections the user wants enforced\n\nExamples: \"do not change test snapshots unless I ask\", \"ask before modifying generated files.\"\n\n### 3. `project` -- Durable project facts not obvious from the repo\n\nExamples: \"this old directory still cannot be deleted because deployment depends on it\", \"this service exists because of a compliance requirement, not technical preference.\"\n\n### 4. `reference` -- Pointers to external resources\n\nExamples: incident board URL, monitoring dashboard location, spec document location.\n\n```python\nMEMORY_TYPES = (\"user\", \"feedback\", \"project\", \"reference\")\n```\n\n**Step 2.** Save one record per file using frontmatter. Each memory is a markdown file with YAML frontmatter that tells the system what the memory is called, what kind it is, and what it is roughly about.\n\n```md\n---\nname: prefer_pnpm\ndescription: User prefers pnpm over npm\ntype: user\n---\nThe user explicitly prefers pnpm for package management commands.\n```\n\n```python\ndef save_memory(name, description, mem_type, content):\n    path = memory_dir / f\"{slugify(name)}.md\"\n    path.write_text(render_frontmatter(name, description, mem_type) + content)\n    rebuild_index()\n```\n\n**Step 3.** Build a small index so the system knows what memories exist without reading every file.\n\n```md\n# Memory Index\n\n- prefer_pnpm [user]\n- ask_before_codegen [feedback]\n- incident_dashboard [reference]\n```\n\nThe index is not the memory itself -- it is a quick map of what exists.\n\n**Step 4.** Load relevant memory at session start and turn it into a prompt section. Memory becomes useful only when it is fed back into the model input. This is why s09 naturally connects into s10.\n\n```python\nmemories = memory_store.load_all()\n```\n\n**Step 5.** Know what should NOT go into memory. This boundary is the most important part of the chapter, and the place where most beginners go wrong.\n\n| Do not store | Why |\n|---|---|\n| file tree layout | can be re-read from the repo |\n| function names and signatures | code is the source of truth |\n| current task status | belongs to task / plan, not memory |\n| temporary branch names or PR numbers | gets stale quickly |\n| secrets or credentials | security risk |\n\nThe right rule is: only keep information that still matters across sessions and cannot be cheaply re-derived from the current workspace.\n\n**Step 6.** Understand the boundaries against neighbor concepts. These four things sound similar but serve different purposes.\n\n| Concept | Purpose | Lifetime |\n|---------|---------|----------|\n| Memory | Facts that should survive across sessions | Persistent |\n| Task | What the system is trying to finish right now | One task |\n| Plan | How this turn or session intends to proceed | One session |\n| CLAUDE.md | Stable instruction documents and project-level standing rules | Persistent |\n\nShort rule of thumb: only useful for this task -- use `task` or `plan`. Useful next session too -- use `memory`. Long-lived instruction text -- use `CLAUDE.md`.\n\n## Common Mistakes\n\n**Mistake 1: Storing things the repo can tell you.** If the code can answer it, memory should not duplicate it. You will just end up with stale copies that conflict with reality.\n\n**Mistake 2: Storing live task progress.** \"Currently fixing auth\" is not memory. That belongs to plan or task state. When the task is done, the memory is meaningless.\n\n**Mistake 3: Treating memory as absolute truth.** Memory can be stale. The safer rule is: memory gives direction, current observation gives truth.\n\n## What Changed From s08\n\n| Component | Before (s08) | After (s09) |\n|-----------|-------------|-------------|\n| Cross-session state | None | File-based memory store |\n| Memory types | None | user, feedback, project, reference |\n| Storage format | None | YAML frontmatter markdown files |\n| Session start | Cold start | Loads relevant memories |\n| Durability | Everything forgotten | Key facts persist |\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s09_memory_system.py\n```\n\nTry asking it to remember:\n\n- a user preference\n- a correction you want enforced later\n- a project fact that is not obvious from the repository\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Explain why memory is a curated store of durable facts, not a dump of everything the agent has seen\n- Categorize facts into four types: user preferences, feedback, project knowledge, and references\n- Store and retrieve memories using frontmatter-based markdown files\n- Draw a clear line between what belongs in memory and what belongs in task state, plans, or CLAUDE.md\n- Avoid the three most common mistakes: duplicating the repo, storing transient state, and treating memories as ground truth\n\n## What's Next\n\nYour agent now remembers things across sessions, but those memories just sit in a file until session start. In s10, you will build the system prompt assembly pipeline -- the mechanism that takes memories, skills, permissions, and other context and weaves them into the prompt that the model actually sees on every turn.\n\n## Key Takeaway\n\n> Memory is not a dump of everything the agent has seen -- it is a small store of durable facts that should still matter next session.\n"
  },
  {
    "version": "s10",
    "slug": "s10-system-prompt",
    "locale": "en",
    "title": "s10: System Prompt",
    "kind": "chapter",
    "filename": "s10-system-prompt.md",
    "content": "# s10: System Prompt\n\n`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > [ s10 ] > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n## What You'll Learn\n\n- How to assemble the system prompt from independent sections instead of one hardcoded string\n- The boundary between stable content (role, rules) and dynamic content (date, cwd, per-turn reminders)\n- How CLAUDE.md files layer instructions without overwriting each other\n- Why memory must be re-injected through the prompt pipeline to actually guide the agent\n\nWhen your agent had one tool and one job, a single hardcoded prompt string worked fine. But look at everything your harness has accumulated by now: a role description, tool definitions, loaded skills, saved memory, CLAUDE.md instruction files, and per-turn runtime context. If you keep cramming all of that into one big string, nobody -- including you -- can tell where each piece came from, why it is there, or how to change it safely. The fix is to stop treating the prompt as a blob and start treating it as an assembly pipeline.\n\n## The Problem\n\nImagine you want to add a new tool to your agent. You open the system prompt, scroll past the role paragraph, past the safety rules, past the three skill descriptions, past the memory block, and paste a tool description somewhere in the middle. Next week someone else adds a CLAUDE.md loader and appends its output to the same string. A month later the prompt is 6,000 characters long, half of it is stale, and nobody remembers which lines are supposed to change per turn and which should stay fixed across the entire session.\n\nThis is not a hypothetical scenario -- it is the natural trajectory of every agent that keeps its prompt in a single variable.\n\n## The Solution\n\nTurn prompt construction into a pipeline. Each section has one source and one responsibility. A builder object assembles them in a fixed order, with a clear boundary between parts that stay stable and parts that change every turn.\n\n```text\n1. core identity and rules\n2. tool catalog\n3. skills\n4. memory\n5. CLAUDE.md instruction chain\n6. dynamic runtime context\n```\n\nThen assemble:\n\n```text\ncore\n+ tools\n+ skills\n+ memory\n+ claude_md\n+ dynamic_context\n= final model input\n```\n\n## How It Works\n\n**Step 1. Define the builder.** Each method owns exactly one source of content.\n\n```python\nclass SystemPromptBuilder:\n    def build(self) -> str:\n        parts = []\n        parts.append(self._build_core())\n        parts.append(self._build_tools())\n        parts.append(self._build_skills())\n        parts.append(self._build_memory())\n        parts.append(self._build_claude_md())\n        parts.append(self._build_dynamic())\n        return \"\\n\\n\".join(p for p in parts if p)\n```\n\nThat is the central idea of the chapter. Each `_build_*` method pulls from one source only: `_build_tools()` reads the tool list, `_build_memory()` reads the memory store, and so on. If you want to know where a line in the prompt came from, you check the one method responsible for it.\n\n**Step 2. Separate stable content from dynamic content.** This is the most important boundary in the entire pipeline.\n\nStable content changes rarely or never during a session:\n\n- role description\n- tool contract (the list of tools and their schemas)\n- long-lived safety rules\n- project instruction chain (CLAUDE.md files)\n\nDynamic content changes every turn or every few turns:\n\n- current date\n- current working directory\n- current mode (plan mode, code mode, etc.)\n- per-turn warnings or reminders\n\nMixing these together means the model re-reads thousands of tokens of stable text that have not changed, while the few tokens that did change are buried somewhere in the middle. A real system separates them with a boundary marker so the stable prefix can be cached across turns to save prompt tokens.\n\n**Step 3. Layer CLAUDE.md instructions.** `CLAUDE.md` is not the same as memory and not the same as a skill. It is a layered instruction source -- meaning multiple files contribute, and later layers add to earlier ones rather than replacing them:\n\n1. user-level instruction file (`~/.claude/CLAUDE.md`)\n2. project-root instruction file (`<project>/CLAUDE.md`)\n3. deeper subdirectory instruction files\n\nThe important point is not the filename itself. The important point is that instruction sources can be layered instead of overwritten.\n\n**Step 4. Re-inject memory.** Saving memory (in s09) is only half the mechanism. If memory never re-enters the model input, it is not actually guiding the agent. So memory naturally belongs in the prompt pipeline:\n\n- save durable facts in `s09`\n- re-inject them through the prompt builder in `s10`\n\n**Step 5. Attach per-turn reminders separately.** Some information is even more short-lived than \"dynamic context\" -- it only matters for this one turn and should not pollute the stable system prompt. A `system-reminder` user message keeps these transient signals outside the builder entirely:\n\n- this-turn-only instructions\n- temporary notices\n- transient recovery guidance\n\n## What Changed from s09\n\n| Aspect | s09: Memory System | s10: System Prompt |\n|--------|--------------------|--------------------|\n| Core concern | Persist durable facts across sessions | Assemble all sources into model input |\n| Memory's role | Write and store | Read and inject |\n| Prompt structure | Assumed but not managed | Explicit pipeline with sections |\n| Instruction files | Not addressed | CLAUDE.md layering introduced |\n| Dynamic context | Not addressed | Separated from stable content |\n\n## Read Together\n\n- If you still treat the prompt as one mysterious blob of text, revisit [`s00a-query-control-plane.md`](./s00a-query-control-plane.md) to see what reaches the model and through which control layers.\n- If you want to stabilize the order of assembly, keep [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md) beside this chapter -- it is the key bridge note for `s10`.\n- If system rules, tool docs, memory, and runtime state start to collapse into one big input lump, reset with [`data-structures.md`](./data-structures.md).\n\n## Common Beginner Mistakes\n\n**Mistake 1: teaching the prompt as one fixed string.** That hides how the system really grows. A fixed string is fine for a demo; it stops being fine the moment you add a second capability.\n\n**Mistake 2: putting every changing detail into the same prompt block.** That mixes durable rules with per-turn noise. When you update one, you risk breaking the other.\n\n**Mistake 3: treating skills, memory, and CLAUDE.md as the same thing.** They may all become prompt sections, but their source and purpose are different:\n\n- `skills`: optional capability packages loaded on demand\n- `memory`: durable cross-session facts about the user or project\n- `CLAUDE.md`: standing instruction documents that layer without overwriting\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s10_system_prompt.py\n```\n\nLook for these three things:\n\n1. where each section comes from\n2. which parts are stable\n3. which parts are generated dynamically each turn\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Build a system prompt from independent, testable sections instead of one opaque string\n- Draw a clear line between stable content and dynamic content\n- Layer instruction files so that project-level and directory-level rules coexist without overwriting\n- Re-inject memory into the prompt pipeline so saved facts actually influence the model\n- Attach per-turn reminders separately from the main system prompt\n\n## What's Next\n\nThe prompt assembly pipeline means your agent now enters each turn with the right instructions, the right tools, and the right context. But real work produces real failures -- output gets cut off, the prompt grows too large, the API times out. In [s11: Error Recovery](./s11-error-recovery.md), you will teach the harness to classify those failures and choose a recovery path instead of crashing.\n\n## Key Takeaway\n\n> The system prompt is an assembly pipeline with clear sections and clear boundaries, not one big mysterious string.\n"
  },
  {
    "version": null,
    "slug": "s10a-message-prompt-pipeline",
    "locale": "en",
    "title": "s10a: Message & Prompt Pipeline",
    "kind": "bridge",
    "filename": "s10a-message-prompt-pipeline.md",
    "content": "# s10a: Message & Prompt Pipeline\n\n> **Deep Dive** -- Best read alongside s10. It shows why the system prompt is only one piece of the model's full input.\n\n### When to Read This\n\nWhen you're working on prompt assembly and want to see the complete input pipeline.\n\n---\n\n> This bridge document extends `s10`.\n>\n> It exists to make one crucial idea explicit:\n>\n> **the system prompt matters, but it is not the whole model input.**\n\n## Why This Document Exists\n\n`s10` already upgrades the system prompt from one giant string into a maintainable assembly process.\n\nThat is important.\n\nBut a higher-completion system goes one step further and treats the whole model input as a pipeline made from multiple sources:\n\n- system prompt blocks\n- normalized messages\n- memory attachments\n- reminder injections\n- dynamic runtime context\n\nSo the true structure is:\n\n**a prompt pipeline, not only a prompt builder.**\n\n## Terms First\n\n### Prompt block\n\nA structured piece inside the system prompt, such as:\n\n- core identity\n- tool instructions\n- memory section\n- CLAUDE.md section\n\n### Normalized message\n\nA message that has already been converted into a stable shape suitable for the model API.\n\nThis is necessary because the raw system may contain:\n\n- user messages\n- assistant replies\n- tool results\n- reminder injections\n- attachment-like content\n\nNormalization ensures all of these fit the same structural contract before they reach the API.\n\n### System reminder\n\nA small temporary instruction injected for the current turn or current mode.\n\nUnlike a long-lived prompt block, a reminder is usually short-lived and situational -- for example, telling the model it is currently in \"plan mode\" or that a certain tool is temporarily unavailable.\n\n## The Smallest Useful Mental Model\n\nThink of the full input as a pipeline:\n\n```text\nmultiple sources\n  |\n  +-- system prompt blocks\n  +-- messages\n  +-- attachments\n  +-- reminders\n  |\n  v\nnormalize\n  |\n  v\nfinal API payload\n```\n\nThe key teaching point is:\n\n**separate the sources first, then normalize them into one stable input.**\n\n## Why System Prompt Is Not Everything\n\nThe system prompt is the right place for:\n\n- identity\n- stable rules\n- long-lived constraints\n- tool capability descriptions\n\nBut it is usually the wrong place for:\n\n- the latest `tool_result`\n- one-turn hook injections\n- temporary reminders\n- dynamic memory attachments\n\nThose belong in the message stream or in adjacent input surfaces.\n\n## Core Structures\n\n### `SystemPromptBlock`\n\n```python\nblock = {\n    \"text\": \"...\",\n    \"cache_scope\": None,\n}\n```\n\n### `PromptParts`\n\n```python\nparts = {\n    \"core\": \"...\",\n    \"tools\": \"...\",\n    \"skills\": \"...\",\n    \"memory\": \"...\",\n    \"claude_md\": \"...\",\n    \"dynamic\": \"...\",\n}\n```\n\n### `NormalizedMessage`\n\n```python\nmessage = {\n    \"role\": \"user\" | \"assistant\",\n    \"content\": [...],\n}\n```\n\nTreat `content` as a list of blocks, not just one string.\n\n### `ReminderMessage`\n\n```python\nreminder = {\n    \"role\": \"system\",\n    \"content\": \"Current mode: plan\",\n}\n```\n\nEven if your teaching implementation does not literally use `role=\"system\"` here, you should still keep the mental split:\n\n- long-lived prompt block\n- short-lived reminder\n\n## Minimal Implementation Path\n\n### 1. Keep a `SystemPromptBuilder`\n\nDo not throw away the prompt-builder step.\n\n### 2. Make messages a separate pipeline\n\n```python\ndef build_messages(raw_messages, attachments, reminders):\n    messages = normalize_messages(raw_messages)\n    messages = attach_memory(messages, attachments)\n    messages = append_reminders(messages, reminders)\n    return messages\n```\n\n### 3. Assemble the final payload only at the end\n\n```python\npayload = {\n    \"system\": build_system_prompt(),\n    \"messages\": build_messages(...),\n    \"tools\": build_tools(...),\n}\n```\n\nThis is the important mental upgrade:\n\n**system prompt, messages, and tools are parallel input surfaces, not replacements for one another.**\n\n## Key Takeaway\n\n**The model input is a pipeline of sources that are normalized late, not one mystical prompt blob. System prompt, messages, and tools are parallel surfaces that converge only at send time.**\n"
  },
  {
    "version": "s11",
    "slug": "s11-error-recovery",
    "locale": "en",
    "title": "s11: Error Recovery",
    "kind": "chapter",
    "filename": "s11-error-recovery.md",
    "content": "# s11: Error Recovery\n\n`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > [ s11 ] > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n## What You'll Learn\n\n- Three categories of recoverable failure: truncation, context overflow, and transient transport errors\n- How to route each failure to the right recovery branch (continuation, compaction, or backoff)\n- Why retry budgets prevent infinite loops\n- How recovery state keeps the \"why\" visible instead of burying it in a catch block\n\nYour agent is doing real work now -- reading files, writing code, calling tools across multiple turns. And real work produces real failures. Output gets cut off mid-sentence. The prompt grows past the model's context window. The API times out or hits a rate limit. If every one of these failures ends the run immediately, your system feels brittle and your users learn not to trust it. But here is the key insight: most of these failures are not true task failure. They are signals that the next step needs a different continuation path.\n\n## The Problem\n\nYour user asks the agent to refactor a large file. The model starts writing the new version, but the output hits `max_tokens` and stops mid-function. Without recovery, the agent just halts with a half-written file. The user has to notice, re-prompt, and hope the model picks up where it left off.\n\nOr: the conversation has been running for 40 turns. The accumulated messages push the prompt past the model's context limit. The API returns an error. Without recovery, the entire session is lost.\n\nOr: a momentary network hiccup drops the connection. Without recovery, the agent crashes even though the same request would succeed one second later.\n\nEach of these is a different kind of failure, and each needs a different recovery action. A single catch-all retry cannot handle all three correctly.\n\n## The Solution\n\nClassify the failure first, choose the recovery branch second, and enforce a retry budget so the system cannot loop forever.\n\n```text\nLLM call\n  |\n  +-- stop_reason == \"max_tokens\"\n  |      -> append continuation reminder\n  |      -> retry\n  |\n  +-- prompt too long\n  |      -> compact context\n  |      -> retry\n  |\n  +-- timeout / rate limit / connection error\n         -> back off\n         -> retry\n```\n\n## How It Works\n\n**Step 1. Track recovery state.** Before you can recover, you need to know how many times you have already tried. A simple counter per category prevents infinite loops:\n\n```python\nrecovery_state = {\n    \"continuation_attempts\": 0,\n    \"compact_attempts\": 0,\n    \"transport_attempts\": 0,\n}\n```\n\n**Step 2. Classify the failure.** Each failure maps to exactly one recovery kind. The classifier examines the stop reason and error text, then returns a structured decision:\n\n```python\ndef choose_recovery(stop_reason: str | None, error_text: str | None) -> dict:\n    if stop_reason == \"max_tokens\":\n        return {\"kind\": \"continue\", \"reason\": \"output truncated\"}\n\n    if error_text and \"prompt\" in error_text and \"long\" in error_text:\n        return {\"kind\": \"compact\", \"reason\": \"context too large\"}\n\n    if error_text and any(word in error_text for word in [\n        \"timeout\", \"rate\", \"unavailable\", \"connection\"\n    ]):\n        return {\"kind\": \"backoff\", \"reason\": \"transient transport failure\"}\n\n    return {\"kind\": \"fail\", \"reason\": \"unknown or non-recoverable error\"}\n```\n\nThe separation matters: classify first, act second. That way the recovery reason stays visible in state instead of disappearing inside a catch block.\n\n**Step 3. Handle continuation (truncated output).** When the model runs out of output space, the task did not fail -- the turn just ended too early. You inject a continuation reminder and retry:\n\n```python\nCONTINUE_MESSAGE = (\n    \"Output limit hit. Continue directly from where you stopped. \"\n    \"Do not restart or repeat.\"\n)\n```\n\nWithout this reminder, models tend to restart from the beginning or repeat what they already wrote. The explicit instruction to \"continue directly\" keeps the output flowing forward.\n\n**Step 4. Handle compaction (context overflow).** When the prompt becomes too large, the problem is not the task itself -- the accumulated context needs to shrink before the next turn can proceed. You call the same `auto_compact` mechanism from s06 to summarize history, then retry:\n\n```python\nif decision[\"kind\"] == \"compact\":\n    messages = auto_compact(messages)\n    continue\n```\n\n**Step 5. Handle backoff (transient errors).** When the error is probably temporary -- a timeout, a rate limit, a brief outage -- you wait and try again. Exponential backoff (doubling the delay each attempt, plus random jitter to avoid thundering-herd problems where many clients retry at the same instant) keeps the system from hammering a struggling server:\n\n```python\ndef backoff_delay(attempt: int) -> float:\n    delay = min(BACKOFF_BASE_DELAY * (2 ** attempt), BACKOFF_MAX_DELAY)\n    jitter = random.uniform(0, 1)\n    return delay + jitter\n```\n\n**Step 6. Wire it into the loop.** The recovery logic sits right inside the agent loop. Each branch either adjusts the messages and continues, or gives up:\n\n```python\nwhile True:\n    try:\n        response = client.messages.create(...)\n        decision = choose_recovery(response.stop_reason, None)\n    except Exception as e:\n        response = None\n        decision = choose_recovery(None, str(e).lower())\n\n    if decision[\"kind\"] == \"continue\":\n        messages.append({\"role\": \"user\", \"content\": CONTINUE_MESSAGE})\n        continue\n\n    if decision[\"kind\"] == \"compact\":\n        messages = auto_compact(messages)\n        continue\n\n    if decision[\"kind\"] == \"backoff\":\n        time.sleep(backoff_delay(...))\n        continue\n\n    if decision[\"kind\"] == \"fail\":\n        break\n```\n\nThe point is not clever code. The point is: classify, choose, retry with a budget.\n\n## What Changed from s10\n\n| Aspect | s10: System Prompt | s11: Error Recovery |\n|--------|--------------------|--------------------|\n| Core concern | Assemble model input from sections | Handle failures without crashing |\n| Loop behavior | Runs until end_turn or tool_use | Adds recovery branches before giving up |\n| Compaction | Not addressed | Triggered reactively on context overflow |\n| Retry logic | Not addressed | Budgeted per failure category |\n| State tracking | Prompt sections | Recovery counters |\n\n## A Note on Real Systems\n\nReal agent systems also persist session state to disk, so that a crash does not destroy a long-running conversation. Session persistence, checkpointing, and resumption are separate concerns from error recovery -- but they complement it. Recovery handles the failures you can retry in-process; persistence handles the failures you cannot. This teaching harness focuses on the in-process recovery paths, but keep in mind that production systems need both layers.\n\n## Read Together\n\n- If you start losing track of why the current query is still continuing, go back to [`s00c-query-transition-model.md`](./s00c-query-transition-model.md).\n- If context compaction and error recovery are starting to look like the same mechanism, reread [`s06-context-compact.md`](./s06-context-compact.md) to separate \"shrink context\" from \"recover after failure.\"\n- If you are about to move into `s12`, keep [`data-structures.md`](./data-structures.md) nearby because the task system adds a new durable work layer on top of recovery state.\n\n## Common Beginner Mistakes\n\n**Mistake 1: using one retry rule for every error.** Different failures need different recovery actions. Retrying a context-overflow error without compacting first will just produce the same error again.\n\n**Mistake 2: no retry budget.** Without budgets, the system can loop forever. Each recovery category needs its own counter and its own maximum.\n\n**Mistake 3: hiding the recovery reason.** The system should know *why* it is retrying. That reason should stay visible in state -- as a structured decision object -- not disappear inside a catch block.\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s11_error_recovery.py\n```\n\nTry forcing:\n\n- a long response (to trigger max_tokens continuation)\n- a large context (to trigger compaction)\n- a temporary timeout (to trigger backoff)\n\nThen observe which recovery branch the system chooses and how the retry counter increments.\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Classify agent failures into three recoverable categories and one terminal category\n- Route each failure to the correct recovery branch: continuation, compaction, or backoff\n- Enforce retry budgets so the system never loops forever\n- Keep recovery decisions visible as structured state instead of burying them in exception handlers\n- Explain why different failure types need different recovery actions\n\n## Stage 2 Complete\n\nYou have finished Stage 2 of the harness. Look at what you have built since Stage 1:\n\n- **s07 Permission System** -- the harness asks before acting, and the user controls what gets auto-approved\n- **s08 Hook System** -- external scripts run at lifecycle points without touching the agent loop\n- **s09 Memory System** -- durable facts survive across sessions\n- **s10 System Prompt** -- the prompt is an assembly pipeline with clear sections, not one big string\n- **s11 Error Recovery** -- failures route to the right recovery path instead of crashing\n\nYour agent started Stage 2 as a working loop that could call tools and manage context. It finishes Stage 2 as a system that governs itself: it checks permissions, runs hooks, remembers what matters, assembles its own instructions, and recovers from failures without human intervention.\n\nThat is a real agent harness. If you stopped here and built a product on top of it, you would have something genuinely useful.\n\nBut there is more to build. Stage 3 introduces structured work management -- task lists, background execution, and scheduled jobs. The agent stops being purely reactive and starts organizing its own work across time. See you in [s12: Task System](./s12-task-system.md).\n\n## Key Takeaway\n\n> Most agent failures are not true task failure -- they are signals to try a different continuation path, and the harness should classify them and recover automatically.\n"
  },
  {
    "version": "s12",
    "slug": "s12-task-system",
    "locale": "en",
    "title": "s12: Task System",
    "kind": "chapter",
    "filename": "s12-task-system.md",
    "content": "# s12: Task System\n\n`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > [ s12 ] > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n## What You'll Learn\n\n- How to promote a flat checklist into a task graph with explicit dependencies\n- How `blockedBy` and `blocks` edges express ordering and parallelism\n- How status transitions (`pending` -> `in_progress` -> `completed`) drive automatic unblocking\n- How persisting tasks to disk makes them survive compression and restarts\n\nBack in s03 you gave the agent a TodoWrite tool -- a flat checklist that tracks what is done and what is not. That works well for a single focused session. But real work has structure. Task B depends on task A. Tasks C and D can run in parallel. Task E waits for both C and D. A flat list cannot express any of that. And because the checklist lives only in memory, context compression (s06) wipes it clean. In this chapter you will replace the checklist with a proper task graph that understands dependencies, persists to disk, and becomes the coordination backbone for everything that follows.\n\n## The Problem\n\nImagine you ask your agent to refactor a codebase: parse the AST, transform the nodes, emit the new code, and run the tests. The parse step must finish before transform and emit can begin. Transform and emit can run in parallel. Tests must wait for both. With s03's flat TodoWrite, the agent has no way to express these relationships. It might attempt the transform before the parse is done, or run the tests before anything is ready. There is no ordering, no dependency tracking, and no status beyond \"done or not.\" Worse, if the context window fills up and compression kicks in, the entire plan vanishes.\n\n## The Solution\n\nPromote the checklist into a task graph persisted to disk. Each task is a JSON file with status, dependencies (`blockedBy`), and dependents (`blocks`). The graph answers three questions at any moment: what is ready, what is blocked, and what is done.\n\n```\n.tasks/\n  task_1.json  {\"id\":1, \"status\":\"completed\"}\n  task_2.json  {\"id\":2, \"blockedBy\":[1], \"status\":\"pending\"}\n  task_3.json  {\"id\":3, \"blockedBy\":[1], \"status\":\"pending\"}\n  task_4.json  {\"id\":4, \"blockedBy\":[2,3], \"status\":\"pending\"}\n\nTask graph (DAG):\n                 +----------+\n            +--> | task 2   | --+\n            |    | pending  |   |\n+----------+     +----------+    +--> +----------+\n| task 1   |                          | task 4   |\n| completed| --> +----------+    +--> | blocked  |\n+----------+     | task 3   | --+     +----------+\n                 | pending  |\n                 +----------+\n\nOrdering:     task 1 must finish before 2 and 3\nParallelism:  tasks 2 and 3 can run at the same time\nDependencies: task 4 waits for both 2 and 3\nStatus:       pending -> in_progress -> completed\n```\n\nThe structure above is a DAG -- a directed acyclic graph, meaning tasks flow forward and never loop back. This task graph becomes the coordination backbone for the later chapters: background execution (s13), agent teams (s15+), and worktree isolation (s18) all build on the same durable task structure.\n\n## How It Works\n\n**Step 1.** Create a `TaskManager` that stores one JSON file per task, with CRUD operations and a dependency graph.\n\n```python\nclass TaskManager:\n    def __init__(self, tasks_dir: Path):\n        self.dir = tasks_dir\n        self.dir.mkdir(exist_ok=True)\n        self._next_id = self._max_id() + 1\n\n    def create(self, subject, description=\"\"):\n        task = {\"id\": self._next_id, \"subject\": subject,\n                \"status\": \"pending\", \"blockedBy\": [],\n                \"blocks\": [], \"owner\": \"\"}\n        self._save(task)\n        self._next_id += 1\n        return json.dumps(task, indent=2)\n```\n\n**Step 2.** Implement dependency resolution. When a task completes, clear its ID from every other task's `blockedBy` list, automatically unblocking dependents.\n\n```python\ndef _clear_dependency(self, completed_id):\n    for f in self.dir.glob(\"task_*.json\"):\n        task = json.loads(f.read_text())\n        if completed_id in task.get(\"blockedBy\", []):\n            task[\"blockedBy\"].remove(completed_id)\n            self._save(task)\n```\n\n**Step 3.** Wire up status transitions and dependency edges in the `update` method. When a task's status changes to `completed`, the dependency-clearing logic from Step 2 fires automatically.\n\n```python\ndef update(self, task_id, status=None,\n           add_blocked_by=None, add_blocks=None):\n    task = self._load(task_id)\n    if status:\n        task[\"status\"] = status\n        if status == \"completed\":\n            self._clear_dependency(task_id)\n    self._save(task)\n```\n\n**Step 4.** Register four task tools in the dispatch map, giving the agent full control over creating, updating, listing, and inspecting tasks.\n\n```python\nTOOL_HANDLERS = {\n    # ...base tools...\n    \"task_create\": lambda **kw: TASKS.create(kw[\"subject\"]),\n    \"task_update\": lambda **kw: TASKS.update(kw[\"task_id\"], kw.get(\"status\")),\n    \"task_list\":   lambda **kw: TASKS.list_all(),\n    \"task_get\":    lambda **kw: TASKS.get(kw[\"task_id\"]),\n}\n```\n\nFrom s12 onward, the task graph becomes the default for durable multi-step work. s03's Todo remains useful for quick single-session checklists, but anything that needs ordering, parallelism, or persistence belongs here.\n\n## Read Together\n\n- If you are coming straight from s03, revisit [`data-structures.md`](./data-structures.md) to separate `TodoItem` / `PlanState` from `TaskRecord` -- they look similar but serve different purposes.\n- If object boundaries start to blur, reset with [`entity-map.md`](./entity-map.md) before you mix messages, tasks, runtime tasks, and teammates into one layer.\n- If you plan to continue into s13, keep [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) beside this chapter because durable tasks and runtime tasks are the easiest pair to confuse next.\n\n## What Changed\n\n| Component | Before (s06) | After (s12) |\n|---|---|---|\n| Tools | 5 | 8 (`task_create/update/list/get`) |\n| Planning model | Flat checklist (in-memory) | Task graph with dependencies (on disk) |\n| Relationships | None | `blockedBy` + `blocks` edges |\n| Status tracking | Done or not | `pending` -> `in_progress` -> `completed` |\n| Persistence | Lost on compression | Survives compression and restarts |\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s12_task_system.py\n```\n\n1. `Create 3 tasks: \"Setup project\", \"Write code\", \"Write tests\". Make them depend on each other in order.`\n2. `List all tasks and show the dependency graph`\n3. `Complete task 1 and then list tasks to see task 2 unblocked`\n4. `Create a task board for refactoring: parse -> transform -> emit -> test, where transform and emit can run in parallel after parse`\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Build a file-based task graph where each task is a self-contained JSON record\n- Express ordering and parallelism through `blockedBy` and `blocks` dependency edges\n- Implement automatic unblocking when upstream tasks complete\n- Persist planning state so it survives context compression and process restarts\n\n## What's Next\n\nTasks now have structure and live on disk. But every tool call still blocks the main loop -- if a task involves a slow subprocess like `npm install` or `pytest`, the agent sits idle waiting. In s13 you will add background execution so slow work runs in parallel while the agent keeps thinking.\n\n## Key Takeaway\n\n> A task graph with explicit dependencies turns a flat checklist into a coordination structure that knows what is ready, what is blocked, and what can run in parallel.\n"
  },
  {
    "version": "s13",
    "slug": "s13-background-tasks",
    "locale": "en",
    "title": "s13: Background Tasks",
    "kind": "chapter",
    "filename": "s13-background-tasks.md",
    "content": "# s13: Background Tasks\n\n`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > [ s13 ] > s14 > s15 > s16 > s17 > s18 > s19`\n\n## What You'll Learn\n\n- How to run slow commands in background threads while the main loop stays responsive\n- How a thread-safe notification queue delivers results back to the agent\n- How daemon threads keep the process clean on exit\n- How the drain-before-call pattern injects background results at exactly the right moment\n\nYou have a task graph now, and every task can express what it depends on. But there is a practical problem: some tasks involve commands that take minutes. `npm install`, `pytest`, `docker build` -- these block the main loop, and while the agent waits, the user waits too. If the user says \"install dependencies and while that runs, create the config file,\" your agent from s12 does them sequentially because it has no way to start something and come back to it later. This chapter fixes that by adding background execution.\n\n## The Problem\n\nConsider a realistic workflow: the user asks the agent to run a full test suite (which takes 90 seconds) and then set up a configuration file. With a blocking loop, the agent submits the test command, stares at a spinning subprocess for 90 seconds, gets the result, and only then starts the config file. The user watches all of this happen serially. Worse, if there are three slow commands, total wall-clock time is the sum of all three -- even though they could have run in parallel. The agent needs a way to start slow work, give control back to the main loop immediately, and pick up the results later.\n\n## The Solution\n\nKeep the main loop single-threaded, but run slow subprocesses on background daemon threads. When a background command finishes, its result goes into a thread-safe notification queue. Before each LLM call, the main loop drains that queue and injects any completed results into the conversation.\n\n```\nMain thread                Background thread\n+-----------------+        +-----------------+\n| agent loop      |        | subprocess runs |\n| ...             |        | ...             |\n| [LLM call] <---+------- | enqueue(result) |\n|  ^drain queue   |        +-----------------+\n+-----------------+\n\nTimeline:\nAgent --[spawn A]--[spawn B]--[other work]----\n             |          |\n             v          v\n          [A runs]   [B runs]      (parallel)\n             |          |\n             +-- results injected before next LLM call --+\n```\n\n## How It Works\n\n**Step 1.** Create a `BackgroundManager` that tracks running tasks with a thread-safe notification queue. The lock ensures that the main thread and background threads never corrupt the queue simultaneously.\n\n```python\nclass BackgroundManager:\n    def __init__(self):\n        self.tasks = {}\n        self._notification_queue = []\n        self._lock = threading.Lock()\n```\n\n**Step 2.** The `run()` method starts a daemon thread and returns immediately. A daemon thread is one that the Python runtime kills automatically when the main program exits -- you do not need to join it or clean it up.\n\n```python\ndef run(self, command: str) -> str:\n    task_id = str(uuid.uuid4())[:8]\n    self.tasks[task_id] = {\"status\": \"running\", \"command\": command}\n    thread = threading.Thread(\n        target=self._execute, args=(task_id, command), daemon=True)\n    thread.start()\n    return f\"Background task {task_id} started\"\n```\n\n**Step 3.** When the subprocess finishes, the background thread puts its result into the notification queue. The lock makes this safe even if the main thread is draining the queue at the same time.\n\n```python\ndef _execute(self, task_id, command):\n    try:\n        r = subprocess.run(command, shell=True, cwd=WORKDIR,\n            capture_output=True, text=True, timeout=300)\n        output = (r.stdout + r.stderr).strip()[:50000]\n    except subprocess.TimeoutExpired:\n        output = \"Error: Timeout (300s)\"\n    with self._lock:\n        self._notification_queue.append({\n            \"task_id\": task_id, \"result\": output[:500]})\n```\n\n**Step 4.** The agent loop drains notifications before each LLM call. This is the drain-before-call pattern: right before you ask the model to think, sweep up any background results and add them to the conversation so the model sees them in its next turn.\n\n```python\ndef agent_loop(messages: list):\n    while True:\n        notifs = BG.drain_notifications()\n        if notifs:\n            notif_text = \"\\n\".join(\n                f\"[bg:{n['task_id']}] {n['result']}\" for n in notifs)\n            messages.append({\"role\": \"user\",\n                \"content\": f\"<background-results>\\n{notif_text}\\n\"\n                           f\"</background-results>\"})\n            messages.append({\"role\": \"assistant\",\n                \"content\": \"Noted background results.\"})\n        response = client.messages.create(...)\n```\n\nThis teaching demo keeps the core loop single-threaded; only subprocess waiting is parallelized. A production system would typically split background work into several runtime lanes, but starting with one clean pattern makes the mechanics easy to follow.\n\n## Read Together\n\n- If you have not fully separated \"task goal\" from \"running execution slot,\" read [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) first -- it clarifies why a task record and a runtime record are different objects.\n- If you are unsure which state belongs in `RuntimeTaskRecord` and which still belongs on the task board, keep [`data-structures.md`](./data-structures.md) nearby.\n- If background execution starts to feel like \"another main loop,\" go back to [`s02b-tool-execution-runtime.md`](./s02b-tool-execution-runtime.md) and reset the boundary: execution and waiting can run in parallel, but the main loop is still one mainline.\n\n## What Changed\n\n| Component      | Before (s12)     | After (s13)                |\n|----------------|------------------|----------------------------|\n| Tools          | 8                | 6 (base + background_run + check)|\n| Execution      | Blocking only    | Blocking + background threads|\n| Notification   | None             | Queue drained per loop     |\n| Concurrency    | None             | Daemon threads             |\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s13_background_tasks.py\n```\n\n1. `Run \"sleep 5 && echo done\" in the background, then create a file while it runs`\n2. `Start 3 background tasks: \"sleep 2\", \"sleep 4\", \"sleep 6\". Check their status.`\n3. `Run pytest in the background and keep working on other things`\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Run slow subprocesses on daemon threads without blocking the main agent loop\n- Collect results through a thread-safe notification queue\n- Inject background results into the conversation using the drain-before-call pattern\n- Let the agent work on other things while long-running commands finish in parallel\n\n## What's Next\n\nBackground tasks solve the problem of slow work that starts now. But what about work that should start later -- \"run this every night\" or \"remind me in 30 minutes\"? In s14 you will add a cron scheduler that stores future intent and triggers it when the time comes.\n\n## Key Takeaway\n\n> Background execution is a runtime lane, not a second main loop -- slow work runs on daemon threads and feeds results back through a single notification queue.\n"
  },
  {
    "version": null,
    "slug": "s13a-runtime-task-model",
    "locale": "en",
    "title": "s13a: Runtime Task Model",
    "kind": "bridge",
    "filename": "s13a-runtime-task-model.md",
    "content": "# s13a: Runtime Task Model\n\n> **Deep Dive** -- Best read between s12 and s13. It prevents the most common confusion in Stage 3.\n\n### When to Read This\n\nRight after s12 (Task System), before you start s13 (Background Tasks). This note separates two meanings of \"task\" that beginners frequently collapse into one.\n\n---\n\n> This bridge note resolves one confusion that becomes expensive very quickly:\n>\n> **the task in the work graph is not the same thing as the task that is currently running**\n\n## How to Read This with the Mainline\n\nThis note works best between these documents:\n\n- read [`s12-task-system.md`](./s12-task-system.md) first to lock in the durable work graph\n- then read [`s13-background-tasks.md`](./s13-background-tasks.md) to see background execution\n- if the terms begin to blur, you might find it helpful to revisit [`glossary.md`](./glossary.md)\n- if you want the fields to line up exactly, you might find it helpful to revisit [`data-structures.md`](./data-structures.md) and [`entity-map.md`](./entity-map.md)\n\n## Why This Deserves Its Own Bridge Note\n\nThe mainline is still correct:\n\n- `s12` teaches the task system\n- `s13` teaches background tasks\n\nBut without one more bridge layer, you can easily start collapsing two different meanings of \"task\" into one bucket.\n\nFor example:\n\n- a work-graph task such as \"implement auth module\"\n- a background execution such as \"run pytest\"\n- a teammate execution such as \"alice is editing files\"\n\nAll three can be casually called tasks, but they do not live on the same layer.\n\n## Two Very Different Kinds of Task\n\n### 1. Work-graph task\n\nThis is the durable node introduced in `s12`.\n\nIt answers:\n\n- what should be done\n- which work depends on which other work\n- who owns it\n- what the progress status is\n\nIt is best understood as:\n\n> a durable unit of planned work\n\n### 2. Runtime task\n\nThis layer answers:\n\n- what execution unit is alive right now\n- what kind of execution it is\n- whether it is running, completed, failed, or killed\n- where its output lives\n\nIt is best understood as:\n\n> a live execution slot inside the runtime\n\n## The Minimum Mental Model\n\nTreat these as two separate tables:\n\n```text\nwork-graph task\n  - durable\n  - goal and dependency oriented\n  - longer lifecycle\n\nruntime task\n  - execution oriented\n  - output and status oriented\n  - shorter lifecycle\n```\n\nTheir relationship is not \"pick one.\"\n\nIt is:\n\n```text\none work-graph task\n  can spawn\none or more runtime tasks\n```\n\nFor example:\n\n```text\nwork-graph task:\n  \"Implement auth module\"\n\nruntime tasks:\n  1. run tests in the background\n  2. launch a coder teammate\n  3. monitor an external service\n```\n\n## Why the Distinction Matters\n\nIf you do not keep these layers separate, the later chapters start tangling together:\n\n- `s13` background execution blurs into the `s12` task board\n- `s15-s17` teammate work has nowhere clean to attach\n- `s18` worktrees become unclear because you no longer know what layer they belong to\n\nThe shortest correct summary is:\n\n**work-graph tasks manage goals; runtime tasks manage execution**\n\n## Core Records\n\n### 1. `WorkGraphTaskRecord`\n\nThis is the durable task from `s12`.\n\n```python\ntask = {\n    \"id\": 12,\n    \"subject\": \"Implement auth module\",\n    \"status\": \"in_progress\",\n    \"blockedBy\": [],\n    \"blocks\": [13],\n    \"owner\": \"alice\",\n    \"worktree\": \"auth-refactor\",\n}\n```\n\n### 2. `RuntimeTaskState`\n\nA minimal teaching shape can look like this:\n\n```python\nruntime_task = {\n    \"id\": \"b8k2m1qz\",\n    \"type\": \"local_bash\",\n    \"status\": \"running\",\n    \"description\": \"Run pytest\",\n    \"start_time\": 1710000000.0,\n    \"end_time\": None,\n    \"output_file\": \".task_outputs/b8k2m1qz.txt\",\n    \"notified\": False,\n}\n```\n\nThe key fields are:\n\n- `type`: what execution unit this is\n- `status`: whether it is active or terminal\n- `output_file`: where the result is stored\n- `notified`: whether the system already surfaced the result\n\n### 3. `RuntimeTaskType`\n\nYou do not need to implement every type in the teaching repo immediately.\n\nBut you should still know that runtime task is a family, not just one shell command type.\n\nA minimal table:\n\n```text\nlocal_bash\nlocal_agent\nremote_agent\nin_process_teammate\nmonitor\nworkflow\n```\n\n## Minimum Implementation Steps\n\n### Step 1: keep the `s12` task board intact\n\nDo not overload it.\n\n### Step 2: add a separate runtime task manager\n\n```python\nclass RuntimeTaskManager:\n    def __init__(self):\n        self.tasks = {}\n```\n\n### Step 3: create runtime tasks when background work starts\n\n```python\ndef spawn_bash_task(command: str):\n    task_id = new_runtime_id()\n    runtime_tasks[task_id] = {\n        \"id\": task_id,\n        \"type\": \"local_bash\",\n        \"status\": \"running\",\n        \"description\": command,\n    }\n```\n\n### Step 4: optionally link runtime execution back to the work graph\n\n```python\nruntime_tasks[task_id][\"work_graph_task_id\"] = 12\n```\n\nYou do not need that field on day one, but it becomes increasingly important once the system reaches teams and worktrees.\n\n## The Picture You Should Hold\n\n```text\nWork Graph\n  task #12: Implement auth module\n        |\n        +-- runtime task A: local_bash (pytest)\n        +-- runtime task B: local_agent (coder worker)\n        +-- runtime task C: monitor (watch service status)\n\nRuntime Task Layer\n  A/B/C each have:\n  - their own runtime ID\n  - their own status\n  - their own output\n  - their own lifecycle\n```\n\n## How This Connects to Later Chapters\n\nOnce this layer is clear, the rest of the runtime and platform chapters become much easier:\n\n- `s13` background commands are runtime tasks\n- `s15-s17` teammates can also be understood as runtime task variants\n- `s18` worktrees mostly bind to durable work, but still affect runtime execution\n- `s19` some monitoring or async external work can also land in the runtime layer\n\nWhenever you see \"something is alive in the background and advancing work,\" ask two questions:\n\n- is this a durable goal from the work graph?\n- or is this a live execution slot in the runtime?\n\n## Common Beginner Mistakes\n\n### 1. Putting background shell state directly into the task board\n\nThat mixes durable task state and runtime execution state.\n\n### 2. Assuming one work-graph task can only have one runtime task\n\nIn real systems, one goal often spawns multiple execution units.\n\n### 3. Reusing the same status vocabulary for both layers\n\nFor example:\n\n- durable tasks: `pending / in_progress / completed`\n- runtime tasks: `running / completed / failed / killed`\n\nThose should stay distinct when possible.\n\n### 4. Ignoring runtime-only fields such as `output_file` and `notified`\n\nThe durable task board does not care much about them.\nThe runtime layer cares a lot.\n\n## Key Takeaway\n\n**\"Task\" means two different things: a durable goal in the work graph (what should be done) and a live execution slot in the runtime (what is running right now). Keep them on separate layers.**\n"
  },
  {
    "version": "s14",
    "slug": "s14-cron-scheduler",
    "locale": "en",
    "title": "s14: Cron Scheduler",
    "kind": "chapter",
    "filename": "s14-cron-scheduler.md",
    "content": "# s14: Cron Scheduler\n\n`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > [ s14 ] > s15 > s16 > s17 > s18 > s19`\n\n## What You'll Learn\n\n- How schedule records store future intent as durable data\n- How a time-based checker turns cron expressions into triggered notifications\n- The difference between durable jobs (survive restarts) and session-only jobs (die with the process)\n- How scheduled work re-enters the agent system through the same notification queue from s13\n\nIn s13 you learned to run slow work in the background so the agent does not block. But that work still starts immediately -- the user says \"run this\" and it runs now. Real workflows often need work that starts later: \"run this every night,\" \"generate the report every Monday morning,\" \"remind me to check this again in 30 minutes.\" Without scheduling, the user has to re-issue the same request every time. This chapter adds one new idea: store future intent now, trigger it later. And it closes out Stage 3 by completing the progression from durable tasks (s12) to background execution (s13) to time-based triggers (s14).\n\n## The Problem\n\nYour agent can now manage a task graph and run commands in the background. But every piece of work begins with the user explicitly asking for it. If the user wants a nightly test run, they have to remember to type \"run the tests\" every evening. If they want a weekly status report, they have to open a session every Monday morning. The agent has no concept of future time -- it reacts to what you say right now, and it cannot act on something you want to happen tomorrow. You need a way to record \"do X at time Y\" and have the system trigger it automatically.\n\n## The Solution\n\nAdd three moving parts: schedule records that describe when and what, a time checker that runs in the background and tests whether any schedule matches the current time, and the same notification queue from s13 to feed triggered work back into the main loop.\n\n```text\nschedule_create(...)\n  ->\nwrite a durable schedule record\n  ->\ntime checker wakes up and tests \"does this rule match now?\"\n  ->\nif yes, enqueue a scheduled notification\n  ->\nmain loop injects that notification as new work\n```\n\nThe key insight is that the scheduler is not a second agent loop. It feeds triggered prompts into the same system the agent already uses. The main loop does not know or care whether a piece of work came from the user typing it or from a cron trigger -- it processes both the same way.\n\n## How It Works\n\n**Step 1.** Define the schedule record. Each job stores a cron expression (a compact time-matching syntax like `0 9 * * 1` meaning \"9:00 AM every Monday\"), the prompt to execute, whether it recurs or fires once, and a `last_fired_at` timestamp to prevent double-firing.\n\n```python\nschedule = {\n    \"id\": \"job_001\",\n    \"cron\": \"0 9 * * 1\",\n    \"prompt\": \"Run the weekly status report.\",\n    \"recurring\": True,\n    \"durable\": True,\n    \"created_at\": 1710000000.0,\n    \"last_fired_at\": None,\n}\n```\n\nA durable job is written to disk and survives process restarts. A session-only job lives in memory and dies when the agent exits. One-shot jobs (`recurring: False`) fire once and then delete themselves.\n\n**Step 2.** Create a schedule through a tool call. The method stores the record and returns it so the model can confirm what was scheduled.\n\n```python\ndef create(self, cron_expr: str, prompt: str, recurring: bool = True):\n    job = {\n        \"id\": new_id(),\n        \"cron\": cron_expr,\n        \"prompt\": prompt,\n        \"recurring\": recurring,\n        \"created_at\": time.time(),\n        \"last_fired_at\": None,\n    }\n    self.jobs.append(job)\n    return job\n```\n\n**Step 3.** Run a background checker loop that wakes up every 60 seconds and tests each schedule against the current time.\n\n```python\ndef check_loop(self):\n    while True:\n        now = datetime.now()\n        self.check_jobs(now)\n        time.sleep(60)\n```\n\n**Step 4.** When a schedule matches, enqueue a notification. The `last_fired_at` field is updated to prevent the same minute from triggering the job twice.\n\n```python\ndef check_jobs(self, now):\n    for job in self.jobs:\n        if cron_matches(job[\"cron\"], now):\n            self.queue.put({\n                \"type\": \"scheduled_prompt\",\n                \"schedule_id\": job[\"id\"],\n                \"prompt\": job[\"prompt\"],\n            })\n            job[\"last_fired_at\"] = now.timestamp()\n```\n\n**Step 5.** Feed scheduled notifications back into the main loop using the same drain pattern from s13. From the agent's perspective, a scheduled prompt looks just like a user message.\n\n```python\nnotifications = scheduler.drain()\nfor item in notifications:\n    messages.append({\n        \"role\": \"user\",\n        \"content\": f\"[scheduled:{item['schedule_id']}] {item['prompt']}\",\n    })\n```\n\n## Read Together\n\n- If `schedule`, `task`, and `runtime task` still feel like the same object, reread [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) -- it draws the boundary between planning records, execution records, and schedule records.\n- If you want to see how one trigger eventually returns to the mainline, pair this chapter with [`s00b-one-request-lifecycle.md`](./s00b-one-request-lifecycle.md).\n- If future triggers start to feel like a whole second execution system, reset with [`data-structures.md`](./data-structures.md) and separate schedule records from runtime records.\n\n## What Changed\n\n| Mechanism | Main question |\n|---|---|\n| Background tasks (s13) | \"How does slow work continue without blocking?\" |\n| Scheduling (s14) | \"When should future work begin?\" |\n\n| Component | Before (s13) | After (s14) |\n|---|---|---|\n| Tools | 6 (base + background) | 8 (+ schedule_create, schedule_list, schedule_delete) |\n| Time awareness | None | Cron-based future triggers |\n| Persistence | Background tasks in memory | Durable schedules survive restarts |\n| Trigger model | User-initiated only | User-initiated + time-triggered |\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s14_cron_scheduler.py\n```\n\n1. Create a repeating schedule: `Schedule \"echo hello\" to run every 2 minutes`\n2. Create a one-shot reminder: `Remind me in 1 minute to check the build`\n3. Create a delayed follow-up: `In 5 minutes, run the test suite and report results`\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Define schedule records that store future intent as durable data\n- Run a background time checker that matches cron expressions to the current clock\n- Distinguish durable jobs (persist to disk) from session-only jobs (in-memory)\n- Feed scheduled triggers back into the main loop through the same notification queue used by background tasks\n- Prevent double-firing with `last_fired_at` tracking\n\n## Stage 3 Complete\n\nYou have finished Stage 3: the execution and scheduling layer. Looking back at the three chapters together:\n\n- **s12** gave the agent a task graph with dependencies and persistence -- it can plan structured work that survives restarts.\n- **s13** added background execution -- slow work runs in parallel instead of blocking the loop.\n- **s14** added time-based triggers -- the agent can schedule future work without the user having to remember.\n\nTogether, these three chapters transform the agent from something that only reacts to what you type right now into something that can plan ahead, work in parallel, and act on its own schedule. In Stage 4 (s15-s18), you will use this foundation to coordinate multiple agents working as a team.\n\n## Key Takeaway\n\n> A scheduler stores future intent as a record, checks it against the clock in a background loop, and feeds triggered work back into the same agent system -- no second loop needed.\n"
  },
  {
    "version": "s15",
    "slug": "s15-agent-teams",
    "locale": "en",
    "title": "s15: Agent Teams",
    "kind": "chapter",
    "filename": "s15-agent-teams.md",
    "content": "# s15: Agent Teams\n\n`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > [ s15 ] > s16 > s17 > s18 > s19`\n\n## What You'll Learn\n- How persistent teammates differ from disposable subagents\n- How JSONL-based inboxes give agents a durable communication channel\n- How the team lifecycle moves through spawn, working, idle, and shutdown\n- How file-based coordination lets multiple agent loops run side by side\n\nSometimes one agent is not enough. A complex project -- say, building a feature that involves frontend, backend, and tests -- needs multiple workers running in parallel, each with its own identity and memory. In this chapter you will build a team system where agents persist beyond a single prompt, communicate through file-based mailboxes, and coordinate without sharing a single conversation thread.\n\n## The Problem\n\nSubagents from s04 are disposable: you spawn one, it works, it returns a summary, and it dies. It has no identity and no memory between invocations. Background tasks from s13 can keep work running in the background, but they are not persistent teammates making their own LLM-guided decisions.\n\nReal teamwork needs three things: (1) persistent agents that outlive a single prompt, (2) identity and lifecycle management so you know who is doing what, and (3) a communication channel between agents so they can exchange information without the lead manually relaying every message.\n\n## The Solution\n\nThe harness maintains a team roster in a shared config file and gives each teammate an append-only JSONL inbox. When one agent sends a message to another, it simply appends a JSON line to the recipient's inbox file. The recipient drains that file before every LLM call.\n\n```\nTeammate lifecycle:\n  spawn -> WORKING -> IDLE -> WORKING -> ... -> SHUTDOWN\n\nCommunication:\n  .team/\n    config.json           <- team roster + statuses\n    inbox/\n      alice.jsonl         <- append-only, drain-on-read\n      bob.jsonl\n      lead.jsonl\n\n              +--------+    send(\"alice\",\"bob\",\"...\")    +--------+\n              | alice  | -----------------------------> |  bob   |\n              | loop   |    bob.jsonl << {json_line}    |  loop  |\n              +--------+                                +--------+\n                   ^                                         |\n                   |        BUS.read_inbox(\"alice\")          |\n                   +---- alice.jsonl -> read + drain ---------+\n```\n\n## How It Works\n\n**Step 1.** `TeammateManager` maintains `config.json` with the team roster. It tracks every teammate's name, role, and current status.\n\n```python\nclass TeammateManager:\n    def __init__(self, team_dir: Path):\n        self.dir = team_dir\n        self.dir.mkdir(exist_ok=True)\n        self.config_path = self.dir / \"config.json\"\n        self.config = self._load_config()\n        self.threads = {}\n```\n\n**Step 2.** `spawn()` creates a teammate entry in the roster and starts its agent loop in a separate thread. From this point on, the teammate runs independently -- it has its own conversation history, its own tool calls, and its own LLM interactions.\n\n```python\ndef spawn(self, name: str, role: str, prompt: str) -> str:\n    member = {\"name\": name, \"role\": role, \"status\": \"working\"}\n    self.config[\"members\"].append(member)\n    self._save_config()\n    thread = threading.Thread(\n        target=self._teammate_loop,\n        args=(name, role, prompt), daemon=True)\n    thread.start()\n    return f\"Spawned teammate '{name}' (role: {role})\"\n```\n\n**Step 3.** `MessageBus` provides append-only JSONL inboxes. `send()` appends a single JSON line to the recipient's file; `read_inbox()` reads all accumulated messages and then empties the file (\"drains\" it). The storage format is intentionally simple -- the teaching focus here is the mailbox boundary, not storage cleverness.\n\n```python\nclass MessageBus:\n    def send(self, sender, to, content, msg_type=\"message\", extra=None):\n        msg = {\"type\": msg_type, \"from\": sender,\n               \"content\": content, \"timestamp\": time.time()}\n        if extra:\n            msg.update(extra)\n        with open(self.dir / f\"{to}.jsonl\", \"a\") as f:\n            f.write(json.dumps(msg) + \"\\n\")\n\n    def read_inbox(self, name):\n        path = self.dir / f\"{name}.jsonl\"\n        if not path.exists(): return \"[]\"\n        msgs = [json.loads(l) for l in path.read_text().strip().splitlines() if l]\n        path.write_text(\"\")  # drain\n        return json.dumps(msgs, indent=2)\n```\n\n**Step 4.** Each teammate checks its inbox before every LLM call. Any received messages get injected into the conversation context so the model can see and respond to them.\n\n```python\ndef _teammate_loop(self, name, role, prompt):\n    messages = [{\"role\": \"user\", \"content\": prompt}]\n    for _ in range(50):\n        inbox = BUS.read_inbox(name)\n        if inbox != \"[]\":\n            messages.append({\"role\": \"user\",\n                \"content\": f\"<inbox>{inbox}</inbox>\"})\n            messages.append({\"role\": \"assistant\",\n                \"content\": \"Noted inbox messages.\"})\n        response = client.messages.create(...)\n        if response.stop_reason != \"tool_use\":\n            break\n        # execute tools, append results...\n    self._find_member(name)[\"status\"] = \"idle\"\n```\n\n## Read Together\n\n- If you still treat a teammate like s04's disposable subagent, revisit [`entity-map.md`](./entity-map.md) to see how they differ.\n- If you plan to continue into s16-s18, keep [`team-task-lane-model.md`](./team-task-lane-model.md) open -- it separates teammate, protocol request, task, runtime slot, and worktree lane into distinct concepts.\n- If you are unsure how a long-lived teammate differs from a live runtime slot, pair this chapter with [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md).\n\n## How It Plugs Into The Earlier System\n\nThis chapter is not just \"more model calls.\" It adds durable executors on top of work structures you already built in s12-s14.\n\n```text\nlead identifies work that needs a long-lived worker\n  ->\nspawn teammate\n  ->\nwrite roster entry in .team/config.json\n  ->\nsend inbox message / task hint\n  ->\nteammate drains inbox before its next loop\n  ->\nteammate runs its own agent loop and tools\n  ->\nresult returns through team messages or task updates\n```\n\nKeep the boundary straight:\n\n- s12-s14 gave you tasks, runtime slots, and schedules\n- s15 adds durable named workers\n- s15 is still mostly lead-assigned work\n- structured protocols arrive in s16\n- autonomous claiming arrives in s17\n\n## Teammate vs Subagent vs Runtime Slot\n\n| Mechanism | Think of it as | Lifecycle | Main boundary |\n|---|---|---|---|\n| subagent | a disposable helper | spawn -> work -> summary -> gone | isolates one exploratory branch |\n| runtime slot | a live execution slot | exists while background work is running | tracks long-running execution, not identity |\n| teammate | a durable worker | can go idle, resume, and keep receiving work | has a name, inbox, and independent loop |\n\n## What Changed From s14\n\n| Component      | Before (s14)     | After (s15)                |\n|----------------|------------------|----------------------------|\n| Tools          | 6                | 9 (+spawn/send/read_inbox) |\n| Agents         | Single           | Lead + N teammates         |\n| Persistence    | None             | config.json + JSONL inboxes|\n| Threads        | Background cmds  | Full agent loops per thread|\n| Lifecycle      | Fire-and-forget  | idle -> working -> idle    |\n| Communication  | None             | message + broadcast        |\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s15_agent_teams.py\n```\n\n1. `Spawn alice (coder) and bob (tester). Have alice send bob a message.`\n2. `Broadcast \"status update: phase 1 complete\" to all teammates`\n3. `Check the lead inbox for any messages`\n4. Type `/team` to see the team roster with statuses\n5. Type `/inbox` to manually check the lead's inbox\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Spawn persistent teammates that each run their own independent agent loop\n- Send messages between agents through durable JSONL inboxes\n- Track teammate status through a shared config file\n- Coordinate multiple agents without funneling everything through a single conversation\n\n## What's Next\n\nYour teammates can now communicate freely, but they lack coordination rules. What happens when you need to shut a teammate down cleanly, or review a risky plan before it executes? In s16, you will add structured protocols -- request-response handshakes that bring order to multi-agent negotiation.\n\n## Key Takeaway\n\n> Teammates persist beyond one prompt, each with identity, lifecycle, and a durable mailbox -- coordination is no longer limited to a single parent loop.\n"
  },
  {
    "version": "s16",
    "slug": "s16-team-protocols",
    "locale": "en",
    "title": "s16: Team Protocols",
    "kind": "chapter",
    "filename": "s16-team-protocols.md",
    "content": "# s16: Team Protocols\n\n`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > [ s16 ] > s17 > s18 > s19`\n\n## What You'll Learn\n- How a request-response pattern with a tracking ID structures multi-agent negotiation\n- How the shutdown protocol lets a lead gracefully stop a teammate\n- How plan approval gates risky work behind a review step\n- How one reusable FSM (a simple status tracker with defined transitions) covers both protocols\n\nIn s15 your teammates can send messages freely, but that freedom comes with chaos. One agent tells another \"please stop,\" and the other ignores it. A teammate starts a risky database migration without asking first. The problem is not communication itself -- you solved that with inboxes -- but the lack of coordination rules. In this chapter you will add structured protocols: a standardized message wrapper with a tracking ID that turns loose messages into reliable handshakes.\n\n## The Problem\n\nTwo coordination gaps become obvious once your team grows past toy examples:\n\n**Shutdown.** Killing a teammate's thread leaves files half-written and the config roster stale. You need a handshake: the lead requests shutdown, and the teammate approves (finishes current work and exits cleanly) or rejects (keeps working because it has unfinished obligations).\n\n**Plan approval.** When the lead says \"refactor the auth module,\" the teammate starts immediately. But for high-risk changes, the lead should review the plan before any code gets written.\n\nBoth scenarios share an identical structure: one side sends a request carrying a unique ID, the other side responds referencing that same ID. That single pattern is enough to build any coordination protocol you need.\n\n## The Solution\n\nBoth shutdown and plan approval follow one shape: send a request with a `request_id`, receive a response referencing that same `request_id`, and track the outcome through a simple status machine (`pending -> approved` or `pending -> rejected`).\n\n```\nShutdown Protocol            Plan Approval Protocol\n==================           ======================\n\nLead             Teammate    Teammate           Lead\n  |                 |           |                 |\n  |--shutdown_req-->|           |--plan_req------>|\n  | {req_id:\"abc\"}  |           | {req_id:\"xyz\"}  |\n  |                 |           |                 |\n  |<--shutdown_resp-|           |<--plan_resp-----|\n  | {req_id:\"abc\",  |           | {req_id:\"xyz\",  |\n  |  approve:true}  |           |  approve:true}  |\n\nShared FSM:\n  [pending] --approve--> [approved]\n  [pending] --reject---> [rejected]\n\nTrackers:\n  shutdown_requests = {req_id: {target, status}}\n  plan_requests     = {req_id: {from, plan, status}}\n```\n\n## How It Works\n\n**Step 1.** The lead initiates shutdown by generating a unique `request_id` and sending the request through the teammate's inbox. The request is tracked in a dictionary so the lead can check its status later.\n\n```python\nshutdown_requests = {}\n\ndef handle_shutdown_request(teammate: str) -> str:\n    req_id = str(uuid.uuid4())[:8]\n    shutdown_requests[req_id] = {\"target\": teammate, \"status\": \"pending\"}\n    BUS.send(\"lead\", teammate, \"Please shut down gracefully.\",\n             \"shutdown_request\", {\"request_id\": req_id})\n    return f\"Shutdown request {req_id} sent (status: pending)\"\n```\n\n**Step 2.** The teammate receives the request in its inbox and responds with approve or reject. The response carries the same `request_id` so the lead can match it to the original request -- this is the correlation that makes the protocol reliable.\n\n```python\nif tool_name == \"shutdown_response\":\n    req_id = args[\"request_id\"]\n    approve = args[\"approve\"]\n    shutdown_requests[req_id][\"status\"] = \"approved\" if approve else \"rejected\"\n    BUS.send(sender, \"lead\", args.get(\"reason\", \"\"),\n             \"shutdown_response\",\n             {\"request_id\": req_id, \"approve\": approve})\n```\n\n**Step 3.** Plan approval follows the identical pattern but in the opposite direction. The teammate submits a plan (generating a `request_id`), and the lead reviews it (referencing the same `request_id` to approve or reject).\n\n```python\nplan_requests = {}\n\ndef handle_plan_review(request_id, approve, feedback=\"\"):\n    req = plan_requests[request_id]\n    req[\"status\"] = \"approved\" if approve else \"rejected\"\n    BUS.send(\"lead\", req[\"from\"], feedback,\n             \"plan_approval_response\",\n             {\"request_id\": request_id, \"approve\": approve})\n```\n\nIn this teaching demo, one FSM shape covers both protocols. A production system might treat different protocol families differently, but the teaching version intentionally keeps one reusable template so you can see the shared structure clearly.\n\n## Read Together\n\n- If plain messages and protocol requests are starting to blur together, revisit [`glossary.md`](./glossary.md) and [`entity-map.md`](./entity-map.md) to see how they differ.\n- If you plan to continue into s17 and s18, read [`team-task-lane-model.md`](./team-task-lane-model.md) first so autonomy and worktree lanes do not collapse into one idea.\n- If you want to trace how a protocol request returns to the main system, pair this chapter with [`s00b-one-request-lifecycle.md`](./s00b-one-request-lifecycle.md).\n\n## How It Plugs Into The Team System\n\nThe real upgrade in s16 is not \"two new message types.\" It is a durable coordination path:\n\n```text\nrequester starts a protocol action\n  ->\nwrite RequestRecord\n  ->\nsend ProtocolEnvelope through inbox\n  ->\nreceiver drains inbox on its next loop\n  ->\nupdate request status by request_id\n  ->\nsend structured response\n  ->\nrequester continues based on approved / rejected\n```\n\nThat is the missing layer between \"agents can chat\" and \"agents can coordinate reliably.\"\n\n## Message vs Protocol vs Request vs Task\n\n| Object | What question it answers | Typical fields |\n|---|---|---|\n| `MessageEnvelope` | who said what to whom | `from`, `to`, `content` |\n| `ProtocolEnvelope` | is this a structured request / response | `type`, `request_id`, `payload` |\n| `RequestRecord` | where is this coordination flow now | `kind`, `status`, `from`, `to` |\n| `TaskRecord` | what actual work item is being advanced | `subject`, `status`, `blockedBy`, `owner` |\n\nDo not collapse them:\n\n- a protocol request is not the task itself\n- the request store is not the task board\n- protocols track coordination flow\n- tasks track work progression\n\n## What Changed From s15\n\n| Component      | Before (s15)     | After (s16)                  |\n|----------------|------------------|------------------------------|\n| Tools          | 9                | 12 (+shutdown_req/resp +plan)|\n| Shutdown       | Natural exit only| Request-response handshake   |\n| Plan gating    | None             | Submit/review with approval  |\n| Correlation    | None             | request_id per request       |\n| FSM            | None             | pending -> approved/rejected |\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s16_team_protocols.py\n```\n\n1. `Spawn alice as a coder. Then request her shutdown.`\n2. `List teammates to see alice's status after shutdown approval`\n3. `Spawn bob with a risky refactoring task. Review and reject his plan.`\n4. `Spawn charlie, have him submit a plan, then approve it.`\n5. Type `/team` to monitor statuses\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Build request-response protocols that use a unique ID for correlation\n- Implement graceful shutdown through a two-step handshake\n- Gate risky work behind a plan approval step\n- Reuse a single FSM pattern (`pending -> approved/rejected`) for any new protocol you invent\n\n## What's Next\n\nYour team now has structure and rules, but the lead still has to babysit every teammate -- assigning tasks one by one, nudging idle workers. In s17, you will make teammates autonomous: they scan the task board themselves, claim unclaimed work, and resume after context compression without losing their identity.\n\n## Key Takeaway\n\n> A protocol request is a structured message with a tracking ID, and the response must reference that same ID -- that single pattern is enough to build any coordination handshake.\n"
  },
  {
    "version": "s17",
    "slug": "s17-autonomous-agents",
    "locale": "en",
    "title": "s17: Autonomous Agents",
    "kind": "chapter",
    "filename": "s17-autonomous-agents.md",
    "content": "# s17: Autonomous Agents\n\n`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > [ s17 ] > s18 > s19`\n\n## What You'll Learn\n- How idle polling lets a teammate find new work without being told\n- How auto-claim turns the task board into a self-service work queue\n- How identity re-injection restores a teammate's sense of self after context compression\n- How a timeout-based shutdown prevents idle agents from running forever\n\nManual assignment does not scale. With ten unclaimed tasks on the board, the lead has to pick one, find an idle teammate, craft a prompt, and hand it off -- ten times. The lead becomes a bottleneck, spending more time dispatching than thinking. In this chapter you will remove that bottleneck by making teammates autonomous: they scan the task board themselves, claim unclaimed work, and shut down gracefully when there is nothing left to do.\n\n## The Problem\n\nIn s15-s16, teammates only work when explicitly told to. The lead must spawn each one with a specific prompt. If ten tasks sit unclaimed on the board, the lead assigns each one manually. This creates a coordination bottleneck that gets worse as the team grows.\n\nTrue autonomy means teammates scan the task board themselves, claim unclaimed tasks, work on them, then look for more -- all without the lead lifting a finger.\n\nOne subtlety makes this harder than it sounds: after context compression (which you built in s06), an agent's conversation history gets truncated. The agent might forget who it is. Identity re-injection fixes this by restoring the agent's name and role when its context gets too short.\n\n## The Solution\n\nEach teammate alternates between two phases: WORK (calling the LLM and executing tools) and IDLE (polling for new messages or unclaimed tasks). If the idle phase times out with nothing to do, the teammate shuts itself down.\n\n```\nTeammate lifecycle with idle cycle:\n\n+-------+\n| spawn |\n+---+---+\n    |\n    v\n+-------+   tool_use     +-------+\n| WORK  | <------------- |  LLM  |\n+---+---+                +-------+\n    |\n    | stop_reason != tool_use (or idle tool called)\n    v\n+--------+\n|  IDLE  |  poll every 5s for up to 60s\n+---+----+\n    |\n    +---> check inbox --> message? ----------> WORK\n    |\n    +---> scan .tasks/ --> unclaimed? -------> claim -> WORK\n    |\n    +---> 60s timeout ----------------------> SHUTDOWN\n\nIdentity re-injection after compression:\n  if len(messages) <= 3:\n    messages.insert(0, identity_block)\n```\n\n## How It Works\n\n**Step 1.** The teammate loop has two phases: WORK and IDLE. During the work phase, the teammate calls the LLM repeatedly and executes tools. When the LLM stops calling tools (or the teammate explicitly calls the `idle` tool), it transitions to the idle phase.\n\n```python\ndef _loop(self, name, role, prompt):\n    while True:\n        # -- WORK PHASE --\n        messages = [{\"role\": \"user\", \"content\": prompt}]\n        for _ in range(50):\n            response = client.messages.create(...)\n            if response.stop_reason != \"tool_use\":\n                break\n            # execute tools...\n            if idle_requested:\n                break\n\n        # -- IDLE PHASE --\n        self._set_status(name, \"idle\")\n        resume = self._idle_poll(name, messages)\n        if not resume:\n            self._set_status(name, \"shutdown\")\n            return\n        self._set_status(name, \"working\")\n```\n\n**Step 2.** The idle phase polls for two things in a loop: inbox messages and unclaimed tasks. It checks every 5 seconds for up to 60 seconds. If a message arrives, the teammate wakes up. If an unclaimed task appears on the board, the teammate claims it and gets back to work. If neither happens within the timeout window, the teammate shuts itself down.\n\n```python\ndef _idle_poll(self, name, messages):\n    for _ in range(IDLE_TIMEOUT // POLL_INTERVAL):  # 60s / 5s = 12\n        time.sleep(POLL_INTERVAL)\n        inbox = BUS.read_inbox(name)\n        if inbox:\n            messages.append({\"role\": \"user\",\n                \"content\": f\"<inbox>{inbox}</inbox>\"})\n            return True\n        unclaimed = scan_unclaimed_tasks()\n        if unclaimed:\n            claim_task(unclaimed[0][\"id\"], name)\n            messages.append({\"role\": \"user\",\n                \"content\": f\"<auto-claimed>Task #{unclaimed[0]['id']}: \"\n                           f\"{unclaimed[0]['subject']}</auto-claimed>\"})\n            return True\n    return False  # timeout -> shutdown\n```\n\n**Step 3.** Task board scanning finds pending, unowned, unblocked tasks. The scan reads task files from disk and filters for tasks that are available to claim -- no owner, no blocking dependencies, and still in `pending` status.\n\n```python\ndef scan_unclaimed_tasks() -> list:\n    unclaimed = []\n    for f in sorted(TASKS_DIR.glob(\"task_*.json\")):\n        task = json.loads(f.read_text())\n        if (task.get(\"status\") == \"pending\"\n                and not task.get(\"owner\")\n                and not task.get(\"blockedBy\")):\n            unclaimed.append(task)\n    return unclaimed\n```\n\n**Step 4.** Identity re-injection handles a subtle problem. After context compression (s06), the conversation history might shrink to just a few messages -- and the agent forgets who it is. When the message list is suspiciously short (3 or fewer messages), the harness inserts an identity block at the beginning so the agent knows its name, role, and team.\n\n```python\nif len(messages) <= 3:\n    messages.insert(0, {\"role\": \"user\",\n        \"content\": f\"<identity>You are '{name}', role: {role}, \"\n                   f\"team: {team_name}. Continue your work.</identity>\"})\n    messages.insert(1, {\"role\": \"assistant\",\n        \"content\": f\"I am {name}. Continuing.\"})\n```\n\n## Read Together\n\n- If teammate, task, and runtime slot are starting to blur into one layer, revisit [`team-task-lane-model.md`](./team-task-lane-model.md) to separate them clearly.\n- If auto-claim makes you wonder where the live execution slot actually lives, keep [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) nearby.\n- If you are starting to forget the core difference between a persistent teammate and a one-shot subagent, revisit [`entity-map.md`](./entity-map.md).\n\n## What Changed From s16\n\n| Component      | Before (s16)     | After (s17)                |\n|----------------|------------------|----------------------------|\n| Tools          | 12               | 14 (+idle, +claim_task)    |\n| Autonomy       | Lead-directed    | Self-organizing            |\n| Idle phase     | None             | Poll inbox + task board    |\n| Task claiming  | Manual only      | Auto-claim unclaimed tasks |\n| Identity       | System prompt    | + re-injection after compress|\n| Timeout        | None             | 60s idle -> auto shutdown  |\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s17_autonomous_agents.py\n```\n\n1. `Create 3 tasks on the board, then spawn alice and bob. Watch them auto-claim.`\n2. `Spawn a coder teammate and let it find work from the task board itself`\n3. `Create tasks with dependencies. Watch teammates respect the blocked order.`\n4. Type `/tasks` to see the task board with owners\n5. Type `/team` to monitor who is working vs idle\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Build teammates that find and claim work from a shared task board without lead intervention\n- Implement an idle polling loop that balances responsiveness with resource efficiency\n- Restore agent identity after context compression so long-running teammates stay coherent\n- Use timeout-based shutdown to prevent abandoned agents from running indefinitely\n\n## What's Next\n\nYour teammates now organize themselves, but they all share the same working directory. When two agents edit the same file at the same time, things break. In s18, you will give each teammate its own isolated worktree -- a separate copy of the codebase where it can work without stepping on anyone else's changes.\n\n## Key Takeaway\n\n> Autonomous teammates scan the task board, claim unclaimed work, and shut down when idle -- removing the lead as a coordination bottleneck.\n"
  },
  {
    "version": "s18",
    "slug": "s18-worktree-task-isolation",
    "locale": "en",
    "title": "s18: Worktree + Task Isolation",
    "kind": "chapter",
    "filename": "s18-worktree-task-isolation.md",
    "content": "# s18: Worktree + Task Isolation\n\n`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > [ s18 ] > s19`\n\n## What You'll Learn\n- How git worktrees (isolated copies of your project directory, managed by git) prevent file conflicts between parallel agents\n- How to bind a task to a dedicated worktree so that \"what to do\" and \"where to do it\" stay cleanly separated\n- How lifecycle events give you an observable record of every create, keep, and remove action\n- How parallel execution lanes let multiple agents work on different tasks without ever stepping on each other's files\n\nWhen two agents both need to edit the same codebase at the same time, you have a problem. Everything you have built so far -- task boards, autonomous agents, team protocols -- assumes that agents work in a single shared directory. That works fine until it does not. This chapter gives every task its own directory, so parallel work stays parallel.\n\n## The Problem\n\nBy s17, your agents can claim tasks, coordinate through team protocols, and complete work autonomously. But all of them run in the same project directory. Imagine agent A is refactoring the authentication module, and agent B is building a new login page. Both need to touch `config.py`. Agent A stages its changes, agent B stages different changes to the same file, and now you have a tangled mess of unstaged edits that neither agent can roll back cleanly.\n\nThe task board tracks *what to do* but has no opinion about *where to do it*. You need a way to give each task its own isolated working directory, so that file-level operations never collide. The fix is straightforward: pair each task with a git worktree -- a separate checkout of the same repository on its own branch. Tasks manage goals; worktrees manage execution context. Bind them by task ID.\n\n## Read Together\n\n- If task, runtime slot, and worktree lane are blurring together in your head, [`team-task-lane-model.md`](./team-task-lane-model.md) separates them clearly.\n- If you want to confirm which fields belong on task records versus worktree records, [`data-structures.md`](./data-structures.md) has the full schema.\n- If you want to see why this chapter comes after tasks and teams in the overall curriculum, [`s00e-reference-module-map.md`](./s00e-reference-module-map.md) has the ordering rationale.\n\n## The Solution\n\nThe system splits into two planes: a control plane (`.tasks/`) that tracks goals, and an execution plane (`.worktrees/`) that manages isolated directories. Each task points to its worktree by name, and each worktree points back to its task by ID.\n\n```\nControl plane (.tasks/)             Execution plane (.worktrees/)\n+------------------+                +------------------------+\n| task_1.json      |                | auth-refactor/         |\n|   status: in_progress  <------>   branch: wt/auth-refactor\n|   worktree: \"auth-refactor\"   |   task_id: 1             |\n+------------------+                +------------------------+\n| task_2.json      |                | ui-login/              |\n|   status: pending    <------>     branch: wt/ui-login\n|   worktree: \"ui-login\"       |   task_id: 2             |\n+------------------+                +------------------------+\n                                    |\n                          index.json (worktree registry)\n                          events.jsonl (lifecycle log)\n\nState machines:\n  Task:     pending -> in_progress -> completed\n  Worktree: absent  -> active      -> removed | kept\n```\n\n## How It Works\n\n**Step 1.** Create a task. The goal is recorded first, before any directory exists.\n\n```python\nTASKS.create(\"Implement auth refactor\")\n# -> .tasks/task_1.json  status=pending  worktree=\"\"\n```\n\n**Step 2.** Create a worktree and bind it to the task. Passing `task_id` automatically advances the task to `in_progress` -- you do not need to update the status separately.\n\n```python\nWORKTREES.create(\"auth-refactor\", task_id=1)\n# -> git worktree add -b wt/auth-refactor .worktrees/auth-refactor HEAD\n# -> index.json gets new entry, task_1.json gets worktree=\"auth-refactor\"\n```\n\nThe binding writes state to both sides so you can traverse the relationship from either direction:\n\n```python\ndef bind_worktree(self, task_id, worktree):\n    task = self._load(task_id)\n    task[\"worktree\"] = worktree\n    if task[\"status\"] == \"pending\":\n        task[\"status\"] = \"in_progress\"\n    self._save(task)\n```\n\n**Step 3.** Run commands in the worktree. The key detail: `cwd` points to the isolated directory, not your main project root. Every file operation happens in a sandbox that cannot collide with other worktrees.\n\n```python\nsubprocess.run(command, shell=True, cwd=worktree_path,\n               capture_output=True, text=True, timeout=300)\n```\n\n**Step 4.** Close out the worktree. You have two choices, depending on whether the work is done:\n\n- `worktree_keep(name)` -- preserve the directory for later (useful when a task is paused or needs review).\n- `worktree_remove(name, complete_task=True)` -- remove the directory, mark the bound task as completed, and emit an event. One call handles teardown and completion together.\n\n```python\ndef remove(self, name, force=False, complete_task=False):\n    self._run_git([\"worktree\", \"remove\", wt[\"path\"]])\n    if complete_task and wt.get(\"task_id\") is not None:\n        self.tasks.update(wt[\"task_id\"], status=\"completed\")\n        self.tasks.unbind_worktree(wt[\"task_id\"])\n        self.events.emit(\"task.completed\", ...)\n```\n\n**Step 5.** Observe the event stream. Every lifecycle step emits a structured event to `.worktrees/events.jsonl`, giving you a complete audit trail of what happened and when:\n\n```json\n{\n  \"event\": \"worktree.remove.after\",\n  \"task\": {\"id\": 1, \"status\": \"completed\"},\n  \"worktree\": {\"name\": \"auth-refactor\", \"status\": \"removed\"},\n  \"ts\": 1730000000\n}\n```\n\nEvents emitted: `worktree.create.before/after/failed`, `worktree.remove.before/after/failed`, `worktree.keep`, `task.completed`.\n\nIn the teaching version, `.tasks/` plus `.worktrees/index.json` are enough to reconstruct the visible control-plane state after a crash. The important lesson is not every production edge case. The important lesson is that goal state and execution-lane state must both stay legible on disk.\n\n## What Changed From s17\n\n| Component          | Before (s17)               | After (s18)                                  |\n|--------------------|----------------------------|----------------------------------------------|\n| Coordination       | Task board (owner/status)  | Task board + explicit worktree binding       |\n| Execution scope    | Shared directory           | Task-scoped isolated directory               |\n| Recoverability     | Task status only           | Task status + worktree index                 |\n| Teardown           | Task completion            | Task completion + explicit keep/remove       |\n| Lifecycle visibility | Implicit in logs         | Explicit events in `.worktrees/events.jsonl` |\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s18_worktree_task_isolation.py\n```\n\n1. `Create tasks for backend auth and frontend login page, then list tasks.`\n2. `Create worktree \"auth-refactor\" for task 1, then bind task 2 to a new worktree \"ui-login\".`\n3. `Run \"git status --short\" in worktree \"auth-refactor\".`\n4. `Keep worktree \"ui-login\", then list worktrees and inspect events.`\n5. `Remove worktree \"auth-refactor\" with complete_task=true, then list tasks/worktrees/events.`\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Create isolated git worktrees so that parallel agents never produce file conflicts\n- Bind tasks to worktrees with a two-way reference (task points to worktree name, worktree points to task ID)\n- Choose between keeping and removing a worktree at closeout, with automatic task status updates\n- Read the event stream in `events.jsonl` to understand the full lifecycle of every worktree\n\n## What's Next\n\nYou now have agents that can work in complete isolation, each in its own directory with its own branch. But every capability they use -- bash, read, write, edit -- is hard-coded into your Python harness. In s19, you will learn how external programs can provide new capabilities through MCP (Model Context Protocol), so your agent can grow without changing its core code.\n\n## Key Takeaway\n\n> Tasks answer *what work is being done*; worktrees answer *where that work runs*; keeping them separate makes parallel systems far easier to reason about and recover from.\n"
  },
  {
    "version": "s19",
    "slug": "s19-mcp-plugin",
    "locale": "en",
    "title": "s19: MCP & Plugin",
    "kind": "chapter",
    "filename": "s19-mcp-plugin.md",
    "content": "# s19: MCP & Plugin\n\n`s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > [ s19 ]`\n\n## What You'll Learn\n- How MCP (Model Context Protocol -- a standard way for the agent to talk to external capability servers) lets your agent gain new tools without changing its core code\n- How tool name normalization with a `mcp__{server}__{tool}` prefix keeps external tools from colliding with native ones\n- How a unified router dispatches tool calls to local handlers or remote servers through the same path\n- How plugin manifests let external capability servers be discovered and launched automatically\n\nUp to this point, every tool your agent uses -- bash, read, write, edit, tasks, worktrees -- lives inside your Python harness. You wrote each one by hand. That works well for a teaching codebase, but a real agent needs to talk to databases, browsers, cloud services, and tools that do not exist yet. Hard-coding every possible capability is not sustainable. This chapter shows how external programs can join your agent through the same tool-routing plane you already built.\n\n## The Problem\n\nYour agent is powerful, but its capabilities are frozen at build time. If you want it to query a Postgres database, you write a new Python handler. If you want it to control a browser, you write another handler. Every new capability means changing the core harness, re-testing the tool router, and redeploying. Meanwhile, other teams are building specialized servers that already know how to talk to these systems. You need a standard protocol so those external servers can expose their tools to your agent, and your agent can call them as naturally as it calls its own native tools -- without rewriting the core loop every time.\n\n## The Solution\n\nMCP gives your agent a standard way to connect to external capability servers over stdio. The agent starts a server process, asks what tools it provides, normalizes their names with a prefix, and routes calls to that server -- all through the same tool pipeline that handles native tools.\n\n```text\nLLM\n  |\n  | asks to call a tool\n  v\nAgent tool router\n  |\n  +-- native tool  -> local Python handler\n  |\n  +-- MCP tool     -> external MCP server\n                        |\n                        v\n                    return result\n```\n\n## Read Together\n\n- If you want to understand how MCP fits into the broader capability surface beyond just tools (resources, prompts, plugin discovery), [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md) covers the full platform boundary.\n- If you want to confirm that external capabilities still return through the same execution surface as native tools, pair this chapter with [`s02b-tool-execution-runtime.md`](./s02b-tool-execution-runtime.md).\n- If query control and external capability routing are drifting apart in your mental model, [`s00a-query-control-plane.md`](./s00a-query-control-plane.md) ties them together.\n\n## How It Works\n\nThere are three essential pieces. Once you understand them, MCP stops being mysterious.\n\n**Step 1.** Build an `MCPClient` that manages the connection to one external server. It starts the server process over stdio, sends a handshake, and caches the list of available tools.\n\n```python\nclass MCPClient:\n    def __init__(self, server_name, command, args=None, env=None):\n        self.server_name = server_name\n        self.command = command\n        self.args = args or []\n        self.process = None\n        self._tools = []\n\n    def connect(self):\n        self.process = subprocess.Popen(\n            [self.command] + self.args,\n            stdin=subprocess.PIPE, stdout=subprocess.PIPE,\n            stderr=subprocess.PIPE, text=True,\n        )\n        self._send({\"method\": \"initialize\", \"params\": {\n            \"protocolVersion\": \"2024-11-05\",\n            \"capabilities\": {},\n            \"clientInfo\": {\"name\": \"teaching-agent\", \"version\": \"1.0\"},\n        }})\n        response = self._recv()\n        if response and \"result\" in response:\n            self._send({\"method\": \"notifications/initialized\"})\n            return True\n        return False\n\n    def list_tools(self):\n        self._send({\"method\": \"tools/list\", \"params\": {}})\n        response = self._recv()\n        if response and \"result\" in response:\n            self._tools = response[\"result\"].get(\"tools\", [])\n        return self._tools\n\n    def call_tool(self, tool_name, arguments):\n        self._send({\"method\": \"tools/call\", \"params\": {\n            \"name\": tool_name, \"arguments\": arguments,\n        }})\n        response = self._recv()\n        if response and \"result\" in response:\n            content = response[\"result\"].get(\"content\", [])\n            return \"\\n\".join(c.get(\"text\", str(c)) for c in content)\n        return \"MCP Error: no response\"\n```\n\n**Step 2.** Normalize external tool names with a prefix so they never collide with native tools. The convention is simple: `mcp__{server}__{tool}`.\n\n```text\nmcp__postgres__query\nmcp__browser__open_tab\n```\n\nThis prefix serves double duty: it prevents name collisions, and it tells the router exactly which server should handle the call.\n\n```python\ndef get_agent_tools(self):\n    agent_tools = []\n    for tool in self._tools:\n        prefixed_name = f\"mcp__{self.server_name}__{tool['name']}\"\n        agent_tools.append({\n            \"name\": prefixed_name,\n            \"description\": tool.get(\"description\", \"\"),\n            \"input_schema\": tool.get(\"inputSchema\", {\n                \"type\": \"object\", \"properties\": {}\n            }),\n        })\n    return agent_tools\n```\n\n**Step 3.** Build one unified router. The router does not care whether a tool is native or external beyond the dispatch decision. If the name starts with `mcp__`, route to the MCP server; otherwise, call the local handler. This keeps the agent loop untouched -- it just sees a flat list of tools.\n\n```python\nif tool_name.startswith(\"mcp__\"):\n    return mcp_router.call(tool_name, arguments)\nelse:\n    return native_handler(arguments)\n```\n\n**Step 4.** Add plugin discovery. If MCP answers \"how does the agent talk to an external capability server,\" plugins answer \"how are those servers discovered and configured?\" A minimal plugin is a manifest file that tells the harness which servers to launch:\n\n```json\n{\n  \"name\": \"my-db-tools\",\n  \"version\": \"1.0.0\",\n  \"mcpServers\": {\n    \"postgres\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-postgres\"]\n    }\n  }\n}\n```\n\nThis lives in `.claude-plugin/plugin.json`. The `PluginLoader` scans for these manifests, extracts the server configs, and hands them to the `MCPToolRouter` for connection.\n\n**Step 5.** Enforce the safety boundary. This is the most important rule of the entire chapter: external tools must still pass through the same permission gate as native tools. If MCP tools bypass permission checks, you have created a security backdoor at the edge of your system.\n\n```python\ndecision = permission_gate.check(block.name, block.input or {})\n# Same check for \"bash\", \"read_file\", and \"mcp__postgres__query\"\n```\n\n## How It Plugs Into The Full Harness\n\nMCP gets confusing when it is treated like a separate universe. The cleaner model is:\n\n```text\nstartup\n  ->\nplugin loader finds manifests\n  ->\nserver configs are extracted\n  ->\nMCP clients connect and list tools\n  ->\nexternal tools are normalized into the same tool pool\n\nruntime\n  ->\nLLM emits tool_use\n  ->\nshared permission gate\n  ->\nnative route or MCP route\n  ->\nresult normalization\n  ->\ntool_result returns to the same loop\n```\n\nDifferent entry point, same control plane and execution plane.\n\n## Plugin vs Server vs Tool\n\n| Layer | What it is | What it is for |\n|---|---|---|\n| plugin manifest | a config declaration | tells the harness which servers to discover and launch |\n| MCP server | an external process / connection | exposes a set of capabilities |\n| MCP tool | one callable capability from that server | the concrete thing the model invokes |\n\nShortest memory aid:\n\n- plugin = discovery\n- server = connection\n- tool = invocation\n\n## Key Data Structures\n\n### Server config\n\n```python\n{\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"...\"],\n    \"env\": {}\n}\n```\n\n### Normalized external tool definition\n\n```python\n{\n    \"name\": \"mcp__postgres__query\",\n    \"description\": \"Run a SQL query\",\n    \"input_schema\": {...}\n}\n```\n\n### Client registry\n\n```python\nclients = {\n    \"postgres\": mcp_client_instance\n}\n```\n\n## What Changed From s18\n\n| Component          | Before (s18)                      | After (s19)                                      |\n|--------------------|-----------------------------------|--------------------------------------------------|\n| Tool sources       | All native (local Python)         | Native + external MCP servers                    |\n| Tool naming        | Flat names (`bash`, `read_file`)  | Prefixed for externals (`mcp__postgres__query`)  |\n| Routing            | Single handler map                | Unified router: native dispatch + MCP dispatch   |\n| Capability growth  | Edit harness code for each tool   | Add a plugin manifest or connect a server        |\n| Permission scope   | Native tools only                 | Native + external tools through same gate        |\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s19_mcp_plugin.py\n```\n\n1. Watch how external tools are discovered from plugin manifests at startup.\n2. Type `/tools` to see native and MCP tools listed side by side in one flat pool.\n3. Type `/mcp` to see which MCP servers are connected and how many tools each provides.\n4. Ask the agent to use a tool and notice how results return through the same loop as local tools.\n\n## What You've Mastered\n\nAt this point, you can:\n\n- Connect to external capability servers using the MCP stdio protocol\n- Normalize external tool names with a `mcp__{server}__{tool}` prefix to prevent collisions\n- Route tool calls through a unified dispatcher that handles both native and MCP tools\n- Discover and launch MCP servers automatically through plugin manifests\n- Enforce the same permission checks on external tools as on native ones\n\n## The Full Picture\n\nYou have now walked through the complete design backbone of a production coding agent, from s01 to s19.\n\nYou started with a bare agent loop that calls an LLM and appends tool results. You added tool use, then a persistent task list, then subagents, skill loading, and context compaction. You built a permission system, a hook system, and a memory system. You constructed the system prompt pipeline, added error recovery, and gave agents a full task board with background execution and cron scheduling. You organized agents into teams with coordination protocols, made them autonomous, gave each task its own isolated worktree, and finally opened the door to external capabilities through MCP.\n\nEach chapter added exactly one idea to the system. None of them required you to throw away what came before. The agent you have now is not a toy -- it is a working model of the same architectural decisions that shape real production agents.\n\nIf you want to test your understanding, try rebuilding the complete system from scratch. Start with the agent loop. Add tools. Add tasks. Keep going until you reach MCP. If you can do that without looking back at the chapters, you understand the design. And if you get stuck somewhere in the middle, the chapter that covers that idea will be waiting for you.\n\n## Key Takeaway\n\n> External capabilities should enter the same tool pipeline as native ones -- same naming, same routing, same permissions -- so the agent loop never needs to know the difference.\n"
  },
  {
    "version": null,
    "slug": "s19a-mcp-capability-layers",
    "locale": "en",
    "title": "s19a: MCP Capability Layers",
    "kind": "bridge",
    "filename": "s19a-mcp-capability-layers.md",
    "content": "# s19a: MCP Capability Layers\n\n> **Deep Dive** -- Best read alongside s19. It shows that MCP is more than just external tools.\n\n### When to Read This\n\nAfter reading s19's tools-first approach, when you're ready to see the full MCP capability stack.\n\n---\n\n> `s19` should still keep a tools-first mainline.\n> This bridge note adds the second mental model:\n>\n> **MCP is not only external tool access. It is a stack of capability layers.**\n\n## How to Read This with the Mainline\n\nIf you want to study MCP without drifting away from the teaching goal:\n\n- read [`s19-mcp-plugin.md`](./s19-mcp-plugin.md) first and keep the tools-first path clear\n- then you might find it helpful to revisit [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) to see how external capability routes back into the unified tool bus\n- if state records begin to blur, you might find it helpful to revisit [`data-structures.md`](./data-structures.md)\n- if concept boundaries blur, you might find it helpful to revisit [`glossary.md`](./glossary.md) and [`entity-map.md`](./entity-map.md)\n\n## Why This Deserves a Separate Bridge Note\n\nFor a teaching repo, keeping the mainline focused on external tools first is correct.\n\nThat is the easiest entry:\n\n- connect an external server\n- receive tool definitions\n- call a tool\n- bring the result back into the agent\n\nBut if you want the system shape to approach real high-completion behavior, you quickly meet deeper questions:\n\n- is the server connected through stdio, HTTP, SSE, or WebSocket\n- why are some servers `connected`, while others are `pending` or `needs-auth`\n- where do resources and prompts fit relative to tools\n- why does elicitation become a special kind of interaction\n- where should OAuth or other auth flows be placed conceptually\n\nWithout a capability-layer map, MCP starts to feel scattered.\n\n## Terms First\n\n### What capability layers means\n\nA capability layer is simply:\n\n> one responsibility slice in a larger system\n\nThe point is to avoid mixing every MCP concern into one bag.\n\n### What transport means\n\nTransport is the connection channel between your agent and an MCP server:\n\n- stdio (standard input/output, good for local processes)\n- HTTP\n- SSE (Server-Sent Events, a one-way streaming protocol over HTTP)\n- WebSocket\n\n### What elicitation means\n\nThis is one of the less familiar terms.\n\nA simple teaching definition is:\n\n> an interaction where the MCP server asks the user for more input before it can continue\n\nSo the system is no longer only:\n\n> agent calls tool -> tool returns result\n\nThe server can also say:\n\n> I need more information before I can finish\n\nThis turns a simple call-and-return into a multi-step conversation between the agent and the server.\n\n## The Minimum Mental Model\n\nA clear six-layer picture:\n\n```text\n1. Config Layer\n   what the server configuration looks like\n\n2. Transport Layer\n   how the server connection is carried\n\n3. Connection State Layer\n   connected / pending / failed / needs-auth\n\n4. Capability Layer\n   tools / resources / prompts / elicitation\n\n5. Auth Layer\n   whether authentication is required and what state it is in\n\n6. Router Integration Layer\n   how MCP routes back into tool routing, permissions, and notifications\n```\n\nThe key lesson is:\n\n**tools are one layer, not the whole MCP story**\n\n## Why the Mainline Should Still Stay Tools-First\n\nThis matters a lot for teaching.\n\nEven though MCP contains multiple layers, the chapter mainline should still teach:\n\n### Step 1: external tools first\n\nBecause that connects most naturally to everything you already learned:\n\n- local tools\n- external tools\n- one shared router\n\n### Step 2: show that more capability layers exist\n\nFor example:\n\n- resources\n- prompts\n- elicitation\n- auth\n\n### Step 3: decide which advanced layers the repo should actually implement\n\nThat matches the teaching goal:\n\n**build the similar system first, then add the heavier platform layers**\n\n## Core Records\n\n### 1. `ScopedMcpServerConfig`\n\nEven a minimal teaching version should expose this idea:\n\n```python\nconfig = {\n    \"name\": \"postgres\",\n    \"type\": \"stdio\",\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"...\"],\n    \"scope\": \"project\",\n}\n```\n\n`scope` matters because server configuration may come from different places (global user settings, project-level settings, or even per-workspace overrides).\n\n### 2. MCP connection state\n\n```python\nserver_state = {\n    \"name\": \"postgres\",\n    \"status\": \"connected\",   # pending / failed / needs-auth / disabled\n    \"config\": {...},\n}\n```\n\n### 3. `MCPToolSpec`\n\n```python\ntool = {\n    \"name\": \"mcp__postgres__query\",\n    \"description\": \"...\",\n    \"input_schema\": {...},\n}\n```\n\n### 4. `ElicitationRequest`\n\n```python\nrequest = {\n    \"server_name\": \"some-server\",\n    \"message\": \"Please provide additional input\",\n    \"requested_schema\": {...},\n}\n```\n\nThe teaching point is not that you need to implement elicitation immediately.\n\nThe point is:\n\n**MCP is not guaranteed to stay a one-way tool invocation forever**\n\n## The Cleaner Platform Picture\n\n```text\nMCP Config\n  |\n  v\nTransport\n  |\n  v\nConnection State\n  |\n  +-- connected\n  +-- pending\n  +-- needs-auth\n  +-- failed\n  |\n  v\nCapabilities\n  +-- tools\n  +-- resources\n  +-- prompts\n  +-- elicitation\n  |\n  v\nRouter / Permission / Notification Integration\n```\n\n## Why Auth Should Not Dominate the Chapter Mainline\n\nAuth is a real layer in the full platform.\n\nBut if the mainline falls into OAuth or vendor-specific auth flow details too early, beginners lose the actual system shape.\n\nA better teaching order is:\n\n- first explain that an auth layer exists\n- then explain that `connected` and `needs-auth` are different connection states\n- only later, in advanced platform work, expand the full auth state machine\n\nThat keeps the repo honest without derailing your learning path.\n\n## How This Relates to `s19` and `s02a`\n\n- the `s19` chapter keeps teaching the tools-first external capability path\n- this note supplies the broader platform map\n- `s02a` explains how MCP capability eventually reconnects to the unified tool control plane\n\nTogether, they teach the actual idea:\n\n**MCP is an external capability platform, and tools are only the first face of it that enters the mainline**\n\n## Common Beginner Mistakes\n\n### 1. Treating MCP as only an external tool catalog\n\nThat makes resources, prompts, auth, and elicitation feel surprising later.\n\n### 2. Diving into transport or OAuth details too early\n\nThat breaks the teaching mainline.\n\n### 3. Letting MCP tools bypass permission checks\n\nThat opens a dangerous side door in the system boundary.\n\n### 4. Mixing server config, connection state, and exposed capabilities into one blob\n\nThose layers should stay conceptually separate.\n\n## Key Takeaway\n\n**MCP is a six-layer capability platform. Tools are the first layer you build, but resources, prompts, elicitation, auth, and router integration are all part of the full picture.**\n"
  },
  {
    "version": null,
    "slug": "teaching-scope",
    "locale": "en",
    "title": "Teaching Scope",
    "kind": "bridge",
    "filename": "teaching-scope.md",
    "content": "# Teaching Scope\n\nThis document explains what you will learn in this repo, what is deliberately left out, and how each chapter stays aligned with your mental model as it grows.\n\n## The Goal Of This Repo\n\nThis is not a line-by-line commentary on some upstream production codebase.\n\nThe real goal is:\n\n**teach you how to build a high-completion coding-agent harness from scratch.**\n\nThat implies three obligations:\n\n1. you can actually rebuild it\n2. you keep the mainline clear instead of drowning in side detail\n3. you do not absorb mechanisms that do not really exist\n\n## What Every Chapter Should Cover\n\nEvery mainline chapter should make these things explicit:\n\n- what problem the mechanism solves\n- which module or layer it belongs to\n- what state it owns\n- what data structures it introduces\n- how it plugs back into the loop\n- what changes in the runtime flow after it appears\n\nIf you finish a chapter and still cannot say where the mechanism lives or what state it owns, the chapter is not done yet.\n\n## What We Deliberately Keep Simple\n\nThese topics are not forbidden, but they should not dominate your learning path:\n\n- packaging, build, and release flow\n- cross-platform compatibility glue\n- telemetry and enterprise policy wiring\n- historical compatibility branches\n- product-specific naming accidents\n- line-by-line upstream code matching\n\nThose belong in appendices, maintainer notes, or later productization notes, not at the center of the beginner path.\n\n## What \"High Fidelity\" Really Means Here\n\nHigh fidelity in a teaching repo does not mean reproducing every edge detail 1:1.\n\nIt means staying close to the true system backbone:\n\n- core runtime model\n- module boundaries\n- key records\n- state transitions\n- cooperation between major subsystems\n\nIn short:\n\n**be highly faithful to the trunk, and deliberate about teaching simplifications at the edges.**\n\n## Who This Is For\n\nYou do not need to be an expert in agent platforms.\n\nA better assumption about you:\n\n- basic Python is familiar\n- functions, classes, lists, and dictionaries are familiar\n- agent systems may be completely new\n\nThat means the chapters should:\n\n- explain new concepts before using them\n- keep one concept complete in one main place\n- move from \"what it is\" to \"why it exists\" to \"how to build it\"\n\n## Recommended Chapter Structure\n\nMainline chapters should roughly follow this order:\n\n1. what problem appears without this mechanism\n2. first explain the new terms\n3. give the smallest useful mental model\n4. show the core records / data structures\n5. show the smallest correct implementation\n6. show how it plugs into the main loop\n7. show common beginner mistakes\n8. show what a higher-completion version would add later\n\n## Terminology Guideline\n\nIf a chapter introduces a term from these categories, it should explain it:\n\n- design pattern\n- data structure\n- concurrency term\n- protocol / networking term\n- uncommon engineering vocabulary\n\nExamples:\n\n- state machine\n- scheduler\n- queue\n- worktree\n- DAG\n- protocol envelope\n\nDo not drop the name without the explanation.\n\n## Minimal Correct Version Principle\n\nReal mechanisms are often complex, but teaching works best when it does not start with every branch at once.\n\nPrefer this sequence:\n\n1. show the smallest correct version\n2. explain what core problem it already solves\n3. show what later iterations would add\n\nExamples:\n\n- permission system: first `deny -> mode -> allow -> ask`\n- error recovery: first three major recovery branches\n- task system: first task records, dependencies, and unlocks\n- team protocols: first request / response plus `request_id`\n\n## Checklist For Rewriting A Chapter\n\n- Does the first screen explain why the mechanism exists?\n- Are new terms explained before they are used?\n- Is there a small mental model or flow picture?\n- Are key records listed explicitly?\n- Is the plug-in point back into the loop explained?\n- Are core mechanisms separated from peripheral product detail?\n- Are the easiest confusion points called out?\n- Does the chapter avoid inventing mechanisms not supported by the repo?\n\n## How To Use Reverse-Engineered Source Material\n\nReverse-engineered source should be used as:\n\n**maintainer calibration material**\n\nUse it to:\n\n- verify the mainline mechanism is described correctly\n- verify important boundaries and records are not missing\n- verify the teaching implementation did not drift into fiction\n\nIt should never become a prerequisite for understanding the teaching docs.\n\n## Key Takeaway\n\n**The quality of a teaching repo is decided less by how many details it mentions and more by whether the important details are fully explained and the unimportant details are safely omitted.**\n"
  },
  {
    "version": null,
    "slug": "team-task-lane-model",
    "locale": "en",
    "title": "Team Task Lane Model",
    "kind": "bridge",
    "filename": "team-task-lane-model.md",
    "content": "# Team Task Lane Model\n\n> **Deep Dive** -- Best read at the start of Stage 4 (s15-s18). It separates five concepts that look similar but live on different layers.\n\n### When to Read This\n\nBefore you start the team chapters. Keep it open as a reference during s15-s18.\n\n---\n\n> By the time you reach `s15-s18`, the easiest thing to blur is not a function name.\n>\n> It is this:\n>\n> **Who is working, who is coordinating, what records the goal, and what provides the execution lane.**\n\n## What This Bridge Doc Fixes\n\nAcross `s15-s18`, you will encounter these words that can easily blur into one vague idea:\n\n- teammate\n- protocol request\n- task\n- runtime task\n- worktree\n\nThey all relate to work getting done, but they do **not** live on the same layer.\n\nIf you do not separate them, the later chapters start to feel tangled:\n\n- Is a teammate the same thing as a task?\n- What is the difference between `request_id` and `task_id`?\n- Is a worktree just another runtime task?\n- Why can a task be complete while a worktree is still kept?\n\nThis document exists to separate those layers cleanly.\n\n## Recommended Reading Order\n\n1. Read [`s15-agent-teams.md`](./s15-agent-teams.md) for long-lived teammates.\n2. Read [`s16-team-protocols.md`](./s16-team-protocols.md) for tracked request-response coordination.\n3. Read [`s17-autonomous-agents.md`](./s17-autonomous-agents.md) for self-claiming teammates.\n4. Read [`s18-worktree-task-isolation.md`](./s18-worktree-task-isolation.md) for isolated execution lanes.\n\nIf the vocabulary starts to blur, you might find it helpful to revisit:\n\n- [`entity-map.md`](./entity-map.md)\n- [`data-structures.md`](./data-structures.md)\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n\n## The Core Separation\n\n```text\nteammate\n  = who participates over time\n\nprotocol request\n  = one tracked coordination request inside the team\n\ntask\n  = what should be done\n\nruntime task / execution slot\n  = what is actively running right now\n\nworktree\n  = where the work executes without colliding with other lanes\n```\n\nThe most common confusion is between the last three:\n\n- `task`\n- `runtime task`\n- `worktree`\n\nAsk three separate questions every time:\n\n- Is this the goal?\n- Is this the running execution unit?\n- Is this the isolated execution directory?\n\n## The Smallest Clean Diagram\n\n```text\nTeam Layer\n  teammate: alice (frontend)\n\nProtocol Layer\n  request_id=req_01\n  kind=plan_approval\n  status=pending\n\nWork Graph Layer\n  task_id=12\n  subject=\"Implement login page\"\n  owner=\"alice\"\n  status=\"in_progress\"\n\nRuntime Layer\n  runtime_id=rt_01\n  type=in_process_teammate\n  status=running\n\nExecution Lane Layer\n  worktree=login-page\n  path=.worktrees/login-page\n  status=active\n```\n\nOnly one of those records the work goal itself:\n\n> `task_id=12`\n\nThe others support coordination, execution, or isolation around that goal.\n\n## 1. Teammate: Who Is Collaborating\n\nIntroduced in `s15`.\n\nThis layer answers:\n\n- what the long-lived worker is called\n- what role it has\n- whether it is `working`, `idle`, or `shutdown`\n- whether it has its own inbox\n\nExample:\n\n```python\nmember = {\n    \"name\": \"alice\",\n    \"role\": \"frontend\",\n    \"status\": \"idle\",\n}\n```\n\nThe point is not \"another agent instance.\"\n\nThe point is:\n\n> a persistent identity that can repeatedly receive work.\n\n## 2. Protocol Request: What Is Being Coordinated\n\nIntroduced in `s16`.\n\nThis layer answers:\n\n- who asked whom\n- what kind of request this is\n- whether it is still pending or already resolved\n\nExample:\n\n```python\nrequest = {\n    \"request_id\": \"a1b2c3d4\",\n    \"kind\": \"plan_approval\",\n    \"from\": \"alice\",\n    \"to\": \"lead\",\n    \"status\": \"pending\",\n}\n```\n\nThis is not ordinary chat.\n\nIt is:\n\n> a coordination record whose state can continue to evolve.\n\n## 3. Task: What Should Be Done\n\nThis is the durable work-graph task from `s12`, and it is what `s17` teammates claim.\n\nIt answers:\n\n- what the goal is\n- who owns it\n- what blocks it\n- what progress state it is in\n\nExample:\n\n```python\ntask = {\n    \"id\": 12,\n    \"subject\": \"Implement login page\",\n    \"status\": \"in_progress\",\n    \"owner\": \"alice\",\n    \"blockedBy\": [],\n}\n```\n\nKeyword:\n\n**goal**\n\nNot directory. Not protocol. Not process.\n\n## 4. Runtime Task / Execution Slot: What Is Running\n\nThis layer was already clarified in the `s13a` bridge doc, but it matters even more in `s15-s18`.\n\nExamples:\n\n- a background shell command\n- a long-lived teammate currently working\n- a monitor process watching an external state\n\nThese are best understood as:\n\n> active execution slots\n\nExample:\n\n```python\nruntime = {\n    \"id\": \"rt_01\",\n    \"type\": \"in_process_teammate\",\n    \"status\": \"running\",\n    \"work_graph_task_id\": 12,\n}\n```\n\nImportant boundary:\n\n- one work-graph task may spawn multiple runtime tasks\n- a runtime task is an execution instance, not the durable goal itself\n\n## 5. Worktree: Where the Work Happens\n\nIntroduced in `s18`.\n\nThis layer answers:\n\n- which isolated directory is used\n- which task it is bound to\n- whether that lane is `active`, `kept`, or `removed`\n\nExample:\n\n```python\nworktree = {\n    \"name\": \"login-page\",\n    \"path\": \".worktrees/login-page\",\n    \"task_id\": 12,\n    \"status\": \"active\",\n}\n```\n\nKeyword:\n\n**execution boundary**\n\nIt is not the task goal itself. It is the isolated lane where that goal is executed.\n\n## How The Layers Connect\n\n```text\nteammate\n  coordinates through protocol requests\n  claims a task\n  runs as an execution slot\n  works inside a worktree lane\n```\n\nIn a more concrete sentence:\n\n> `alice` claims `task #12` and progresses it inside the `login-page` worktree lane.\n\nThat sentence is much cleaner than saying:\n\n> \"alice is doing the login-page worktree task\"\n\nbecause the shorter sentence incorrectly merges:\n\n- the teammate\n- the task\n- the worktree\n\n## Common Mistakes\n\n### 1. Treating teammate and task as the same object\n\nThe teammate executes. The task expresses the goal.\n\n### 2. Treating `request_id` and `task_id` as interchangeable\n\nOne tracks coordination. The other tracks work goals.\n\n### 3. Treating the runtime slot as the durable task\n\nThe running execution may end while the durable task still exists.\n\n### 4. Treating the worktree as the task itself\n\nThe worktree is only the execution lane.\n\n### 5. Saying \"the system works in parallel\" without naming the layers\n\nGood teaching does not stop at \"there are many agents.\"\n\nIt can say clearly:\n\n> teammates provide long-lived collaboration, requests track coordination, tasks record goals, runtime slots carry execution, and worktrees isolate the execution directory.\n\n## What You Should Be Able to Say After Reading This\n\n1. `s17` autonomy claims `s12` work-graph tasks, not `s13` runtime slots.\n2. `s18` worktrees bind execution lanes to tasks; they do not turn tasks into directories.\n3. A teammate can be idle while the task still exists and while the worktree is still kept.\n4. A protocol request tracks a coordination exchange, not a work goal.\n\n## Key Takeaway\n\n**Five things that sound alike -- teammate, protocol request, task, runtime slot, worktree -- live on five separate layers. Naming which layer you mean is how you keep the team chapters from collapsing into confusion.**\n"
  },
  {
    "version": null,
    "slug": "data-structures",
    "locale": "zh",
    "title": "Core Data Structures (核心数据结构总表)",
    "kind": "bridge",
    "filename": "data-structures.md",
    "content": "# Core Data Structures (核心数据结构总表)\n\n> 学习 agent，最容易迷路的地方不是功能太多，而是不知道“状态到底放在哪”。这份文档把主线章节和桥接章节里反复出现的关键数据结构集中列出来，方便你把整套系统看成一张图。\n\n## 推荐联读\n\n建议把这份总表当成“状态地图”来用：\n\n- 先不懂词，就回 [`glossary.md`](./glossary.md)。\n- 先不懂边界，就回 [`entity-map.md`](./entity-map.md)。\n- 如果卡在 `TaskRecord` 和 `RuntimeTaskState`，继续看 [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)。\n- 如果卡在 MCP 为什么还有 resource / prompt / elicitation，继续看 [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)。\n\n## 先记住两个总原则\n\n### 原则 1：区分“内容状态”和“流程状态”\n\n- `messages`、`tool_result`、memory 正文，属于内容状态。\n- `turn_count`、`transition`、`pending_classifier_check`，属于流程状态。\n\n很多初学者会把这两类状态混在一起。  \n一混，后面就很难看懂为什么一个结构完整的系统会需要控制平面。\n\n### 原则 2：区分“持久状态”和“运行时状态”\n\n- task、memory、schedule 这类状态，通常会落盘，跨会话存在。\n- runtime task、当前 permission decision、当前 MCP connection 这类状态，通常只在系统运行时活着。\n\n## 1. 查询与对话控制状态\n\n### Message\n\n作用：保存当前对话和工具往返历史。\n\n最小形状：\n\n```python\nmessage = {\n    \"role\": \"user\" | \"assistant\",\n    \"content\": \"...\",\n}\n```\n\n支持工具调用后，`content` 常常不再只是字符串，而会变成块列表，其中可能包含：\n\n- text block\n- `tool_use`\n- `tool_result`\n\n相关章节：\n\n- `s01`\n- `s02`\n- `s06`\n- `s10`\n\n### NormalizedMessage\n\n作用：把不同来源的消息整理成统一、稳定、可送给模型 API 的消息格式。\n\n最小形状：\n\n```python\nmessage = {\n    \"role\": \"user\" | \"assistant\",\n    \"content\": [\n        {\"type\": \"text\", \"text\": \"...\"},\n    ],\n}\n```\n\n它和普通 `Message` 的区别是：\n\n- `Message` 偏“系统内部记录”\n- `NormalizedMessage` 偏“准备发给模型之前的统一输入”\n\n相关章节：\n\n- `s10`\n- [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md)\n\n### CompactSummary\n\n作用：上下文太长时，用摘要替代旧消息原文。\n\n最小形状：\n\n```python\nsummary = {\n    \"task_overview\": \"...\",\n    \"current_state\": \"...\",\n    \"key_decisions\": [\"...\"],\n    \"next_steps\": [\"...\"],\n}\n```\n\n相关章节：\n\n- `s06`\n- `s11`\n\n### SystemPromptBlock\n\n作用：把 system prompt 从一整段大字符串，拆成若干可管理片段。\n\n最小形状：\n\n```python\nblock = {\n    \"text\": \"...\",\n    \"cache_scope\": None,\n}\n```\n\n你可以把它理解成：\n\n- `text`：这一段提示词正文\n- `cache_scope`：这一段是否可以复用缓存\n\n相关章节：\n\n- `s10`\n- [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md)\n\n### PromptParts\n\n作用：在真正拼成 system prompt 之前，先把各部分拆开管理。\n\n最小形状：\n\n```python\nparts = {\n    \"core\": \"...\",\n    \"tools\": \"...\",\n    \"skills\": \"...\",\n    \"memory\": \"...\",\n    \"claude_md\": \"...\",\n    \"dynamic\": \"...\",\n}\n```\n\n相关章节：\n\n- `s10`\n\n### QueryParams\n\n作用：进入查询主循环时，外部一次性传进来的输入集合。\n\n最小形状：\n\n```python\nparams = {\n    \"messages\": [...],\n    \"system_prompt\": \"...\",\n    \"user_context\": {...},\n    \"system_context\": {...},\n    \"tool_use_context\": {...},\n    \"fallback_model\": None,\n    \"max_output_tokens_override\": None,\n    \"max_turns\": None,\n}\n```\n\n它的重要点在于：\n\n- 这是“本次 query 的入口输入”\n- 它和循环内部不断变化的状态，不是同一层\n\n相关章节：\n\n- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)\n\n### QueryState\n\n作用：保存一条 query 在多轮循环之间不断变化的流程状态。\n\n最小形状：\n\n```python\nstate = {\n    \"messages\": [...],\n    \"tool_use_context\": {...},\n    \"turn_count\": 1,\n    \"max_output_tokens_recovery_count\": 0,\n    \"has_attempted_reactive_compact\": False,\n    \"max_output_tokens_override\": None,\n    \"pending_tool_use_summary\": None,\n    \"stop_hook_active\": False,\n    \"transition\": None,\n}\n```\n\n这类字段的共同特点是：\n\n- 它们不是对话内容\n- 它们是“这一轮该怎么继续”的控制状态\n\n相关章节：\n\n- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)\n- `s11`\n\n### TransitionReason\n\n作用：记录“上一轮为什么继续了，而不是结束”。\n\n最小形状：\n\n```python\ntransition = {\n    \"reason\": \"next_turn\",\n}\n```\n\n在更完整的 query 状态里，这个 `reason` 常见会有这些类型：\n\n- `next_turn`\n- `reactive_compact_retry`\n- `token_budget_continuation`\n- `max_output_tokens_recovery`\n- `stop_hook_continuation`\n\n它的价值不是炫技，而是让：\n\n- 日志更清楚\n- 测试更清楚\n- 恢复链路更清楚\n\n相关章节：\n\n- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)\n- `s11`\n\n## 2. 工具、权限与 hook 执行状态\n\n### ToolSpec\n\n作用：告诉模型“有哪些工具、每个工具要什么输入”。\n\n最小形状：\n\n```python\ntool = {\n    \"name\": \"read_file\",\n    \"description\": \"Read file contents.\",\n    \"input_schema\": {...},\n}\n```\n\n相关章节：\n\n- `s02`\n- `s19`\n\n### ToolDispatchMap\n\n作用：把工具名映射到真实执行函数。\n\n最小形状：\n\n```python\nhandlers = {\n    \"read_file\": run_read,\n    \"write_file\": run_write,\n    \"bash\": run_bash,\n}\n```\n\n相关章节：\n\n- `s02`\n\n### ToolUseContext\n\n作用：把工具运行时需要的共享环境打成一个总线。\n\n最小形状：\n\n```python\ntool_use_context = {\n    \"tools\": handlers,\n    \"permission_context\": {...},\n    \"mcp_clients\": [],\n    \"messages\": [...],\n    \"app_state\": {...},\n    \"cwd\": \"...\",\n    \"read_file_state\": {...},\n    \"notifications\": [],\n}\n```\n\n这层很关键。  \n因为在更完整的工具执行环境里，工具拿到的不只是 `tool_input`，还包括：\n\n- 当前权限环境\n- 当前消息\n- 当前 app state\n- 当前 MCP client\n- 当前文件读取缓存\n\n相关章节：\n\n- [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)\n- `s07`\n- `s19`\n\n### PermissionRule\n\n作用：描述某类工具调用命中后该怎么处理。\n\n最小形状：\n\n```python\nrule = {\n    \"tool_name\": \"bash\",\n    \"rule_content\": \"rm -rf *\",\n    \"behavior\": \"deny\",\n}\n```\n\n相关章节：\n\n- `s07`\n\n### PermissionRuleSource\n\n作用：标记一条权限规则是从哪里来的。\n\n最小形状：\n\n```python\nsource = (\n    \"userSettings\"\n    | \"projectSettings\"\n    | \"localSettings\"\n    | \"flagSettings\"\n    | \"policySettings\"\n    | \"cliArg\"\n    | \"command\"\n    | \"session\"\n)\n```\n\n这个结构的意义是：\n\n- 你不只知道“有什么规则”\n- 还知道“这条规则是谁加进来的”\n\n相关章节：\n\n- `s07`\n\n### PermissionDecision\n\n作用：表示一次工具调用当前该允许、拒绝还是提问。\n\n最小形状：\n\n```python\ndecision = {\n    \"behavior\": \"allow\" | \"deny\" | \"ask\",\n    \"reason\": \"matched deny rule\",\n}\n```\n\n在更完整的权限流里，`ask` 结果还可能带：\n\n- 修改后的输入\n- 建议写回哪些规则更新\n- 一个后台自动分类检查\n\n相关章节：\n\n- `s07`\n\n### PermissionUpdate\n\n作用：描述“这次权限确认之后，要把什么改回配置里”。\n\n最小形状：\n\n```python\nupdate = {\n    \"type\": \"addRules\" | \"removeRules\" | \"setMode\" | \"addDirectories\",\n    \"destination\": \"userSettings\" | \"projectSettings\" | \"localSettings\" | \"session\",\n    \"rules\": [],\n}\n```\n\n它解决的是一个很容易被漏掉的问题：\n\n用户这次点了“允许”，到底只是这一次放行，还是要写回会话、项目，甚至用户级配置。\n\n相关章节：\n\n- `s07`\n\n### HookContext\n\n作用：把某个 hook 事件发生时的上下文打包给外部脚本。\n\n最小形状：\n\n```python\ncontext = {\n    \"event\": \"PreToolUse\",\n    \"tool_name\": \"bash\",\n    \"tool_input\": {...},\n    \"tool_result\": \"...\",\n}\n```\n\n相关章节：\n\n- `s08`\n\n### RecoveryState\n\n作用：记录恢复流程已经尝试到哪里。\n\n最小形状：\n\n```python\nstate = {\n    \"continuation_attempts\": 0,\n    \"compact_attempts\": 0,\n    \"transport_attempts\": 0,\n}\n```\n\n相关章节：\n\n- `s11`\n\n## 3. 持久化工作状态\n\n### TodoItem\n\n作用：当前会话里的轻量计划项。\n\n最小形状：\n\n```python\ntodo = {\n    \"content\": \"Read parser.py\",\n    \"status\": \"pending\" | \"completed\",\n}\n```\n\n相关章节：\n\n- `s03`\n\n### MemoryEntry\n\n作用：保存跨会话仍然有价值的信息。\n\n最小形状：\n\n```python\nmemory = {\n    \"name\": \"prefer_tabs\",\n    \"description\": \"User prefers tabs for indentation\",\n    \"type\": \"user\" | \"feedback\" | \"project\" | \"reference\",\n    \"scope\": \"private\" | \"team\",\n    \"body\": \"...\",\n}\n```\n\n这里最重要的不是字段多，而是边界清楚：\n\n- 只存不容易从当前项目状态重新推出来的东西\n- 记忆可能会过时，要验证\n\n相关章节：\n\n- `s09`\n\n### TaskRecord\n\n作用：磁盘上的工作图任务节点。\n\n最小形状：\n\n```python\ntask = {\n    \"id\": 12,\n    \"subject\": \"Implement auth module\",\n    \"description\": \"\",\n    \"status\": \"pending\",\n    \"blockedBy\": [],\n    \"blocks\": [],\n    \"owner\": \"\",\n    \"worktree\": \"\",\n}\n```\n\n重点字段：\n\n- `blockedBy`：谁挡着我\n- `blocks`：我挡着谁\n- `owner`：谁认领了\n- `worktree`：在哪个隔离目录里做\n\n相关章节：\n\n- `s12`\n- `s17`\n- `s18`\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n\n### ScheduleRecord\n\n作用：记录未来要触发的调度任务。\n\n最小形状：\n\n```python\nschedule = {\n    \"id\": \"job_001\",\n    \"cron\": \"0 9 * * 1\",\n    \"prompt\": \"Generate weekly report\",\n    \"recurring\": True,\n    \"durable\": True,\n    \"created_at\": 1710000000.0,\n    \"last_fired_at\": None,\n}\n```\n\n相关章节：\n\n- `s14`\n\n## 4. 运行时执行状态\n\n### RuntimeTaskState\n\n作用：表示系统里一个“正在运行的执行单元”。\n\n最小形状：\n\n```python\nruntime_task = {\n    \"id\": \"b8k2m1qz\",\n    \"type\": \"local_bash\",\n    \"status\": \"running\",\n    \"description\": \"Run pytest\",\n    \"start_time\": 1710000000.0,\n    \"end_time\": None,\n    \"output_file\": \".task_outputs/b8k2m1qz.txt\",\n    \"notified\": False,\n}\n```\n\n这和 `TaskRecord` 不是一回事：\n\n- `TaskRecord` 管工作目标\n- `RuntimeTaskState` 管当前执行槽位\n\n相关章节：\n\n- `s13`\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n\n### TeamMember\n\n作用：记录一个持久队友是谁、在做什么。\n\n最小形状：\n\n```python\nmember = {\n    \"name\": \"alice\",\n    \"role\": \"coder\",\n    \"status\": \"idle\",\n}\n```\n\n相关章节：\n\n- `s15`\n- `s17`\n\n### MessageEnvelope\n\n作用：队友之间传递结构化消息。\n\n最小形状：\n\n```python\nmessage = {\n    \"type\": \"message\" | \"shutdown_request\" | \"plan_approval\",\n    \"from\": \"lead\",\n    \"to\": \"alice\",\n    \"request_id\": \"req_001\",\n    \"content\": \"...\",\n    \"payload\": {},\n    \"timestamp\": 1710000000.0,\n}\n```\n\n相关章节：\n\n- `s15`\n- `s16`\n\n### RequestRecord\n\n作用：追踪一个协议请求当前走到哪里。\n\n最小形状：\n\n```python\nrequest = {\n    \"request_id\": \"req_001\",\n    \"kind\": \"shutdown\" | \"plan_review\",\n    \"status\": \"pending\" | \"approved\" | \"rejected\" | \"expired\",\n    \"from\": \"lead\",\n    \"to\": \"alice\",\n}\n```\n\n相关章节：\n\n- `s16`\n\n### WorktreeRecord\n\n作用：记录一个任务绑定的隔离工作目录。\n\n最小形状：\n\n```python\nworktree = {\n    \"name\": \"auth-refactor\",\n    \"path\": \".worktrees/auth-refactor\",\n    \"branch\": \"wt/auth-refactor\",\n    \"task_id\": 12,\n    \"status\": \"active\",\n}\n```\n\n相关章节：\n\n- `s18`\n\n### WorktreeEvent\n\n作用：记录 worktree 生命周期事件，便于恢复和排查。\n\n最小形状：\n\n```python\nevent = {\n    \"event\": \"worktree.create.after\",\n    \"task_id\": 12,\n    \"worktree\": \"auth-refactor\",\n    \"ts\": 1710000000.0,\n}\n```\n\n相关章节：\n\n- `s18`\n\n## 5. 外部平台与 MCP 状态\n\n### ScopedMcpServerConfig\n\n作用：描述一个 MCP server 应该如何连接，以及它的配置来自哪个作用域。\n\n最小形状：\n\n```python\nconfig = {\n    \"name\": \"postgres\",\n    \"type\": \"stdio\",\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"...\"],\n    \"scope\": \"project\",\n}\n```\n\n这个 `scope` 很重要，因为 server 配置可能来自：\n\n- 本地\n- 用户\n- 项目\n- 动态注入\n- 插件或托管来源\n\n相关章节：\n\n- `s19`\n- [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)\n- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)\n- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)\n\n### MCPServerConnectionState\n\n作用：表示一个 MCP server 当前连到了哪一步。\n\n最小形状：\n\n```python\nserver_state = {\n    \"name\": \"postgres\",\n    \"type\": \"connected\",   # pending / failed / needs-auth / disabled\n    \"config\": {...},\n}\n```\n\n这层特别重要，因为“有没有接上”不是布尔值，而是多种状态：\n\n- `connected`\n- `pending`\n- `failed`\n- `needs-auth`\n- `disabled`\n\n相关章节：\n\n- `s19`\n- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)\n\n### MCPToolSpec\n\n作用：把外部 MCP 工具转换成 agent 内部统一工具定义。\n\n最小形状：\n\n```python\nmcp_tool = {\n    \"name\": \"mcp__postgres__query\",\n    \"description\": \"Run a SQL query\",\n    \"input_schema\": {...},\n}\n```\n\n相关章节：\n\n- `s19`\n\n### ElicitationRequest\n\n作用：表示 MCP server 反过来向用户请求额外输入。\n\n最小形状：\n\n```python\nrequest = {\n    \"server_name\": \"some-server\",\n    \"message\": \"Please provide additional input\",\n    \"requested_schema\": {...},\n}\n```\n\n它提醒你一件事：\n\n- MCP 不只是“模型主动调工具”\n- 外部 server 也可能反过来请求补充输入\n\n相关章节：\n\n- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)\n\n## 最后用一句话把它们串起来\n\n如果你只想记一条总线索，可以记这个：\n\n```text\nmessages / prompt / query state\n  管本轮输入和继续理由\n\ntools / permissions / hooks\n  管动作怎么安全执行\n\nmemory / task / schedule\n  管跨轮、跨会话的持久工作\n\nruntime task / team / worktree\n  管当前执行车道\n\nmcp\n  管系统怎样向外接能力\n```\n\n这份总表最好配合 [`s00-architecture-overview.md`](./s00-architecture-overview.md) 和 [`entity-map.md`](./entity-map.md) 一起看。\n\n## 教学边界\n\n这份总表只负责做两件事：\n\n- 帮你确认一个状态到底属于哪一层\n- 帮你确认这个状态大概长什么样\n\n它不负责穷举真实系统里的每一个字段、每一条兼容分支、每一种产品化补丁。\n\n如果你已经知道某个状态归谁管、什么时候创建、什么时候销毁，再回到对应章节看执行路径，理解会顺很多。\n"
  },
  {
    "version": null,
    "slug": "entity-map",
    "locale": "zh",
    "title": "Entity Map (系统实体边界图)",
    "kind": "bridge",
    "filename": "entity-map.md",
    "content": "# Entity Map (系统实体边界图)\n\n> 这份文档不是某一章的正文，而是一张“别再混词”的地图。  \n> 到了仓库后半程，真正让读者困惑的往往不是代码，而是：\n>\n> **同一个系统里，为什么会同时出现这么多看起来很像、但其实不是一回事的实体。**\n\n## 这张图和另外几份桥接文档怎么分工\n\n- 这份图先回答：一个词到底属于哪一层。\n- [`glossary.md`](./glossary.md) 先回答：这个词到底是什么意思。\n- [`data-structures.md`](./data-structures.md) 再回答：这个词落到代码里时，状态长什么样。\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) 专门补“工作图任务”和“运行时任务”的分层。\n- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md) 专门补 MCP 平台层不是只有 tools。\n\n## 先给一个总图\n\n```text\n对话层\n  - message\n  - prompt block\n  - reminder\n\n动作层\n  - tool call\n  - tool result\n  - hook event\n\n工作层\n  - work-graph task\n  - runtime task\n  - protocol request\n\n执行层\n  - subagent\n  - teammate\n  - worktree lane\n\n平台层\n  - mcp server\n  - mcp capability\n  - memory record\n```\n\n## 最容易混淆的 8 对概念\n\n### 1. Message vs Prompt Block\n\n| 实体 | 它是什么 | 它不是什么 | 常见位置 |\n|---|---|---|---|\n| `Message` | 对话历史中的一条消息 | 不是长期系统规则 | `messages[]` |\n| `Prompt Block` | system prompt 内的一段稳定说明 | 不是某一轮刚发生的事件 | prompt builder |\n\n简单记法：\n\n- message 更像“对话内容”\n- prompt block 更像“系统说明”\n\n### 2. Todo / Plan vs Task\n\n| 实体 | 它是什么 | 它不是什么 |\n|---|---|---|\n| `todo / plan` | 当前轮或当前阶段的过程性安排 | 不是长期持久化工作图 |\n| `task` | 持久化的工作节点 | 不是某一轮的临时思路 |\n\n### 3. Work-Graph Task vs Runtime Task\n\n| 实体 | 它是什么 | 它不是什么 |\n|---|---|---|\n| `work-graph task` | 任务板上的工作节点 | 不是系统里活着的执行单元 |\n| `runtime task` | 当前正在执行的后台/agent/monitor 槽位 | 不是依赖图节点 |\n\n这对概念是整个仓库后半程最关键的区分之一。\n\n### 4. Subagent vs Teammate\n\n| 实体 | 它是什么 | 它不是什么 |\n|---|---|---|\n| `subagent` | 一次性委派执行者 | 不是长期在线成员 |\n| `teammate` | 持久存在、可重复接活的队友 | 不是一次性摘要工具 |\n\n### 5. Protocol Request vs Normal Message\n\n| 实体 | 它是什么 | 它不是什么 |\n|---|---|---|\n| `normal message` | 自由文本沟通 | 不是可追踪的审批流程 |\n| `protocol request` | 带 request_id 的结构化请求 | 不是随便说一句话 |\n\n### 6. Worktree vs Task\n\n| 实体 | 它是什么 | 它不是什么 |\n|---|---|---|\n| `task` | 说明要做什么 | 不是目录 |\n| `worktree` | 说明在哪做 | 不是工作目标 |\n\n### 7. Memory vs CLAUDE.md\n\n| 实体 | 它是什么 | 它不是什么 |\n|---|---|---|\n| `memory` | 跨会话仍有价值、但不易从当前代码直接推出来的信息 | 不是项目规则文件 |\n| `CLAUDE.md` | 长期规则、约束和说明 | 不是用户偏好或项目动态背景 |\n\n### 8. MCP Server vs MCP Tool\n\n| 实体 | 它是什么 | 它不是什么 |\n|---|---|---|\n| `MCP server` | 外部能力提供者 | 不是单个工具定义 |\n| `MCP tool` | 某个 server 暴露出来的一项具体能力 | 不是完整平台连接本身 |\n\n## 一张“是什么 / 存在哪里”的速查表\n\n| 实体 | 主要作用 | 典型存放位置 |\n|---|---|---|\n| `Message` | 当前对话历史 | `messages[]` |\n| `PromptParts` | system prompt 的组装片段 | prompt builder |\n| `PermissionRule` | 工具执行前的决策规则 | settings / session state |\n| `HookEvent` | 某个时机触发的扩展点 | hook config |\n| `MemoryEntry` | 跨会话有价值信息 | `.memory/` |\n| `TaskRecord` | 持久化工作节点 | `.tasks/` |\n| `RuntimeTaskState` | 正在执行的任务槽位 | runtime task manager |\n| `TeamMember` | 持久队友 | `.team/config.json` |\n| `MessageEnvelope` | 队友间结构化消息 | `.team/inbox/*.jsonl` |\n| `RequestRecord` | 审批/关机等协议状态 | request tracker |\n| `WorktreeRecord` | 隔离工作目录记录 | `.worktrees/index.json` |\n| `MCPServerConfig` | 外部 server 配置 | plugin / settings |\n\n## 后半程推荐怎么记\n\n如果你到了 `s15` 以后开始觉得名词多，可以只记这条线：\n\n```text\nmessage / prompt\n   管输入\n\ntool / permission / hook\n   管动作\n\ntask / runtime task / protocol\n   管工作推进\n\nsubagent / teammate / worktree\n   管执行者和执行车道\n\nmcp / memory / claude.md\n   管平台外延和长期上下文\n```\n\n## 初学者最容易心智打结的地方\n\n### 1. 把“任务”这个词用在所有层\n\n这是最常见的混乱来源。\n\n所以建议你在写正文时，尽量直接写全：\n\n- 工作图任务\n- 运行时任务\n- 后台任务\n- 协议请求\n\n不要都叫“任务”。\n\n### 2. 把队友和子 agent 混成一类\n\n如果生命周期不同，就不是同一类实体。\n\n### 3. 把 worktree 当成 task 的别名\n\n一个是“做什么”，一个是“在哪做”。\n\n### 4. 把 memory 当成通用笔记本\n\n它不是。它只保存很特定的一类长期信息。\n\n## 这份图应该怎么用\n\n最好的用法不是读一遍背下来，而是：\n\n- 每次你发现两个词开始混\n- 先来这张图里确认它们是不是一个层级\n- 再回去读对应章节\n\n如果你确认“不在一个层级”，下一步最好立刻去找它们对应的数据结构，而不是继续凭感觉读正文。\n\n## 教学边界\n\n这张图只解决“实体边界”这一个问题。\n\n它不负责展开每个实体的全部字段，也不负责把所有产品化分支一起讲完。\n\n你可以把它当成一张分层地图：\n\n- 先确认词属于哪一层\n- 再去对应章节看机制\n- 最后去 [`data-structures.md`](./data-structures.md) 看状态形状\n\n## 一句话记住\n\n**一个结构完整的系统最怕的不是功能多，而是实体边界不清；边界一清，很多复杂度会自动塌下来。**\n"
  },
  {
    "version": null,
    "slug": "glossary",
    "locale": "zh",
    "title": "Glossary (术语表)",
    "kind": "bridge",
    "filename": "glossary.md",
    "content": "# Glossary (术语表)\n\n> 这份术语表只收录本仓库主线里最重要、最容易让初学者卡住的词。  \n> 如果某个词你看着眼熟但说不清它到底是什么，先回这里。\n\n## 推荐联读\n\n如果你不是单纯查词，而是已经开始分不清“这些词分别活在哪一层”，建议按这个顺序一起看：\n\n- 先看 [`entity-map.md`](./entity-map.md)：搞清每个实体属于哪一层。\n- 再看 [`data-structures.md`](./data-structures.md)：搞清这些词真正落成什么状态结构。\n- 如果你卡在“任务”这个词上，再看 [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)。\n- 如果你卡在 MCP 不只等于 tools，再看 [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)。\n\n## Agent\n\n在这套仓库里，`agent` 指的是：  \n**一个能根据输入做判断，并且会调用工具去完成任务的模型。**\n\n你可以简单理解成：\n\n- 模型负责思考\n- harness 负责给模型工作环境\n\n## Harness\n\n`harness` 可以理解成“给 agent 准备好的工作台”。\n\n它包括：\n\n- 工具\n- 文件系统\n- 权限\n- 提示词\n- 记忆\n- 任务系统\n\n模型本身不是 harness。  \nharness 也不是模型。\n\n## Agent Loop\n\n`agent loop` 是系统反复执行的一条主循环：\n\n1. 把当前上下文发给模型\n2. 看模型是要直接回答，还是要调工具\n3. 如果调工具，就执行工具\n4. 把工具结果写回上下文\n5. 再继续下一轮\n\n没有这条循环，就没有 agent 系统。\n\n## Message / Messages\n\n`message` 是一条消息。  \n`messages` 是消息列表。\n\n它通常包含：\n\n- 用户消息\n- assistant 消息\n- tool_result 消息\n\n这份列表就是 agent 最主要的工作记忆。\n\n## Tool\n\n`tool` 是模型可以调用的一种动作。\n\n例如：\n\n- 读文件\n- 写文件\n- 改文件\n- 跑 shell 命令\n- 搜索文本\n\n模型并不直接执行系统命令。  \n模型只是说“我要调哪个工具、传什么参数”，真正执行的是你的代码。\n\n## Tool Schema\n\n`tool schema` 是工具的输入说明。\n\n它告诉模型：\n\n- 这个工具叫什么\n- 这个工具做什么\n- 需要哪些参数\n- 参数是什么类型\n\n可以把它想成“工具使用说明书”。\n\n## Dispatch Map\n\n`dispatch map` 是一张映射表：\n\n```python\n{\n    \"read_file\": read_file_handler,\n    \"write_file\": write_file_handler,\n    \"bash\": bash_handler,\n}\n```\n\n意思是：\n\n- 模型说要调用 `read_file`\n- 代码就去表里找到 `read_file_handler`\n- 然后执行它\n\n## Stop Reason\n\n`stop_reason` 是模型这一轮为什么停下来的原因。\n\n常见的有：\n\n- `end_turn`：模型说完了\n- `tool_use`：模型要调用工具\n- `max_tokens`：模型输出被截断了\n\n它决定主循环下一步怎么走。\n\n## Context\n\n`context` 是模型当前能看到的信息总和。\n\n包括：\n\n- `messages`\n- system prompt\n- 动态补充信息\n- tool_result\n\n上下文不是永久记忆。  \n上下文是“这一轮工作时当前摆在桌上的东西”。\n\n## Compact / Compaction\n\n`compact` 指压缩上下文。\n\n因为对话越长，模型能看到的历史就越多，成本和混乱也会一起增加。\n\n压缩的目标不是“删除有用信息”，而是：\n\n- 保留真正关键的内容\n- 去掉重复和噪声\n- 给后面的轮次腾空间\n\n## Subagent\n\n`subagent` 是从当前 agent 派生出来的一个子任务执行者。\n\n它最重要的价值是：\n\n**把一个大任务放到独立上下文里处理，避免污染父上下文。**\n\n## Fork\n\n`fork` 在本仓库语境里，指一种子 agent 启动方式：\n\n- 不是从空白上下文开始\n- 而是先继承父 agent 的已有上下文\n\n这适合“子任务必须理解当前讨论背景”的场景。\n\n## Permission\n\n`permission` 就是“这个工具调用能不能执行”。\n\n一个好的权限系统通常要回答三件事：\n\n- 应不应该直接拒绝\n- 能不能自动允许\n- 剩下的是不是要问用户\n\n## Permission Mode\n\n`permission mode` 是权限系统的工作模式。\n\n例如：\n\n- `default`：默认询问\n- `plan`：只允许读，不允许写\n- `auto`：简单安全的操作自动过，危险操作再问\n\n## Hook\n\n`hook` 是一个插入点。\n\n意思是：  \n在不改主循环代码的前提下，在某个时机额外执行一段逻辑。\n\n例如：\n\n- 工具调用前先检查一下\n- 工具调用后追加一条审计信息\n\n## Memory\n\n`memory` 是跨会话保存的信息。\n\n但不是所有东西都该存 memory。\n\n适合存 memory 的，通常是：\n\n- 用户长期偏好\n- 多次出现的重要反馈\n- 未来别的会话仍然有价值的信息\n\n## System Prompt\n\n`system prompt` 是系统级说明。\n\n它告诉模型：\n\n- 你是谁\n- 你能做什么\n- 你有哪些规则\n- 你应该如何协作\n\n它比普通用户消息更稳定。\n\n## System Reminder\n\n`system reminder` 是每一轮临时追加的动态提醒。\n\n例如：\n\n- 当前目录\n- 当前日期\n- 某个本轮才需要的额外上下文\n\n它和稳定的 system prompt 不是一回事。\n\n## Task\n\n`task` 是持久化任务系统里的一个任务节点。\n\n一个 task 通常不只是一句待办事项，还会带：\n\n- 状态\n- 描述\n- 依赖关系\n- owner\n\n## Dependency Graph\n\n`dependency graph` 指任务之间的依赖关系图。\n\n最简单的理解：\n\n- A 做完，B 才能开始\n- C 和 D 可以并行\n- E 要等 C 和 D 都完成\n\n这类结构能帮助 agent 判断：\n\n- 现在能做什么\n- 什么被卡住了\n- 什么能同时做\n\n## Worktree\n\n`worktree` 是 Git 提供的一个机制：\n\n同一个仓库，可以在多个不同目录里同时展开多个工作副本。\n\n它的价值是：\n\n- 并行做多个任务\n- 不互相污染文件改动\n- 便于多 agent 并行工作\n\n## MCP\n\n`MCP` 是 Model Context Protocol。\n\n你可以先把它理解成一套统一接口，让 agent 能接入外部工具。\n\n它解决的核心问题是：\n\n- 工具不必都写死在主程序里\n- 可以通过统一协议接入外部能力\n\n如果你已经知道“能接外部工具”，但开始分不清 server、connection、tool、resource、prompt 这些层，继续看：\n\n- [`data-structures.md`](./data-structures.md)\n- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)\n\n## Runtime Task\n\n`runtime task` 指的是：\n\n> 系统当前正在运行、等待完成、或者刚刚结束的一条执行单元。\n\n例如：\n\n- 一个后台 `pytest`\n- 一个正在工作的 teammate\n- 一个正在运行的 monitor\n\n它和 `task` 不一样。\n\n- `task` 更像工作目标\n- `runtime task` 更像执行槽位\n\n如果你总把这两个词混掉，不要只在正文里来回翻，直接去看：\n\n- [`entity-map.md`](./entity-map.md)\n- [`data-structures.md`](./data-structures.md)\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n\n## Teammate\n\n`teammate` 是长期存在的队友 agent。\n\n它和 `subagent` 的区别是：\n\n- `subagent`：一次性委派，干完就结束\n- `teammate`：长期存在，可以反复接任务\n\n如果你发现自己开始把这两个词混用，说明你需要回看：\n\n- `s04`\n- `s15`\n- `entity-map.md`\n\n## Protocol\n\n`protocol` 就是一套提前约好的协作规则。\n\n它回答的是：\n\n- 消息应该长什么样\n- 收到以后要怎么处理\n- 批准、拒绝、超时这些状态怎么记录\n\n在团队章节里，它最常见的形状是：\n\n```text\nrequest\n  ->\nresponse\n  ->\nstatus update\n```\n\n## Envelope\n\n`envelope` 本意是“信封”。\n\n在程序里，它表示：\n\n> 把正文和一些元信息一起包起来的一条结构化记录。\n\n例如一条协议消息里，正文之外还会附带：\n\n- `from`\n- `to`\n- `request_id`\n- `timestamp`\n\n这整包东西，就可以叫一个 `envelope`。\n\n## State Machine\n\n`state machine` 不是很玄的高级理论。\n\n你可以先把它理解成：\n\n> 一张“状态可以怎么变化”的规则表。\n\n例如：\n\n```text\npending -> approved\npending -> rejected\npending -> expired\n```\n\n这就是一个最小状态机。\n\n## Router\n\n`router` 可以简单理解成“分发器”。\n\n它的任务是：\n\n- 看请求属于哪一类\n- 把它送去正确的处理路径\n\n例如工具层里：\n\n- 本地工具走本地 handler\n- `mcp__...` 工具走 MCP client\n\n## Control Plane\n\n`control plane` 可以理解成“负责协调和控制的一层”。\n\n它通常不直接产出最终业务结果，  \n而是负责决定：\n\n- 谁来执行\n- 在什么环境里执行\n- 有没有权限\n- 执行后要不要通知别的模块\n\n这个词第一次看到容易怕。  \n但在本仓库里，你只需要把它先记成：\n\n> 不直接干活，负责协调怎么干活的一层。\n\n## Capability\n\n`capability` 就是“能力项”。\n\n例如在 MCP 里，能力不只可能是工具，还可能包括：\n\n- tools\n- resources\n- prompts\n- elicitation\n\n所以 `capability` 比 `tool` 更宽。\n\n## Resource\n\n`resource` 可以理解成：\n\n> 一个可读取、可引用、但不一定是“执行动作”的外部内容入口。\n\n例如：\n\n- 一份文档\n- 一个只读配置\n- 一块可被模型读取的数据内容\n\n它和 `tool` 的区别是：\n\n- `tool` 更像动作\n- `resource` 更像可读取内容\n\n## Elicitation\n\n`elicitation` 可以先理解成：\n\n> 外部系统反过来向用户要补充输入。\n\n也就是说，不再只是 agent 主动调用外部能力。  \n外部能力也可能说：\n\n“我还缺一点信息，请你补一下。”\n\n## 最容易混的几对词\n\n如果你是初学者，下面这几对词最值得一起记。\n\n| 词对 | 最简单的区分方法 |\n|---|---|\n| `message` vs `system prompt` | 一个更像对话内容，一个更像系统说明 |\n| `todo` vs `task` | 一个更像临时步骤，一个更像持久化工作节点 |\n| `task` vs `runtime task` | 一个管目标，一个管执行 |\n| `subagent` vs `teammate` | 一个一次性，一个长期存在 |\n| `tool` vs `resource` | 一个更像动作，一个更像内容 |\n| `permission` vs `hook` | 一个决定能不能做，一个决定要不要额外插入行为 |\n\n---\n\n如果读文档时又遇到新词卡住，优先回这里，不要硬顶着往后读。\n"
  },
  {
    "version": null,
    "slug": "s00-architecture-overview",
    "locale": "zh",
    "title": "s00: Architecture Overview (架构总览)",
    "kind": "bridge",
    "filename": "s00-architecture-overview.md",
    "content": "# s00: Architecture Overview (架构总览)\n\n> 这一章是全仓库的地图。  \n> 如果你只想先知道“整个系统到底由哪些模块组成、为什么是这个学习顺序”，先读这一章。\n\n## 先说结论\n\n这套仓库的主线是合理的。\n\n它最重要的优点，不是“章节数量多”，而是它把学习过程拆成了四个阶段：\n\n1. 先做出一个真的能工作的 agent。\n2. 再补安全、扩展、记忆和恢复。\n3. 再把临时清单升级成持久化任务系统。\n4. 最后再进入多 agent、隔离执行和外部工具平台。\n\n这个顺序符合初学者的心智。\n\n因为一个新手最需要的，不是先知道所有高级细节，而是先建立一条稳定的主线：\n\n`用户输入 -> 模型思考 -> 调工具 -> 拿结果 -> 继续思考 -> 完成`\n\n只要这条主线还没真正理解，后面的权限、hook、memory、MCP 都会变成一堆零散名词。\n\n## 这套仓库到底要还原什么\n\n本仓库的目标不是逐行复制任何一个生产仓库。\n\n本仓库真正要还原的是：\n\n- 主要模块有哪些\n- 模块之间怎么协作\n- 每个模块的核心职责是什么\n- 关键状态存在哪里\n- 一条请求在系统里是怎么流动的\n\n也就是说，我们追求的是：\n\n**设计主脉络高保真，而不是所有外围实现细节 1:1。**\n\n这很重要。\n\n如果你是为了自己从 0 到 1 做一个类似系统，那么你真正需要掌握的是：\n\n- 核心循环\n- 工具机制\n- 规划与任务\n- 上下文管理\n- 权限与扩展点\n- 持久化\n- 多 agent 协作\n- 工作隔离\n- 外部工具接入\n\n而不是打包、跨平台兼容、历史兼容分支或产品化胶水代码。\n\n## 三条阅读原则\n\n### 1. 先学最小版本，再学结构更完整的版本\n\n比如子 agent。\n\n最小版本只需要：\n\n- 父 agent 发一个子任务\n- 子 agent 用自己的 `messages`\n- 子 agent 返回一个摘要\n\n这已经能解决 80% 的核心问题：上下文隔离。\n\n等这个最小版本你真的能写出来，再去补更完整的能力，比如：\n\n- 继承父上下文的 fork 模式\n- 独立权限\n- 背景运行\n- worktree 隔离\n\n### 2. 每个新名词都必须先解释\n\n本仓库会经常用到一些词：\n\n- `state machine`\n- `dispatch map`\n- `dependency graph`\n- `frontmatter`\n- `worktree`\n- `MCP`\n\n如果你对这些词不熟，不要硬扛。  \n应该立刻去看术语表：[`glossary.md`](./glossary.md)\n\n如果你想先知道“这套仓库到底教什么、不教什么”，建议配合看：\n\n- [`teaching-scope.md`](./teaching-scope.md)\n\n如果你想先把最关键的数据结构建立成整体地图，可以配合看：\n\n- [`data-structures.md`](./data-structures.md)\n\n如果你已经知道章节顺序没问题，但一打开本地 `agents/*.py` 就会重新乱掉，建议再配合看：\n\n- [`s00f-code-reading-order.md`](./s00f-code-reading-order.md)\n\n### 3. 不把复杂外围细节伪装成“核心机制”\n\n好的教学，不是把一切都讲进去。\n\n好的教学，是把真正关键的东西讲完整，把不关键但很复杂的东西先拿掉。\n\n所以本仓库会刻意省略一些不属于主干的内容，比如：\n\n- 打包与发布\n- 企业策略接线\n- 遥测\n- 多客户端表层集成\n- 历史兼容层\n\n## 建议配套阅读的文档\n\n除了主线章节，我建议把下面两份文档当作全程辅助地图：\n\n| 文档 | 用途 |\n|---|---|\n| [`teaching-scope.md`](./teaching-scope.md) | 帮你分清哪些内容属于教学主线，哪些只是维护者侧补充 |\n| [`data-structures.md`](./data-structures.md) | 帮你集中理解整个系统的关键状态和数据结构 |\n| [`s00f-code-reading-order.md`](./s00f-code-reading-order.md) | 帮你把“章节顺序”和“本地代码阅读顺序”对齐，避免重新乱翻源码 |\n\n如果你已经读到中后半程，想把“章节之间缺的那一层”补上，再加看下面这些桥接文档：\n\n| 文档 | 它补的是什么 |\n|---|---|\n| [`s00d-chapter-order-rationale.md`](./s00d-chapter-order-rationale.md) | 为什么这套课要按现在这个顺序讲，哪些重排会把读者心智讲乱 |\n| [`s00e-reference-module-map.md`](./s00e-reference-module-map.md) | 参考仓库里真正重要的模块簇，和当前课程章节是怎样一一对应的 |\n| [`s00a-query-control-plane.md`](./s00a-query-control-plane.md) | 为什么一个更完整的系统不能只靠 `messages[] + while True` |\n| [`s00b-one-request-lifecycle.md`](./s00b-one-request-lifecycle.md) | 一条请求如何从用户输入一路流过 query、tools、permissions、tasks、teams、MCP 再回到主循环 |\n| [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) | 为什么工具层不只是 `tool_name -> handler` |\n| [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md) | 为什么 system prompt 不是模型完整输入的全部 |\n| [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) | 为什么任务板里的 task 和正在运行的 task 不是一回事 |\n| [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md) | 为什么 MCP 正文先讲 tools-first，但平台层还要再补一张地图 |\n| [`entity-map.md`](./entity-map.md) | 帮你把 message、task、runtime task、subagent、teammate、worktree、MCP server 这些实体彻底分开 |\n\n## 四阶段学习路径\n\n### 阶段 1：核心单 agent (`s01-s06`)\n\n目标：先做出一个能干活的 agent。\n\n| 章节 | 学什么 | 解决什么问题 |\n|---|---|---|\n| `s01` | Agent Loop | 没有循环，就没有 agent |\n| `s02` | Tool Use | 让模型从“会说”变成“会做” |\n| `s03` | Todo / Planning | 防止大任务乱撞 |\n| `s04` | Subagent | 防止上下文被大任务污染 |\n| `s05` | Skills | 按需拿知识，不把所有知识塞进提示词 |\n| `s06` | Context Compact | 防止上下文无限膨胀 |\n\n这一阶段结束后，你已经有了一个真正可运行的 coding agent 雏形。\n\n### 阶段 2：生产加固 (`s07-s11`)\n\n目标：让 agent 不只是能跑，而是更安全、更稳、更可扩展。\n\n| 章节 | 学什么 | 解决什么问题 |\n|---|---|---|\n| `s07` | Permission System | 危险操作先过权限关 |\n| `s08` | Hook System | 不改主循环也能扩展行为 |\n| `s09` | Memory System | 让真正有价值的信息跨会话存在 |\n| `s10` | System Prompt | 把系统说明、工具、约束组装成稳定输入 |\n| `s11` | Error Recovery | 出错后能恢复，而不是直接崩溃 |\n\n### 阶段 3：任务管理 (`s12-s14`)\n\n目标：把“聊天中的清单”升级成“磁盘上的任务图”。\n\n| 章节 | 学什么 | 解决什么问题 |\n|---|---|---|\n| `s12` | Task System | 大任务要有持久结构 |\n| `s13` | Background Tasks | 慢操作不应该卡住前台思考 |\n| `s14` | Cron Scheduler | 让系统能在未来自动做事 |\n\n### 阶段 4：多 agent 与外部系统 (`s15-s19`)\n\n目标：从单 agent 升级成真正的平台。\n\n| 章节 | 学什么 | 解决什么问题 |\n|---|---|---|\n| `s15` | Agent Teams | 让多个 agent 协作 |\n| `s16` | Team Protocols | 让协作有统一规则 |\n| `s17` | Autonomous Agents | 让 agent 自己找活、认领任务 |\n| `s18` | Worktree Isolation | 并行工作时互不踩目录 |\n| `s19` | MCP & Plugin | 接入外部工具与外部能力 |\n\n## 章节速查表：每章到底新增了哪一层状态\n\n很多读者读到中途会开始觉得：\n\n- 这一章到底是在加工具，还是在加状态\n- 这个机制是“输入层”的，还是“执行层”的\n- 学完这一章以后，我手里到底多了一个什么东西\n\n所以这里给一张全局速查表。  \n读每章以前，先看这一行；读完以后，再回来检查自己是不是真的吃透了这一行。\n\n| 章节 | 新增的核心结构 | 它接在系统哪一层 | 学完你应该会什么 |\n|---|---|---|---|\n| `s01` | `messages` / `LoopState` | 主循环 | 手写一个最小 agent 闭环 |\n| `s02` | `ToolSpec` / `ToolDispatchMap` | 工具层 | 把模型意图路由成真实动作 |\n| `s03` | `TodoItem` / `PlanState` | 过程规划层 | 让 agent 按步骤推进，而不是乱撞 |\n| `s04` | `SubagentContext` | 执行隔离层 | 把探索性工作丢进干净子上下文 |\n| `s05` | `SkillRegistry` / `SkillContent` | 知识注入层 | 只在需要时加载额外知识 |\n| `s06` | `CompactSummary` / `PersistedOutput` | 上下文管理层 | 控制上下文大小又不丢主线 |\n| `s07` | `PermissionRule` / `PermissionDecision` | 安全控制层 | 让危险动作先经过决策管道 |\n| `s08` | `HookEvent` / `HookResult` | 扩展控制层 | 不改主循环也能插入扩展逻辑 |\n| `s09` | `MemoryEntry` / `MemoryStore` | 持久上下文层 | 只把真正跨会话有价值的信息留下 |\n| `s10` | `PromptParts` / `SystemPromptBlock` | 输入组装层 | 把模型输入拆成可管理的管道 |\n| `s11` | `RecoveryState` / `TransitionReason` | 恢复控制层 | 出错后知道为什么继续、怎么继续 |\n| `s12` | `TaskRecord` / `TaskStatus` | 工作图层 | 把临时清单升级成持久化任务图 |\n| `s13` | `RuntimeTaskState` / `Notification` | 运行时执行层 | 让慢任务后台运行、稍后回送结果 |\n| `s14` | `ScheduleRecord` / `CronTrigger` | 定时触发层 | 让时间本身成为工作触发器 |\n| `s15` | `TeamMember` / `MessageEnvelope` | 多 agent 基础层 | 让队友长期存在、反复接活 |\n| `s16` | `ProtocolEnvelope` / `RequestRecord` | 协作协议层 | 让团队从自由聊天升级成结构化协作 |\n| `s17` | `ClaimPolicy` / `AutonomyState` | 自治调度层 | 让 agent 空闲时自己找活、恢复工作 |\n| `s18` | `WorktreeRecord` / `TaskBinding` | 隔离执行层 | 给并行任务分配独立工作目录 |\n| `s19` | `MCPServerConfig` / `CapabilityRoute` | 外部能力层 | 把外部能力并入系统主控制面 |\n\n## 整个系统的大图\n\n先看最重要的一张图：\n\n```text\nUser\n  |\n  v\nmessages[]\n  |\n  v\n+-------------------------+\n|  Agent Loop (s01)       |\n|                         |\n|  1. 组装输入            |\n|  2. 调模型              |\n|  3. 看 stop_reason      |\n|  4. 如果要调工具就执行   |\n|  5. 把结果写回 messages  |\n|  6. 继续下一轮           |\n+-------------------------+\n  |\n  +------------------------------+\n  |                              |\n  v                              v\nTool Pipeline                Context / State\n(s02, s07, s08)              (s03, s06, s09, s10, s11)\n  |                              |\n  v                              v\nTasks / Teams / Worktree / MCP (s12-s19)\n```\n\n你可以把它理解成三层：\n\n### 第一层：主循环\n\n这是系统心脏。\n\n它只做一件事：  \n**不停地推动“思考 -> 行动 -> 观察 -> 再思考”的循环。**\n\n### 第二层：横切机制\n\n这些机制不是替代主循环，而是“包在主循环周围”：\n\n- 权限\n- hooks\n- memory\n- prompt 组装\n- 错误恢复\n- 上下文压缩\n\n它们的作用，是让主循环更安全、更稳定、更聪明。\n\n### 第三层：更大的工作平台\n\n这些机制把单 agent 升级成更完整的系统：\n\n- 任务图\n- 后台任务\n- 多 agent 团队\n- worktree 隔离\n- MCP 外部工具\n\n## 你真正需要掌握的关键状态\n\n理解 agent，最重要的不是背很多功能名，而是知道**状态放在哪里**。\n\n下面是这个仓库里最关键的几类状态：\n\n### 1. 对话状态：`messages`\n\n这是 agent 当前上下文的主体。\n\n它保存：\n\n- 用户说了什么\n- 模型回复了什么\n- 调用了哪些工具\n- 工具返回了什么\n\n你可以把它想成 agent 的“工作记忆”。\n\n### 2. 工具注册表：`tools` / `handlers`\n\n这是一张“工具名 -> Python 函数”的映射表。\n\n这类结构常被叫做 `dispatch map`。\n\n意思很简单：\n\n- 模型说“我要调用 `read_file`”\n- 代码就去表里找 `read_file` 对应的函数\n- 找到以后执行\n\n### 3. 计划与任务状态：`todo` / `tasks`\n\n这部分保存：\n\n- 当前有哪些事要做\n- 哪些已经完成\n- 哪些被别的任务阻塞\n- 哪些可以并行\n\n### 4. 权限与策略状态\n\n这部分保存：\n\n- 当前权限模式是什么\n- 允许规则有哪些\n- 拒绝规则有哪些\n- 最近是否连续被拒绝\n\n### 5. 持久化状态\n\n这部分保存那些“不该跟着一次对话一起消失”的东西：\n\n- memory 文件\n- task 文件\n- transcript\n- background task 输出\n- worktree 绑定信息\n\n## 如果你想做出结构完整的版本，至少要有哪些数据结构\n\n如果你的目标是自己写一个结构完整、接近真实主脉络的类似系统，最低限度要把下面这些数据结构设计清楚：\n\n```python\nclass AppState:\n    messages: list\n    tools: dict\n    tool_schemas: list\n\n    todo: object | None\n    tasks: object | None\n\n    permissions: object | None\n    hooks: object | None\n    memories: object | None\n    prompt_builder: object | None\n\n    compact_state: dict\n    recovery_state: dict\n\n    background: object | None\n    cron: object | None\n\n    teammates: object | None\n    worktree_session: dict | None\n    mcp_clients: dict\n```\n\n这不是要求你一开始就把这些全写完。\n\n这张表的作用只是告诉你：\n\n**一个像样的 agent 系统，不只是 `messages + tools`。**\n\n它最终会长成一个带很多子模块的状态系统。\n\n## 一条请求是怎么流动的\n\n```text\n1. 用户发来任务\n2. 系统组装 prompt 和上下文\n3. 模型返回普通文本，或者返回 tool_use\n4. 如果返回 tool_use：\n   - 先过 permission\n   - 再过 hook\n   - 然后执行工具\n   - 把 tool_result 写回 messages\n5. 主循环继续\n6. 如果任务太大：\n   - 可能写入 todo / tasks\n   - 可能派生 subagent\n   - 可能触发 compact\n   - 可能走 background / team / worktree / MCP\n7. 直到模型结束这一轮\n```\n\n这条流是全仓库最重要的主脉络。\n\n你在后面所有章节里看到的机制，本质上都只是插在这条流的不同位置。\n\n## 读者最容易混淆的几组概念\n\n### `Todo` 和 `Task` 不是一回事\n\n- `Todo`：轻量、临时、偏会话内\n- `Task`：持久化、带状态、带依赖关系\n\n### `Memory` 和 `Context` 不是一回事\n\n- `Context`：这一轮工作临时需要的信息\n- `Memory`：未来别的会话也可能仍然有价值的信息\n\n### `Subagent` 和 `Teammate` 不是一回事\n\n- `Subagent`：通常是当前 agent 派生出来的一次性帮手\n- `Teammate`：更偏向长期存在于团队中的协作角色\n\n### `Prompt` 和 `System Reminder` 不是一回事\n\n- `System Prompt`：较稳定的系统级输入\n- `System Reminder`：每轮动态变化的补充上下文\n\n## 这套仓库刻意省略了什么\n\n为了让初学者能顺着学下去，本仓库不会把下面这些内容塞进主线：\n\n- 产品级启动流程里的全部外围初始化\n- 真实商业产品中的账号、策略、遥测、灰度等逻辑\n- 只服务于兼容性和历史负担的复杂分支\n- 某些非常复杂但教学收益很低的边角机制\n\n这不是因为这些东西“不存在”。\n\n而是因为对一个从 0 到 1 造类似系统的读者来说，主干先于枝叶。\n\n## 这一章之后怎么读\n\n推荐顺序：\n\n1. 先读 `s01` 和 `s02`\n2. 然后读 `s03` 到 `s06`\n3. 进入 `s07` 到 `s10`\n4. 接着补 `s11`\n5. 最后再读 `s12` 到 `s19`\n\n如果你在某一章觉得名词开始打结，回来看这一章和术语表就够了。\n\n---\n\n**一句话记住全仓库：**\n\n先做出能工作的最小循环，再一层一层给它补上规划、隔离、安全、记忆、任务、协作和外部能力。\n"
  },
  {
    "version": null,
    "slug": "s00a-query-control-plane",
    "locale": "zh",
    "title": "s00a: Query Control Plane (查询控制平面)",
    "kind": "bridge",
    "filename": "s00a-query-control-plane.md",
    "content": "# s00a: Query Control Plane (查询控制平面)\n\n> 这不是新的主线章节，而是一份桥接文档。  \n> 它用来回答一个问题：\n>\n> **为什么一个结构更完整的 agent，不会只靠 `messages[]` 和一个 `while True` 就够了？**\n\n## 这一篇为什么要存在\n\n主线里的 `s01` 会先教你做出一个最小可运行循环：\n\n```text\n用户输入\n  ->\n模型回复\n  ->\n如果要调工具就执行\n  ->\n把结果喂回去\n  ->\n继续下一轮\n```\n\n这条主线是对的，而且必须先学这个。\n\n但当系统开始长功能以后，真正支撑一个完整 harness 的，不再只是“循环”本身，而是：\n\n**一层专门负责管理查询过程的控制平面。**\n\n这一层在真实系统里通常会统一处理：\n\n- 当前对话消息\n- 当前轮次\n- 为什么继续下一轮\n- 是否正在恢复错误\n- 是否已经压缩过上下文\n- 是否需要切换输出预算\n- hook 是否暂时影响了结束条件\n\n如果不把这层讲出来，读者虽然能做出一个能跑的 demo，但很难自己把系统推到接近 95%-99% 的完成度。\n\n## 先解释几个名词\n\n### 什么是 query\n\n这里的 `query` 不是“数据库查询”。\n\n这里说的 query，更接近：\n\n> 系统为了完成用户当前这一次请求，而运行的一整段主循环过程。\n\n也就是说：\n\n- 用户说一句话\n- 系统可能要经过很多轮模型调用和工具调用\n- 最后才结束这一次请求\n\n这整段过程，就可以看成一条 query。\n\n### 什么是控制平面\n\n`控制平面` 这个词第一次看会有点抽象。\n\n它的意思其实很简单：\n\n> 不是直接做业务动作，而是负责协调、调度、决定流程怎么往下走的一层。\n\n在这里：\n\n- 模型回复内容，算“业务内容”\n- 工具执行结果，算“业务动作”\n- 决定“要不要继续下一轮、为什么继续、现在属于哪种继续”，这层就是控制平面\n\n### 什么是 transition\n\n`transition` 可以翻成“转移原因”。\n\n它回答的是：\n\n> 上一轮为什么没有结束，而是继续下一轮了？\n\n例如：\n\n- 因为工具刚执行完\n- 因为输出被截断，要续写\n- 因为刚做完压缩，要重试\n- 因为 hook 要求继续\n- 因为预算还允许继续\n\n## 最小心智模型\n\n先把 query 控制平面想成 3 层：\n\n```text\n1. 输入层\n   - messages\n   - system prompt\n   - user/system context\n\n2. 控制层\n   - 当前状态 state\n   - 当前轮 turn\n   - 当前继续原因 transition\n   - 恢复/压缩/预算等标记\n\n3. 执行层\n   - 调模型\n   - 执行工具\n   - 写回消息\n```\n\n它的工作不是“替代主循环”，而是：\n\n**让主循环从一个小 demo，升级成一个能管理很多分支和状态的系统。**\n\n## 为什么只靠 `messages[]` 不够\n\n很多初学者第一次实现 agent 时，会把所有状态都堆进 `messages[]`。\n\n这在最小 demo 里没问题。\n\n但一旦系统长出下面这些能力，就不够了：\n\n- 你要知道自己是不是已经做过一次 reactive compact\n- 你要知道输出被截断已经续写了几次\n- 你要知道这次继续是因为工具，还是因为错误恢复\n- 你要知道当前轮是否启用了特殊输出预算\n\n这些信息不是“对话内容”，而是“流程控制状态”。\n\n所以它们不该都硬塞进 `messages[]` 里。\n\n## 关键数据结构\n\n### 1. QueryParams\n\n这是进入 query 引擎时的外部输入。\n\n最小形状可以这样理解：\n\n```python\nparams = {\n    \"messages\": [...],\n    \"system_prompt\": \"...\",\n    \"user_context\": {...},\n    \"system_context\": {...},\n    \"tool_use_context\": {...},\n    \"fallback_model\": None,\n    \"max_output_tokens_override\": None,\n    \"max_turns\": None,\n}\n```\n\n它的作用是：\n\n- 带进来这次查询一开始已知的输入\n- 这些值大多不在每轮里随便乱改\n\n### 2. QueryState\n\n这才是跨迭代真正会变化的部分。\n\n最小教学版建议你把它显式做成一个结构：\n\n```python\nstate = {\n    \"messages\": [...],\n    \"tool_use_context\": {...},\n    \"continuation_count\": 0,\n    \"has_attempted_compact\": False,\n    \"max_output_tokens_override\": None,\n    \"stop_hook_active\": False,\n    \"turn_count\": 1,\n    \"transition\": None,\n}\n```\n\n它的价值在于：\n\n- 把“会变的流程状态”集中放在一起\n- 让每个 continue site 修改的是同一份 state，而不是散落在很多局部变量里\n\n### 3. TransitionReason\n\n建议你单独定义一组继续原因：\n\n```python\nTRANSITIONS = (\n    \"tool_result_continuation\",\n    \"max_tokens_recovery\",\n    \"compact_retry\",\n    \"transport_retry\",\n    \"stop_hook_continuation\",\n    \"budget_continuation\",\n)\n```\n\n这不是为了炫技。\n\n它的作用很实在：\n\n- 日志更清楚\n- 调试更清楚\n- 测试更清楚\n- 教学更清楚\n\n## 最小实现\n\n### 第一步：把外部输入和内部状态分开\n\n```python\ndef query(params):\n    state = {\n        \"messages\": params[\"messages\"],\n        \"tool_use_context\": params[\"tool_use_context\"],\n        \"continuation_count\": 0,\n        \"has_attempted_compact\": False,\n        \"max_output_tokens_override\": params.get(\"max_output_tokens_override\"),\n        \"turn_count\": 1,\n        \"transition\": None,\n    }\n```\n\n### 第二步：每一轮先读 state，再决定如何执行\n\n```python\nwhile True:\n    messages = state[\"messages\"]\n    transition = state[\"transition\"]\n    turn_count = state[\"turn_count\"]\n\n    response = call_model(...)\n    ...\n```\n\n### 第三步：所有“继续下一轮”的地方都写回 state\n\n```python\nif response.stop_reason == \"tool_use\":\n    state[\"messages\"] = append_tool_results(...)\n    state[\"transition\"] = \"tool_result_continuation\"\n    state[\"turn_count\"] += 1\n    continue\n\nif response.stop_reason == \"max_tokens\":\n    state[\"messages\"].append({\"role\": \"user\", \"content\": CONTINUE_MESSAGE})\n    state[\"continuation_count\"] += 1\n    state[\"transition\"] = \"max_tokens_recovery\"\n    continue\n```\n\n这一点非常关键。\n\n**不要只做 `continue`，要知道自己为什么 continue。**\n\n## 一张真正清楚的心智图\n\n```text\nparams\n  |\n  v\ninit state\n  |\n  v\nquery loop\n  |\n  +-- normal assistant end --------------> terminal\n  |\n  +-- tool_use --------------------------> write tool_result -> transition=tool_result_continuation\n  |\n  +-- max_tokens ------------------------> inject continue -> transition=max_tokens_recovery\n  |\n  +-- prompt too long -------------------> compact -> transition=compact_retry\n  |\n  +-- transport error -------------------> backoff -> transition=transport_retry\n  |\n  +-- stop hook asks to continue --------> transition=stop_hook_continuation\n```\n\n## 它和 `s01`、`s11` 的关系\n\n- `s01` 负责建立“最小主循环”\n- `s11` 负责建立“错误恢复分支”\n- 这一篇负责把两者再往上抽象一层，解释为什么一个更完整的系统会出现一个 query control plane\n\n所以这篇不是替代主线，而是把主线补完整。\n\n## 初学者最容易犯的错\n\n### 1. 把所有控制状态都塞进消息里\n\n这样日志和调试都会很难看，也会让消息层和控制层混在一起。\n\n### 2. `continue` 了，但没有记录为什么继续\n\n短期看起来没问题，系统一复杂就会变成黑盒。\n\n### 3. 每个分支都直接改很多局部变量\n\n这样后面你很难看出“哪些状态是跨轮共享的”。\n\n### 4. 把 query loop 讲成“只是一个 while True”\n\n这对最小 demo 是真话，对一个正在长出控制面的 harness 就不是完整真话了。\n\n## 教学边界\n\n这篇最重要的，不是把所有控制状态一次列满，而是先让你守住三件事：\n\n- query loop 不只是 `while True`，而是一条带着共享状态往前推进的控制面\n- 每次 `continue` 都应该有明确原因，而不是黑盒跳转\n- 消息层、工具回写、压缩恢复、重试恢复，最终都要回到同一份 query 状态上\n\n更细的 `transition taxonomy`、预算跟踪、prefetch 等扩展，可以放到你把这条最小控制面真正手搓稳定以后再补。\n\n## 一句话记住\n\n**更完整的 query loop 不只是“循环”，而是“拿着一份跨轮状态不断推进的查询控制平面”。**\n"
  },
  {
    "version": null,
    "slug": "s00b-one-request-lifecycle",
    "locale": "zh",
    "title": "s00b: One Request Lifecycle (一次请求的完整生命周期)",
    "kind": "bridge",
    "filename": "s00b-one-request-lifecycle.md",
    "content": "# s00b: One Request Lifecycle (一次请求的完整生命周期)\n\n> 这是一份桥接文档。  \n> 它不替代主线章节，而是把整套系统串成一条真正连续的执行链。\n>\n> 它要回答的问题是：\n>\n> **用户的一句话，进入系统以后，到底是怎样一路流动、分发、执行、再回到主循环里的？**\n\n## 为什么必须补这一篇\n\n很多读者在按顺序看教程时，会逐章理解：\n\n- `s01` 讲循环\n- `s02` 讲工具\n- `s03` 讲规划\n- `s07` 讲权限\n- `s09` 讲 memory\n- `s12-s19` 讲任务、多 agent、MCP\n\n每章单看都能懂。\n\n但一旦开始自己实现，就会很容易卡住：\n\n- 这些模块到底谁先谁后？\n- 一条请求进来时，先走 prompt，还是先走 memory？\n- 工具执行前，权限和 hook 在哪一层？\n- task、runtime task、teammate、worktree、MCP 到底是在一次请求里的哪个阶段介入？\n\n所以你需要一张“纵向流程图”。\n\n## 先给一条最重要的总图\n\n```text\n用户请求\n  |\n  v\nQuery State 初始化\n  |\n  v\n组装 system prompt / messages / reminders\n  |\n  v\n调用模型\n  |\n  +-- 普通回答 -------------------------------> 结束本次请求\n  |\n  +-- tool_use\n        |\n        v\n    Tool Router\n        |\n        +-- 权限判断\n        +-- Hook 拦截/注入\n        +-- 本地工具 / MCP / agent / task / team\n        |\n        v\n    执行结果\n        |\n        +-- 可能写入 task / runtime task / memory / worktree 状态\n        |\n        v\n    tool_result 写回 messages\n        |\n        v\n    Query State 更新\n        |\n        v\n    下一轮继续\n```\n\n你可以把整条链先理解成三层：\n\n1. `Query Loop`\n2. `Tool Control Plane`\n3. `Platform State`\n\n## 第 1 段：用户请求进入查询控制平面\n\n当用户说：\n\n```text\n修复 tests/test_auth.py 的失败，并告诉我原因\n```\n\n系统最先做的，不是立刻跑工具，而是先为这次请求建立一份查询状态。\n\n最小可以理解成：\n\n```python\nquery_state = {\n    \"messages\": [{\"role\": \"user\", \"content\": user_text}],\n    \"turn_count\": 1,\n    \"transition\": None,\n    \"tool_use_context\": {...},\n}\n```\n\n这里的重点是：\n\n**这次请求不是“单次 API 调用”，而是一段可能包含很多轮的查询过程。**\n\n如果你对这一层还不够熟，先回看：\n\n- [`s01-the-agent-loop.md`](./s01-the-agent-loop.md)\n- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)\n\n## 第 2 段：组装本轮真正送给模型的输入\n\n主循环不会直接把原始 `messages` 裸发出去。\n\n在更完整的系统里，它通常会先组装：\n\n- system prompt blocks\n- 规范化后的 messages\n- memory section\n- 当前轮 reminder\n- 工具清单\n\n也就是说，真正发给模型的通常是：\n\n```text\nsystem prompt\n+ normalized messages\n+ tools\n+ optional reminders / attachments\n```\n\n这里涉及的章节是：\n\n- `s09` memory\n- `s10` system prompt\n- `s10a` message & prompt pipeline\n\n这一段的核心心智是：\n\n**system prompt 不是全部输入，它只是输入管道中的一段。**\n\n## 第 3 段：模型产出两类东西\n\n模型这一轮的输出，最关键地分成两种：\n\n### 第一种：普通回复\n\n如果模型直接给出结论或说明，本次请求可能就结束了。\n\n### 第二种：动作意图\n\n也就是工具调用。\n\n例如：\n\n```text\nread_file(\"tests/test_auth.py\")\nbash(\"pytest tests/test_auth.py -q\")\ntodo([...])\nload_skill(\"code-review\")\ntask_create(...)\nmcp__postgres__query(...)\n```\n\n这时候系统真正收到的，不只是“文本”，而是：\n\n> 模型想让真实世界发生某些动作。\n\n## 第 4 段：工具路由层接管动作意图\n\n一旦出现 `tool_use`，系统就进入工具控制平面。\n\n这一层至少要回答：\n\n1. 这是什么工具？\n2. 它应该路由到哪类能力来源？\n3. 执行前要不要先过权限？\n4. hook 有没有要拦截或补充？\n5. 它执行时能访问哪些共享状态？\n\n最小图可以这样看：\n\n```text\ntool_use\n  |\n  v\nTool Router\n  |\n  +-- native tool handler\n  +-- MCP client\n  +-- agent/team/task handler\n```\n\n如果你对这一层不够清楚，回看：\n\n- [`s02-tool-use.md`](./s02-tool-use.md)\n- [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)\n\n## 第 5 段：权限系统决定“能不能执行”\n\n不是所有动作意图都应该直接变成真实执行。\n\n例如：\n\n- 写文件\n- 跑 bash\n- 改工作目录\n- 调外部服务\n\n这时会先进入权限判断：\n\n```text\ndeny rules\n  -> mode\n  -> allow rules\n  -> ask user\n```\n\n权限系统处理的是：\n\n> 这次动作是否允许发生。\n\n相关章节：\n\n- [`s07-permission-system.md`](./s07-permission-system.md)\n\n## 第 6 段：Hook 可以在边上做扩展\n\n通过权限检查以后，系统还可能在工具执行前后跑 hook。\n\n你可以把 hook 理解成：\n\n> 不改主循环主干，也能插入自定义行为的扩展点。\n\n例如：\n\n- 执行前记录日志\n- 执行后做额外检查\n- 根据结果注入额外提醒\n\n相关章节：\n\n- [`s08-hook-system.md`](./s08-hook-system.md)\n\n## 第 7 段：真正执行动作，并影响不同层的状态\n\n这是很多人最容易低估的一段。\n\n工具执行结果，不只是“一段文本输出”。\n\n它还可能修改系统别的状态层。\n\n### 例子 1：规划状态\n\n如果工具是 `todo`，它会更新的是当前会话计划。\n\n相关章节：\n\n- [`s03-todo-write.md`](./s03-todo-write.md)\n\n### 例子 2：持久任务图\n\n如果工具是 `task_create` / `task_update`，它会修改磁盘上的任务板。\n\n相关章节：\n\n- [`s12-task-system.md`](./s12-task-system.md)\n\n### 例子 3：运行时任务\n\n如果工具启动了后台 bash、后台 agent 或监控任务，它会创建 runtime task。\n\n相关章节：\n\n- [`s13-background-tasks.md`](./s13-background-tasks.md)\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n\n### 例子 4：多 agent / teammate\n\n如果工具是 `delegate`、`spawn_agent` 一类，它会在平台层生成新的执行单元。\n\n相关章节：\n\n- [`s15-agent-teams.md`](./s15-agent-teams.md)\n- [`s16-team-protocols.md`](./s16-team-protocols.md)\n- [`s17-autonomous-agents.md`](./s17-autonomous-agents.md)\n\n### 例子 5：worktree\n\n如果系统要为某个任务提供隔离工作目录，这会影响文件系统级执行环境。\n\n相关章节：\n\n- [`s18-worktree-task-isolation.md`](./s18-worktree-task-isolation.md)\n\n### 例子 6：MCP\n\n如果调用的是外部 MCP 能力，那么执行主体可能根本不在本地 handler，而在外部能力端。\n\n相关章节：\n\n- [`s19-mcp-plugin.md`](./s19-mcp-plugin.md)\n- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)\n\n## 第 8 段：执行结果被包装回消息流\n\n不管执行落在哪一层，最后都要回到同一个位置：\n\n```text\ntool_result -> messages\n```\n\n这是整个系统最核心的闭环。\n\n因为无论工具背后多复杂，模型下一轮真正能继续工作的依据，仍然是：\n\n> 系统把执行结果重新写回了它可见的消息流。\n\n这也是为什么 `s01` 永远是根。\n\n## 第 9 段：主循环根据结果决定下一轮是否继续\n\n当 `tool_result` 写回以后，查询状态也会一起更新：\n\n- `messages` 变了\n- `turn_count` 增加了\n- `transition` 被记录成某种续行原因\n\n这时系统就进入下一轮。\n\n如果中间发生下面这些情况，控制平面还会继续介入：\n\n- 上下文太长，需要压缩\n- 输出被截断，需要续写\n- 请求失败，需要恢复\n\n相关章节：\n\n- [`s06-context-compact.md`](./s06-context-compact.md)\n- [`s11-error-recovery.md`](./s11-error-recovery.md)\n\n## 第 10 段：哪些信息不会跟着一次请求一起结束\n\n这也是非常容易混的地方。\n\n一次请求结束后，并不是所有状态都随之消失。\n\n### 会跟着当前请求结束的\n\n- 当前轮 messages 中的临时推进过程\n- 会话内 todo 状态\n- 当前轮 reminder\n\n### 可能跨请求继续存在的\n\n- memory\n- 持久任务图\n- runtime task 输出\n- worktree\n- MCP 连接状态\n\n所以你要逐渐学会区分：\n\n```text\nquery-scope state\nsession-scope state\nproject-scope state\nplatform-scope state\n```\n\n## 用一个完整例子串一次\n\n还是用这个请求：\n\n```text\n修复 tests/test_auth.py 的失败，并告诉我原因\n```\n\n系统可能会这样流动：\n\n1. 用户请求进入 `QueryState`\n2. system prompt + memory + tools 被组装好\n3. 模型先调用 `todo`，写出三步计划\n4. 模型调用 `read_file(\"tests/test_auth.py\")`\n5. 工具路由到本地文件读取 handler\n6. 读取结果包装成 `tool_result` 写回消息流\n7. 下一轮模型调用 `bash(\"pytest tests/test_auth.py -q\")`\n8. 权限系统判断这条命令是否可执行\n9. 执行测试，输出太长则先落盘并留预览\n10. 失败日志回到消息流\n11. 模型再读实现文件并修改代码\n12. 修改后再跑测试\n13. 如果对话变长，`s06` 触发压缩\n14. 如果任务被拆给子 agent，`s15-s17` 介入\n15. 最后模型输出结论，本次请求结束\n\n你会发现：\n\n**整套系统再复杂，也始终没有脱离“输入 -> 动作意图 -> 执行 -> 结果写回 -> 下一轮”这条主骨架。**\n\n## 读这篇时最该记住的三件事\n\n### 1. 所有模块都不是平铺摆在那里的\n\n它们是在一次请求的不同阶段依次介入的。\n\n### 2. 真正的闭环只有一个\n\n那就是：\n\n```text\ntool_result 回到 messages\n```\n\n### 3. 很多高级机制，本质上只是围绕这条闭环加的保护层\n\n例如：\n\n- 权限是执行前保护层\n- hook 是扩展层\n- compact 是上下文预算保护层\n- recovery 是出错后的恢复层\n- task/team/worktree/MCP 是更大的平台能力层\n\n## 一句话记住\n\n**一次请求的完整生命周期，本质上就是：系统围绕同一条主循环，把不同模块按阶段接进来，最终持续把真实执行结果送回模型继续推理。**\n"
  },
  {
    "version": null,
    "slug": "s00c-query-transition-model",
    "locale": "zh",
    "title": "s00c: Query Transition Model (查询转移模型)",
    "kind": "bridge",
    "filename": "s00c-query-transition-model.md",
    "content": "# s00c: Query Transition Model (查询转移模型)\n\n> 这篇桥接文档专门解决一个问题：\n>\n> **为什么一个只会 `continue` 的 agent，不足以支撑完整系统，而必须显式知道“为什么继续到下一轮”？**\n\n## 这一篇为什么要存在\n\n主线里：\n\n- `s01` 先教你最小循环\n- `s06` 开始教上下文压缩\n- `s11` 开始教错误恢复\n\n这些都对。  \n但如果你只分别学这几章，脑子里很容易还是停留在一种过于粗糙的理解：\n\n> “反正 `continue` 了就继续呗。”\n\n这在最小 demo 里能跑。  \n但当系统开始长出恢复、压缩和外部控制以后，这样理解会很快失灵。\n\n因为系统继续下一轮的原因其实很多，而且这些原因不是一回事：\n\n- 工具刚执行完，要把结果喂回模型\n- 输出被截断了，要续写\n- 上下文刚压缩完，要重试\n- 运输层刚超时了，要退避后重试\n- stop hook 要求当前 turn 先不要结束\n- token budget 还允许继续推进\n\n如果你不把这些“继续原因”从一开始拆开，后面会出现三个大问题：\n\n- 日志看不清\n- 测试不好写\n- 教学心智会越来越模糊\n\n## 先解释几个名词\n\n### 什么叫 transition\n\n这里的 `transition`，你可以先把它理解成：\n\n> 上一轮为什么转移到了下一轮。\n\n它不是“消息内容”，而是“流程原因”。\n\n### 什么叫 continuation\n\ncontinuation 就是：\n\n> 这条 query 当前还没有结束，要继续推进。\n\n但 continuation 不止一种。\n\n### 什么叫 query boundary\n\nquery boundary 就是一轮和下一轮之间的边界。\n\n每次跨过这个边界，系统最好都知道：\n\n- 这次为什么继续\n- 这次继续前有没有修改状态\n- 这次继续后应该怎么读主循环\n\n## 最小心智模型\n\n先不要把 query 想成一条线。\n\n更接近真实情况的理解是：\n\n```text\n一条 query\n  = 一组“继续原因”串起来的状态转移\n```\n\n例如：\n\n```text\n用户输入\n  ->\n模型产生 tool_use\n  ->\n工具执行完\n  ->\ntool_result_continuation\n  ->\n模型输出过长\n  ->\nmax_tokens_recovery\n  ->\n压缩后继续\n  ->\ncompact_retry\n  ->\n最终结束\n```\n\n这样看，你会更容易理解：\n\n**系统不是单纯在 while loop 里转圈，而是在一串显式的转移原因里推进。**\n\n## 关键数据结构\n\n### 1. QueryState 里的 `transition`\n\n最小版建议就把这类字段显式放进状态里：\n\n```python\nstate = {\n    \"messages\": [...],\n    \"turn_count\": 3,\n    \"has_attempted_compact\": False,\n    \"continuation_count\": 1,\n    \"transition\": None,\n}\n```\n\n这里的 `transition` 不是可有可无。\n\n它的意义是：\n\n- 当前这轮为什么会出现\n- 下一轮日志应该怎么解释\n- 测试时应该断言哪条路径被走到\n\n### 2. TransitionReason\n\n教学版最小可以先这样分：\n\n```python\nTRANSITIONS = (\n    \"tool_result_continuation\",\n    \"max_tokens_recovery\",\n    \"compact_retry\",\n    \"transport_retry\",\n    \"stop_hook_continuation\",\n    \"budget_continuation\",\n)\n```\n\n这几种原因的本质不一样：\n\n- `tool_result_continuation`\n  是正常主线继续\n- `max_tokens_recovery`\n  是输出被截断后的恢复继续\n- `compact_retry`\n  是上下文处理后的恢复继续\n- `transport_retry`\n  是基础设施抖动后的恢复继续\n- `stop_hook_continuation`\n  是外部控制逻辑阻止本轮结束\n- `budget_continuation`\n  是系统主动利用预算继续推进\n\n### 3. Continuation Budget\n\n更完整的 query 状态不只会说“继续”，还会限制：\n\n- 最多续写几次\n- 最多压缩后重试几次\n- 某类恢复是不是已经尝试过\n\n例如：\n\n```python\nstate = {\n    \"max_output_tokens_recovery_count\": 2,\n    \"has_attempted_reactive_compact\": True,\n}\n```\n\n这些字段的本质都是：\n\n> continuation 不是无限制的。\n\n## 最小实现\n\n### 第一步：把 continue site 显式化\n\n很多初学者写主循环时，所有继续逻辑都长这样：\n\n```python\ncontinue\n```\n\n教学版应该往前走一步：\n\n```python\nstate[\"transition\"] = \"tool_result_continuation\"\ncontinue\n```\n\n### 第二步：不同继续原因，配不同状态修改\n\n```python\nif response.stop_reason == \"tool_use\":\n    state[\"messages\"] = append_tool_results(...)\n    state[\"turn_count\"] += 1\n    state[\"transition\"] = \"tool_result_continuation\"\n    continue\n\nif response.stop_reason == \"max_tokens\":\n    state[\"messages\"].append({\n        \"role\": \"user\",\n        \"content\": CONTINUE_MESSAGE,\n    })\n    state[\"max_output_tokens_recovery_count\"] += 1\n    state[\"transition\"] = \"max_tokens_recovery\"\n    continue\n```\n\n重点不是“多写一行”。\n\n重点是：\n\n**每次继续之前，你都要知道自己做了什么状态更新，以及为什么继续。**\n\n### 第三步：把恢复继续和正常继续分开\n\n```python\nif should_retry_transport(error):\n    time.sleep(backoff(...))\n    state[\"transition\"] = \"transport_retry\"\n    continue\n\nif should_recompact(error):\n    state[\"messages\"] = compact_messages(state[\"messages\"])\n    state[\"transition\"] = \"compact_retry\"\n    continue\n```\n\n这时候你就开始得到一条非常清楚的控制链：\n\n```text\n继续\n  不再是一个动作\n  而是一类带原因的转移\n```\n\n## 一张真正应该建立的图\n\n```text\nquery loop\n  |\n  +-- tool executed --------------------> transition = tool_result_continuation\n  |\n  +-- output truncated -----------------> transition = max_tokens_recovery\n  |\n  +-- compact just happened -----------> transition = compact_retry\n  |\n  +-- network / transport retry -------> transition = transport_retry\n  |\n  +-- stop hook blocked termination ---> transition = stop_hook_continuation\n  |\n  +-- budget says keep going ----------> transition = budget_continuation\n```\n\n## 它和逆向仓库主脉络为什么对得上\n\n如果你去看更完整系统的查询入口，会发现它真正难的地方从来不是：\n\n- 再调一次模型\n\n而是：\n\n- 什么时候该继续\n- 继续前改哪份状态\n- 继续属于哪一种路径\n\n所以这篇桥接文档讲的，不是额外装饰，而是完整 query engine 的主骨架之一。\n\n## 它和主线章节怎么接\n\n- `s01` 让你先把 loop 跑起来\n- `s06` 让你知道为什么上下文管理会介入继续路径\n- `s11` 让你知道为什么恢复路径不是一种\n- 这篇则把“继续原因”统一抬成显式状态\n\n所以你可以把它理解成：\n\n> 给前后几章之间补上一条“为什么继续”的统一主线。\n\n## 初学者最容易犯的错\n\n### 1. 只有 `continue`，没有 `transition`\n\n这样日志和测试都会越来越难看。\n\n### 2. 把所有继续都当成一种\n\n这样会把：\n\n- 正常主线继续\n- 错误恢复继续\n- 压缩后重试\n\n全部混成一锅。\n\n### 3. 没有 continuation budget\n\n没有预算，系统就会在某些坏路径里无限试下去。\n\n### 4. 把 `transition` 写进消息文本，而不是流程状态\n\n消息是给模型看的。  \n`transition` 是给系统自己看的。\n\n### 5. 压缩、恢复、hook 都发生了，却没有统一的查询状态\n\n这会导致控制逻辑散落在很多局部变量里，越长越乱。\n\n## 教学边界\n\n这篇最重要的，不是一次枚举完所有 transition 名字，而是先让你守住三件事：\n\n- `continue` 最好总能对应一个显式的 `transition reason`\n- 正常继续、恢复继续、压缩后重试，不应该被混成同一种路径\n- continuation 需要预算和状态，而不是无限重来\n\n只要这三点成立，你就已经能把 `s01 / s06 / s11` 真正串成一条完整主线。  \n更细的 transition taxonomy、预算策略和日志分类，可以放到你把最小 query 状态机写稳以后再补。\n\n## 读完这一篇你应该能说清楚\n\n至少能完整说出这句话：\n\n> 一条 query 不是简单 while loop，而是一串显式 continuation reason 驱动的状态转移。\n\n如果这句话你已经能稳定说清，那么你再回头看 `s11`、`s19`，心智会顺很多。\n"
  },
  {
    "version": null,
    "slug": "s00d-chapter-order-rationale",
    "locale": "zh",
    "title": "s00d: Chapter Order Rationale (为什么是这个章节顺序)",
    "kind": "bridge",
    "filename": "s00d-chapter-order-rationale.md",
    "content": "# s00d: Chapter Order Rationale (为什么是这个章节顺序)\n\n> 这份文档不讲某一个机制本身。  \n> 它专门回答一个更基础的问题：\n>\n> **为什么这套仓库要按现在这个顺序教，而不是按源码目录顺序、功能热闹程度，或者“哪里复杂先讲哪里”。**\n\n## 先说结论\n\n当前这套 `s01 -> s19` 的主线顺序，整体上是合理的。\n\n它最大的优点不是“覆盖面广”，而是：\n\n- 先建立最小闭环\n- 再补横切控制面\n- 再补持久化工作层\n- 最后才扩成多 agent 平台和外部能力总线\n\n这个顺序适合教学，因为它遵守的不是“源码文件先后”，而是：\n\n**机制依赖顺序。**\n\n也就是：\n\n- 后一章需要建立在前一章已经清楚的心智之上\n- 同一层的新概念尽量一起讲完\n- 不把高阶平台能力提前压给还没建立主闭环的读者\n\n如果要把这套课程改到更接近满分，一个很重要的标准不是“加更多内容”，而是：\n\n**让读者始终知道这一章为什么现在学，而不是上一章或下一章。**\n\n这份文档就是干这件事的。\n\n## 这份顺序到底按什么排\n\n不是按这些排：\n\n- 不是按逆向源码里文件顺序排\n- 不是按实现难度排\n- 不是按功能看起来酷不酷排\n- 不是按产品里出现得早不早排\n\n它真正按的是四条依赖线：\n\n1. `主闭环依赖`\n2. `控制面依赖`\n3. `工作状态依赖`\n4. `平台边界依赖`\n\n你可以先把整套课粗暴地看成下面这条线：\n\n```text\n先让 agent 能跑\n  -> 再让它不乱跑\n  -> 再让它能长期跑\n  -> 最后让它能分工跑、隔离跑、接外部能力跑\n```\n\n这才是当前章节顺序最核心的逻辑。\n\n## 一张总图：章节之间真正的依赖关系\n\n```text\ns00 总览与地图\n  |\n  v\ns01 主循环\n  ->\ns02 工具执行\n  ->\ns03 会话计划\n  ->\ns04 子任务隔离\n  ->\ns05 按需知识注入\n  ->\ns06 上下文压缩\n\ns06 之后，单 agent 主骨架成立\n  |\n  v\ns07 权限闸门\n  ->\ns08 生命周期 Hook\n  ->\ns09 跨会话记忆\n  ->\ns10 Prompt / 输入装配\n  ->\ns11 恢复与续行\n\ns11 之后，单 agent 的高完成度控制面成立\n  |\n  v\ns12 持久任务图\n  ->\ns13 运行时后台槽位\n  ->\ns14 时间触发器\n\ns14 之后，工作系统从“聊天过程”升级成“可持续运行时”\n  |\n  v\ns15 持久队友\n  ->\ns16 协议化协作\n  ->\ns17 自治认领\n  ->\ns18 worktree 执行车道\n  ->\ns19 外部能力总线\n```\n\n如果你记不住所有章节，只记住每段结束后的“系统里多了什么”：\n\n- `s06` 结束：你有了能工作的单 agent\n- `s11` 结束：你有了更稳、更可控的单 agent\n- `s14` 结束：你有了能长期推进工作的运行时\n- `s19` 结束：你有了接近完整的平台边界\n\n## 为什么 `s01-s06` 必须先成一整段\n\n### `s01` 必须最先\n\n因为它定义的是：\n\n- 这套系统的最小入口\n- 每一轮到底怎么推进\n- 工具结果为什么能再次进入模型\n\n如果连这一条都没建立，后面所有内容都会变成“往空气里挂功能”。\n\n### `s02` 必须紧跟 `s01`\n\n因为没有工具，agent 只是会说，不是真的会做。\n\n开发者第一次真正感受到“harness 在做什么”，往往就是在 `s02`：\n\n- 模型产出 `tool_use`\n- 系统找到 handler\n- 执行工具\n- 回写 `tool_result`\n\n这是整个仓库第一条真正的“行动回路”。\n\n### `s03` 放在 `s04` 前面是对的\n\n很多人会直觉上想先讲 subagent，因为它更“高级”。\n\n但教学上不该这样排。\n\n原因很简单：\n\n- `s03` 先解决“当前 agent 自己怎么不乱撞”\n- `s04` 再解决“哪些工作要交给别的执行者”\n\n如果主 agent 连本地计划都没有，就提前进入子 agent，读者只会觉得：\n\n- 为什么要委派\n- 委派和待办到底是什么关系\n- 哪些是主流程，哪些是探索性流程\n\n都不清楚。\n\n所以：\n\n**先有本地计划，再有上下文隔离委派。**\n\n### `s05` 放在 `s06` 前面是对的\n\n这两个章节很多人会低估。\n\n实际上它们解决的是同一类问题的前后两半：\n\n- `s05` 解决：知识不要一开始全塞进来\n- `s06` 解决：已经塞进来的上下文怎么控制体积\n\n如果先讲压缩，再讲技能加载，读者容易误会成：\n\n- 上下文膨胀主要靠“事后压缩”解决\n\n但更合理的心智应该是：\n\n1. 先减少不必要进入上下文的东西\n2. 再处理已经进入上下文、且必须继续保留的东西\n\n所以 `s05 -> s06` 的顺序很合理。\n\n## 为什么 `s07-s11` 应该成一整段“控制面加固”\n\n这五章看起来分散，实际上它们共同在回答同一个问题：\n\n**主循环已经能跑了，但要怎样才能跑得稳、跑得可控、跑得更像一个完整系统。**\n\n### `s07` 权限必须早于 `s08` Hook\n\n因为权限是在问：\n\n- 这件事能不能做\n- 这件事做到哪一步要停\n- 这件事要不要先问用户\n\nHook 是在问：\n\n- 系统这个时刻要不要额外做点什么\n\n如果先讲 Hook，再讲权限，读者很容易误会：\n\n- 安全判断也只是某个 hook\n\n但实际上不是。\n\n更清楚的教学顺序应该是：\n\n1. 先建立“执行前必须先过闸门”的概念\n2. 再建立“主循环周围可以挂扩展点”的概念\n\n也就是：\n\n**先 gate，再 extend。**\n\n### `s09` 记忆放在 `s10` Prompt 前面是对的\n\n这是整套课程里很关键的一条顺序。\n\n很多人容易反过来讲，先讲 prompt，再讲 memory。\n\n但对开发者心智更友好的顺序其实是现在这样：\n\n- `s09` 先讲“长期信息从哪里来、哪些值得留下”\n- `s10` 再讲“这些来源最终怎样被组装进模型输入”\n\n也就是说：\n\n- `memory` 先回答“内容源是什么”\n- `prompt pipeline` 再回答“这些内容源怎么装配”\n\n如果反过来，读者会在 `s10` 里不断追问：\n\n- 为什么这里会有 memory block\n- 这块内容到底是谁准备的\n- 它和 messages、CLAUDE.md、skills 的边界在哪里\n\n所以这一条顺序不要乱换。\n\n### `s11` 放在这一段结尾很合理\n\n因为恢复与续行不是单独一层业务功能，而是：\n\n- 对前面所有输入、执行、状态、权限、压缩分支的总回收\n\n它天然适合做“控制面阶段的收口章”。\n\n只有当读者已经知道：\n\n- 一轮输入怎么组装\n- 执行时会走哪些分支\n- 发生什么状态变化\n\n他才真正看得懂恢复系统在恢复什么。\n\n## 为什么 `s12-s14` 必须先讲“任务图”，再讲“后台运行”，最后讲“定时触发”\n\n这是后半程最容易排错的一段。\n\n### `s12` 必须先于 `s13`\n\n因为 `s12` 解决的是：\n\n- 事情本身是什么\n- 依赖关系是什么\n- 哪个工作节点已完成、未完成、阻塞中\n\n而 `s13` 解决的是：\n\n- 某个执行单元现在是不是正在后台跑\n- 跑到什么状态\n- 结果怎么回流\n\n也就是：\n\n- `task` 是工作目标\n- `runtime task` 是执行槽位\n\n如果没有 `s12` 先铺开 durable work graph，读者到了 `s13` 会把后台任务误当成任务系统本体。\n\n这会直接导致后面：\n\n- cron 概念混乱\n- teammate 认领概念混乱\n- worktree lane 概念混乱\n\n所以这里一定要守住：\n\n**先有目标，再有执行体。**\n\n### `s14` 必须紧跟 `s13`\n\n因为 cron 本质上不是又一种任务。\n\n它只是回答：\n\n**如果现在不是用户当场触发，而是由时间触发一次执行，该怎么接到现有运行时里。**\n\n也就是说：\n\n- 没有 runtime slot，cron 没地方发车\n- 没有 task graph，cron 不知道在触发什么工作\n\n所以最合理顺序一定是：\n\n`task graph -> runtime slot -> schedule trigger`\n\n## 为什么 `s15-s19` 要按“队友 -> 协议 -> 自治 -> 隔离车道 -> 外部能力”排\n\n这一段如果顺序乱了，读者最容易开始觉得：\n\n- 队友、协议、任务、worktree、MCP 全都像“高级功能堆叠”\n\n但其实它们之间有很强的前后依赖。\n\n### `s15` 先定义“谁在系统里长期存在”\n\n这一章先把对象立起来：\n\n- 队友是谁\n- 他们有没有身份\n- 他们是不是可以持续存在\n\n如果连 actor 都还没清楚，协议对象就无从谈起。\n\n### `s16` 再定义“这些 actor 之间按什么规则说话”\n\n协议层不应该早于 actor 层。\n\n因为协议不是凭空存在的。\n\n它一定是服务于：\n\n- 请求谁\n- 谁审批\n- 谁响应\n- 如何回执\n\n所以：\n\n**先有队友，再有协议。**\n\n### `s17` 再进入“队友自己找活”\n\n自治不是“又多一种 agent 功能”。\n\n自治其实是建立在前两章之上的：\n\n- 前提 1：队友是长期存在的\n- 前提 2：队友之间有可追踪的协作规则\n\n只有这两个前提都建立了，自治认领才不会讲成一团雾。\n\n### `s18` 为什么在 `s19` 前面\n\n因为在平台层里，worktree 是执行隔离边界，MCP 是能力边界。\n\n对开发者自己手搓系统来说，更应先搞清：\n\n- 多个执行者如何不互相踩目录\n- 一个任务与一个执行车道如何绑定\n\n这些是“本地多执行者平台”先要解决的问题。\n\n把这个问题讲完后，再去讲：\n\n- 外部 server\n- 外部 tool\n- capability route\n\n开发者才不会把“MCP 很强”误解成“本地平台边界可以先不管”。\n\n### `s19` 放最后是对的\n\n因为它本质上是平台边界的最外层。\n\n它关心的是：\n\n- 本地系统之外的能力如何并入\n- 外部 server 和本地 tool 如何统一纳入 capability bus\n\n这个东西只有在前面这些边界都已经清楚后，读者才真的能吸收：\n\n- 本地 actor\n- 本地 work lane\n- 本地 task / runtime state\n- 外部 capability provider\n\n分别是什么。\n\n## 五种最容易让课程变差的“错误重排”\n\n### 错误 1：把 `s04` 提到 `s03` 前面\n\n坏处：\n\n- 读者先学会“把活丢出去”\n- 却还没学会“本地怎么规划”\n\n最后 subagent 只会变成“遇事就开新 agent”的逃避按钮。\n\n### 错误 2：把 `s10` 提到 `s09` 前面\n\n坏处：\n\n- 输入装配先讲了\n- 但输入源的边界还没立住\n\n结果 prompt pipeline 会看起来像一堆神秘字符串拼接。\n\n### 错误 3：把 `s13` 提到 `s12` 前面\n\n坏处：\n\n- 读者会把后台执行槽位误认成工作任务本体\n- 后面 cron、自治认领、worktree 都会越来越混\n\n### 错误 4：把 `s17` 提到 `s15` 或 `s16` 前面\n\n坏处：\n\n- 还没定义持久队友\n- 也还没定义结构化协作规则\n- 就先讲自治认领\n\n最后“自治”会被理解成模糊的自动轮询魔法。\n\n### 错误 5：把 `s19` 提到 `s18` 前面\n\n坏处：\n\n- 读者会先被外部能力系统吸引注意力\n- 却还没真正看清本地多执行者平台怎么稳定成立\n\n这会让整个课程后半程“看起来很大”，但“落到自己实现时没有抓手”。\n\n## 如果你自己手搓，可以在哪些地方先停\n\n这套课不是说一定要一次把 `s01-s19` 全做完。\n\n更稳的实现节奏是：\n\n### 里程碑 A：先做到 `s06`\n\n你已经有：\n\n- 主循环\n- 工具\n- 计划\n- 子任务隔离\n- 技能按需注入\n- 上下文压缩\n\n这已经足够做出一个“能用的单 agent 原型”。\n\n### 里程碑 B：再做到 `s11`\n\n你多了：\n\n- 权限\n- Hook\n- Memory\n- Prompt pipeline\n- 错误恢复\n\n到这里，单 agent 系统已经接近“高完成度教学实现”。\n\n### 里程碑 C：做到 `s14`\n\n你多了：\n\n- durable task\n- background runtime slot\n- cron trigger\n\n到这里，系统开始脱离“只会跟着当前会话走”的状态。\n\n### 里程碑 D：做到 `s19`\n\n这时再进入：\n\n- persistent teammate\n- protocol\n- autonomy\n- worktree lane\n- MCP / plugin\n\n这时你手里才是接近完整的平台结构。\n\n## 维护者在重排章节前该问自己什么\n\n如果你准备改顺序，先问下面这些问题：\n\n1. 这一章依赖的前置概念，前面有没有已经讲清？\n2. 这次重排会不会让两个同名但不同层的概念更容易混？\n3. 这一章新增的是“目标状态”“运行状态”“执行者”还是“外部能力”？\n4. 如果把它提前，读者会不会只记住名词，反而抓不到最小实现？\n5. 这次重排是在服务开发者实现路径，还是只是在模仿某个源码目录顺序？\n6. 读者按当前章节学完以后，本地代码到底该按什么顺序打开，这条代码阅读顺序有没有一起讲清？\n\n如果第 5 个问题的答案偏向后者，那大概率不该改。\n\n## 一句话记住\n\n**好的章节顺序，不是把所有机制排成一列，而是让每一章都像前一章自然长出来的下一层。**\n"
  },
  {
    "version": null,
    "slug": "s00e-reference-module-map",
    "locale": "zh",
    "title": "s00e: 参考仓库模块映射图",
    "kind": "bridge",
    "filename": "s00e-reference-module-map.md",
    "content": "# s00e: 参考仓库模块映射图\n\n> 这是一份给维护者和认真学习者用的校准文档。  \n> 它不是让读者逐行读逆向源码。\n>\n> 它只回答一个很关键的问题：\n>\n> **如果把参考仓库里真正重要的模块簇，和当前教学仓库的章节顺序对照起来看，现在这套课程顺序到底合不合理？**\n\n## 先说结论\n\n合理。\n\n当前这套 `s01 -> s19` 的顺序，整体上是对的，而且比“按源码目录顺序讲”更接近真实系统的设计主干。\n\n原因很简单：\n\n- 参考仓库里目录很多\n- 但真正决定系统骨架的，是少数几簇控制、状态、任务、团队、隔离执行和外部能力模块\n- 这些高信号模块，和当前教学仓库的四阶段主线基本是对齐的\n\n所以正确动作不是把教程改成“跟着源码树走”。\n\n正确动作是：\n\n- 保留现在这条按依赖关系展开的主线\n- 把它和参考仓库的映射关系讲明白\n- 继续把低价值的产品外围细节挡在主线外\n\n## 这份对照是怎么做的\n\n这次对照主要看的是参考仓库里真正决定系统骨架的部分，例如：\n\n- `Tool.ts`\n- `state/AppStateStore.ts`\n- `coordinator/coordinatorMode.ts`\n- `memdir/*`\n- `services/SessionMemory/*`\n- `services/toolUseSummary/*`\n- `constants/prompts.ts`\n- `tasks/*`\n- `tools/TodoWriteTool/*`\n- `tools/AgentTool/*`\n- `tools/ScheduleCronTool/*`\n- `tools/EnterWorktreeTool/*`\n- `tools/ExitWorktreeTool/*`\n- `tools/MCPTool/*`\n- `services/mcp/*`\n- `plugins/*`\n- `hooks/toolPermission/*`\n\n这些已经足够判断“设计主脉络”。\n\n没有必要为了教学，再把每个命令目录、兼容分支、UI 细节和产品接线全部拖进正文。\n\n## 真正的映射关系\n\n| 参考仓库模块簇 | 典型例子 | 对应教学章节 | 为什么这样放是对的 |\n|---|---|---|---|\n| 查询主循环 + 控制状态 | `Tool.ts`、`AppStateStore.ts`、query / coordinator 状态 | `s00`、`s00a`、`s00b`、`s01`、`s11` | 真实系统绝不只是 `messages[] + while True`。教学上先讲最小循环，再补控制平面，是对的。 |\n| 工具路由与执行面 | `Tool.ts`、原生 tools、tool context、执行辅助逻辑 | `s02`、`s02a`、`s02b` | 参考仓库明确把 tools 做成统一执行面，不只是玩具版分发表。当前拆法是合理的。 |\n| 会话规划 | `TodoWriteTool` | `s03` | 这是“当前会话怎么不乱撞”的小结构，应该早于持久任务图。 |\n| 一次性委派 | `AgentTool` 的最小子集 | `s04` | 参考仓库的 agent 体系很大，但教学仓库先教“新上下文 + 子任务 + 摘要返回”这个最小正确版本，是对的。 |\n| 技能发现与按需加载 | `DiscoverSkillsTool`、`skills/*`、相关 prompt 片段 | `s05` | 技能不是花哨外挂，而是知识注入层，所以应早于 prompt 复杂化和上下文压力。 |\n| 上下文压力与压缩 | `services/toolUseSummary/*`、`services/contextCollapse/*`、compact 逻辑 | `s06` | 参考仓库明确存在显式压缩机制，把这一层放在平台化能力之前完全正确。 |\n| 权限闸门 | `types/permissions.ts`、`hooks/toolPermission/*`、审批处理器 | `s07` | 执行安全是明确闸门，不是“某个 hook 顺手干的事”，所以必须早于 hook。 |\n| Hook 与侧边扩展 | `types/hooks.ts`、hook runner、生命周期接线 | `s08` | 参考仓库把扩展点和权限分开。教学顺序保持“先 gate，再 extend”是对的。 |\n| 持久记忆选择 | `memdir/*`、`services/SessionMemory/*`、记忆提取与筛选 | `s09` | 参考仓库把 memory 处理成“跨会话、选择性装配”的层，不是通用笔记本。 |\n| Prompt 组装 | `constants/prompts.ts`、prompt sections、memory prompt 注入 | `s10`、`s10a` | 参考仓库明显把输入拆成多个 section。教学版把 prompt 讲成流水线，而不是一段大字符串，是正确的。 |\n| 恢复与续行 | query transition、retry 分支、compact retry、token recovery | `s11`、`s00c` | 真实系统里“为什么继续下一轮”是显式存在的，所以恢复应当晚于 loop / tools / compact / permissions / memory / prompt。 |\n| 持久工作图 | 任务记录、任务板、依赖解锁 | `s12` | 当前教程把“持久任务目标”和“会话内待办”分开，是对的。 |\n| 活着的运行时任务 | `tasks/types.ts`、`LocalShellTask`、`LocalAgentTask`、`RemoteAgentTask`、`MonitorMcpTask` | `s13`、`s13a` | 参考仓库里 runtime task 是明确的联合类型，这强烈证明 `TaskRecord` 和 `RuntimeTaskState` 必须分开教。 |\n| 定时触发 | `ScheduleCronTool/*`、`useScheduledTasks` | `s14` | 调度是建在 runtime work 之上的新启动条件，放在 `s13` 后非常合理。 |\n| 持久队友 | `InProcessTeammateTask`、team tools、agent registry | `s15` | 参考仓库清楚地从一次性 subagent 继续长成长期 actor。把 teammate 放到后段是对的。 |\n| 结构化团队协作 | send-message 流、request tracking、coordinator mode | `s16` | 协议必须建立在“已有持久 actor”之上，所以不能提前。 |\n| 自治认领与恢复 | coordinator mode、任务认领、异步 worker 生命周期、resume 逻辑 | `s17` | 参考仓库里的 autonomy 不是魔法，而是建立在 actor、任务和协议之上的。 |\n| Worktree 执行车道 | `EnterWorktreeTool`、`ExitWorktreeTool`、agent worktree 辅助逻辑 | `s18` | 参考仓库把 worktree 当作执行边界 + 收尾状态来处理。当前放在 tasks / teams 后是正确的。 |\n| 外部能力总线 | `MCPTool`、`services/mcp/*`、`plugins/*`、MCP resources / prompts / tools | `s19`、`s19a` | 参考仓库把 MCP / plugin 放在平台最外层边界。把它放最后是合理的。 |\n\n## 这份对照最能证明的 5 件事\n\n### 1. `s03` 应该继续放在 `s12` 前面\n\n参考仓库里同时存在：\n\n- 小范围的会话计划\n- 大范围的持久任务 / 运行时系统\n\n它们不是一回事。\n\n所以教学顺序应当继续保持：\n\n`会话内计划 -> 持久任务图`\n\n### 2. `s09` 应该继续放在 `s10` 前面\n\n参考仓库里的输入装配，明确把 memory 当成输入来源之一。\n\n也就是说：\n\n- `memory` 先回答“内容从哪里来”\n- `prompt pipeline` 再回答“这些内容怎么组装进去”\n\n所以先讲 `s09`，再讲 `s10`，顺序不要反过来。\n\n### 3. `s12` 必须早于 `s13`\n\n`tasks/types.ts` 这类运行时任务联合类型，是这次对照里最强的证据之一。\n\n它非常清楚地说明：\n\n- 持久化的工作目标\n- 当前活着的执行槽位\n\n必须是两层不同状态。\n\n如果先讲 `s13`，读者几乎一定会把这两层混掉。\n\n### 4. `s15 -> s16 -> s17` 的顺序是对的\n\n参考仓库里明确能看到：\n\n- 持久 actor\n- 结构化协作\n- 自治认领 / 恢复\n\n自治必须建立在前两者之上，所以当前顺序合理。\n\n### 5. `s18` 应该继续早于 `s19`\n\n参考仓库把 worktree 当作本地执行边界机制。\n\n这应该先于：\n\n- 外部能力提供者\n- MCP server\n- plugin 装配面\n\n被讲清。\n\n否则读者会误以为“外部能力系统比本地执行边界更核心”。\n\n## 这套教学仓库仍然不该抄进主线的内容\n\n参考仓库里有很多真实但不应该占据主线的内容，例如：\n\n- CLI 命令面的完整铺开\n- UI 渲染细节\n- 遥测与分析分支\n- 远程 / 企业产品接线\n- 平台兼容层\n- 文件名、函数名、行号级 trivia\n\n这些不是假的。\n\n但它们不该成为 0 到 1 教学路径的中心。\n\n## 当前教学最容易漂掉的地方\n\n### 1. 不要把 subagent 和 teammate 混成一个模糊概念\n\n参考仓库里的 `AgentTool` 横跨了：\n\n- 一次性委派\n- 后台 worker\n- 持久 worker / teammate\n- worktree 隔离 worker\n\n这恰恰说明教学仓库应该继续拆开讲：\n\n- `s04`\n- `s15`\n- `s17`\n- `s18`\n\n不要在早期就把这些东西混成一个“大 agent 能力”。\n\n### 2. 不要把 worktree 教成“只是 git 小技巧”\n\n参考仓库里有 closeout、resume、cleanup、dirty-check 等状态。\n\n所以 `s18` 必须继续讲清：\n\n- lane 身份\n- task 绑定\n- keep / remove 收尾\n- 恢复与清理\n\n而不是只讲 `git worktree add`。\n\n### 3. 不要把 MCP 缩成“远程 tools”\n\n参考仓库里明显不只有工具，还有：\n\n- resources\n- prompts\n- elicitation / connection state\n- plugin 中介层\n\n所以 `s19` 可以继续用 tools-first 的教学路径切入，但一定要补平台边界那一层地图。\n\n## 最终判断\n\n如果只拿“章节顺序是否贴近参考仓库的设计主干”这个问题来打分，那么当前这套顺序是过关而且方向正确的。\n\n真正还能继续加分的地方，不再是再做一次大重排，而是：\n\n- 把桥接文档补齐\n- 把实体边界讲得更硬\n- 把多语言内容统一到同一个心智层次\n- 让 web 页面把这套学习地图展示得更清楚\n\n## 一句话记住\n\n**最好的教学顺序，不是源码文件出现的顺序，而是一个初学实现者真正能顺着依赖关系把系统重建出来的顺序。**\n"
  },
  {
    "version": null,
    "slug": "s00f-code-reading-order",
    "locale": "zh",
    "title": "s00f: 本仓库代码阅读顺序",
    "kind": "bridge",
    "filename": "s00f-code-reading-order.md",
    "content": "# s00f: 本仓库代码阅读顺序\n\n> 这份文档不是让你“多看代码”。  \n> 它专门解决另一个问题：\n>\n> **当你已经知道章节顺序是对的以后，本仓库代码到底应该按什么顺序读，才不会把心智重新读乱。**\n\n## 先说结论\n\n不要这样读代码：\n\n- 不要从文件最长的那一章开始\n- 不要随机点一个你觉得“高级”的章节开始\n- 不要先钻 `web/` 再回头猜主线\n- 不要把 19 个 `agents/*.py` 当成一个源码池乱翻\n\n最稳的读法只有一句话：\n\n**文档顺着章节读，代码也顺着章节读。**\n\n而且每一章的代码，都先按同一个模板看：\n\n1. 先看状态结构\n2. 再看工具定义或注册表\n3. 再看“这一轮怎么推进”的主函数\n4. 最后才看 CLI 入口和试运行方式\n\n## 为什么需要这份文档\n\n很多读者不是看不懂某一章文字，而是会在真正打开代码以后重新乱掉。\n\n典型症状是：\n\n- 一上来先盯住 300 行以上的文件底部\n- 先看一堆 `run_*` 函数，却不知道它们挂在哪条主线上\n- 先看“最复杂”的平台章节，然后觉得前面的章节好像都太简单\n- 把 `task`、`runtime task`、`teammate`、`worktree` 在代码里重新混成一团\n\n这份阅读顺序就是为了防止这种情况。\n\n## 读每个 agent 文件时，都先按同一个模板\n\n不管你打开的是哪一章，本仓库里的 `agents/sXX_*.py` 都建议先按下面顺序读：\n\n### 第一步：先看文件头注释\n\n先回答两个问题：\n\n- 这一章到底在教什么\n- 它故意没有教什么\n\n如果连这一步都没建立，后面你会把每个函数都看成同等重要。\n\n### 第二步：先看状态结构或管理器类\n\n优先找这些东西：\n\n- `LoopState`\n- `PlanningState`\n- `CompactState`\n- `TaskManager`\n- `BackgroundManager`\n- `TeammateManager`\n- `WorktreeManager`\n\n原因很简单：\n\n**先知道系统到底记住了什么，后面才看得懂它为什么要这样流动。**\n\n### 第三步：再看工具列表或注册表\n\n优先找这些入口：\n\n- `TOOLS`\n- `TOOL_HANDLERS`\n- 各种 `run_*`\n- `build_tool_pool()`\n\n这一层回答的是：\n\n- 模型到底能调用什么\n- 这些调用会落到哪条执行面上\n\n### 第四步：最后才看主推进函数\n\n重点函数通常长这样：\n\n- `run_one_turn(...)`\n- `agent_loop(...)`\n- 某个 `handle_*`\n\n这一步要回答的是：\n\n- 这一章新机制到底接在主循环哪一环\n- 哪个分支是新增的\n- 新状态是在哪里写入、回流、继续的\n\n### 第五步：最后再看 `if __name__ == \"__main__\"`\n\nCLI 入口当然有用，但它不应该成为第一屏。\n\n因为它通常只是在做：\n\n- 读用户输入\n- 初始化状态\n- 调用 `agent_loop`\n\n真正决定一章心智主干的，不在这里。\n\n## 阶段 1：`s01-s06` 应该怎样读代码\n\n这一段不是在学“很多功能”，而是在学：\n\n**一个单 agent 主骨架到底怎样成立。**\n\n| 章节 | 文件 | 先看什么 | 再看什么 | 读完要确认什么 |\n|---|---|---|---|---|\n| `s01` | `agents/s01_agent_loop.py` | `LoopState` | `TOOLS` -> `execute_tool_calls()` -> `run_one_turn()` -> `agent_loop()` | 你已经能看懂 `messages -> model -> tool_result -> next turn` |\n| `s02` | `agents/s02_tool_use.py` | `safe_path()` | `run_read()` / `run_write()` / `run_edit()` -> `TOOL_HANDLERS` -> `agent_loop()` | 你已经能看懂“主循环不变，工具靠分发面增长” |\n| `s03` | `agents/s03_todo_write.py` | `PlanItem` / `PlanningState` / `TodoManager` | `todo` 相关 handler -> reminder 注入 -> `agent_loop()` | 你已经能看懂“会话计划状态”怎么外显化 |\n| `s04` | `agents/s04_subagent.py` | `AgentTemplate` | `run_subagent()` -> 父 `agent_loop()` | 你已经能看懂“子智能体首先是上下文隔离” |\n| `s05` | `agents/s05_skill_loading.py` | `SkillManifest` / `SkillDocument` / `SkillRegistry` | `get_descriptions()` / `get_content()` -> `agent_loop()` | 你已经能看懂“先发现、再按需加载” |\n| `s06` | `agents/s06_context_compact.py` | `CompactState` | `persist_large_output()` -> `micro_compact()` -> `compact_history()` -> `agent_loop()` | 你已经能看懂“压缩不是删历史，而是转移细节” |\n\n### 这一段最值得反复看的 3 个代码点\n\n1. `state` 在哪里第一次从“聊天内容”升级成“显式系统状态”\n2. `tool_result` 是怎么一直保持为统一回流接口的\n3. 新机制是怎样接进 `agent_loop()` 而不是把 `agent_loop()` 重写烂的\n\n### 这一段读完后，最好的动作\n\n不要立刻去看 `s07`。\n\n先自己从空目录手写一遍下面这些最小件：\n\n- 一个 loop\n- 一个 dispatch map\n- 一个会话计划状态\n- 一个一次性子任务隔离\n- 一个按需技能加载\n- 一个最小压缩层\n\n## 阶段 2：`s07-s11` 应该怎样读代码\n\n这一段不是在学“又多了五种功能”。\n\n它真正是在学：\n\n**单 agent 的控制面是怎样长出来的。**\n\n| 章节 | 文件 | 先看什么 | 再看什么 | 读完要确认什么 |\n|---|---|---|---|---|\n| `s07` | `agents/s07_permission_system.py` | `BashSecurityValidator` / `PermissionManager` | 权限判定入口 -> `run_bash()` -> `agent_loop()` | 你已经能看懂“先 gate，再 execute” |\n| `s08` | `agents/s08_hook_system.py` | `HookManager` | hook 注册与触发 -> `agent_loop()` | 你已经能看懂 hook 是固定时机的插口，不是散落 if |\n| `s09` | `agents/s09_memory_system.py` | `MemoryManager` / `DreamConsolidator` | `run_save_memory()` -> `build_system_prompt()` -> `agent_loop()` | 你已经能看懂 memory 是长期信息层，不是上下文垃圾桶 |\n| `s10` | `agents/s10_system_prompt.py` | `SystemPromptBuilder` | `build_system_reminder()` -> `agent_loop()` | 你已经能看懂输入是流水线，不是单块 prompt |\n| `s11` | `agents/s11_error_recovery.py` | `estimate_tokens()` / `auto_compact()` / `backoff_delay()` | 各恢复分支 -> `agent_loop()` | 你已经能看懂“恢复以后怎样继续下一轮” |\n\n### 这一段读代码时，最容易重新读乱的地方\n\n1. 把权限和 hook 混成一类\n2. 把 memory 和 prompt 装配混成一类\n3. 把 `s11` 看成很多异常判断，而不是“续行控制”\n\n如果你开始混，先回：\n\n- `docs/zh/s00a-query-control-plane.md`\n- `docs/zh/s10a-message-prompt-pipeline.md`\n- `docs/zh/s00c-query-transition-model.md`\n\n## 阶段 3：`s12-s14` 应该怎样读代码\n\n这一段开始，代码理解的关键不再是“工具多了什么”，而是：\n\n**系统第一次真正长出会话外工作状态和运行时槽位。**\n\n| 章节 | 文件 | 先看什么 | 再看什么 | 读完要确认什么 |\n|---|---|---|---|---|\n| `s12` | `agents/s12_task_system.py` | `TaskManager` | 任务创建、依赖、解锁 -> `agent_loop()` | 你已经能看懂 task 是持久工作图，不是 todo |\n| `s13` | `agents/s13_background_tasks.py` | `NotificationQueue` / `BackgroundManager` | 后台执行登记 -> 通知排空 -> `agent_loop()` | 你已经能看懂 background task 是运行槽位 |\n| `s14` | `agents/s14_cron_scheduler.py` | `CronLock` / `CronScheduler` | `cron_matches()` -> schedule 触发 -> `agent_loop()` | 你已经能看懂调度器只负责“未来何时开始” |\n\n### 这一段读代码时一定要守住的边界\n\n- `task` 是工作目标\n- `runtime task` 是正在跑的执行槽位\n- `schedule` 是何时触发工作\n\n只要这三层在代码里重新混掉，后面 `s15-s19` 会一起变难。\n\n## 阶段 4：`s15-s19` 应该怎样读代码\n\n这一段不要当成“功能狂欢”去读。\n\n它真正建立的是：\n\n**平台边界。**\n\n| 章节 | 文件 | 先看什么 | 再看什么 | 读完要确认什么 |\n|---|---|---|---|---|\n| `s15` | `agents/s15_agent_teams.py` | `MessageBus` / `TeammateManager` | 队友名册、邮箱、独立循环 -> `agent_loop()` | 你已经能看懂 teammate 是长期 actor，不是一次性 subagent |\n| `s16` | `agents/s16_team_protocols.py` | `RequestStore` / `TeammateManager` | `handle_shutdown_request()` / `handle_plan_review()` -> `agent_loop()` | 你已经能看懂 request-response + `request_id` |\n| `s17` | `agents/s17_autonomous_agents.py` | `RequestStore` / `TeammateManager` | `is_claimable_task()` / `claim_task()` / `ensure_identity_context()` -> `agent_loop()` | 你已经能看懂自治主线：空闲检查 -> 安全认领 -> 恢复工作 |\n| `s18` | `agents/s18_worktree_task_isolation.py` | `TaskManager` / `WorktreeManager` / `EventBus` | `worktree_enter` 相关生命周期 -> `agent_loop()` | 你已经能看懂 task 管目标，worktree 管执行车道 |\n| `s19` | `agents/s19_mcp_plugin.py` | `CapabilityPermissionGate` / `MCPClient` / `PluginLoader` / `MCPToolRouter` | `build_tool_pool()` / `handle_tool_call()` / `normalize_tool_result()` -> `agent_loop()` | 你已经能看懂外部能力如何接回同一控制面 |\n\n### 这一段最容易误读的地方\n\n1. 把 `s15` 的 teammate 当成 `s04` 的 subagent 放大版\n2. 把 `s17` 自治看成“agent 自己乱跑”\n3. 把 `s18` worktree 看成一个 git 小技巧\n4. 把 `s19` MCP 缩成“只是远程 tools”\n\n## 代码阅读时，哪些文件不要先看\n\n如果你的目标是建立主线心智，下面这些内容不要先看：\n\n- `web/` 里的可视化实现细节\n- `web/src/data/generated/*`\n- `.next/` 或其他构建产物\n- `agents/s_full.py`\n\n原因不是它们没价值。\n\n而是：\n\n- `web/` 解决的是展示与学习界面\n- `generated` 是抽取结果，不是机制本身\n- `s_full.py` 是整合参考，不适合第一次建立边界\n\n## 最推荐的“文档 + 代码 + 运行”循环\n\n每一章最稳的学习动作不是只看文档，也不是只看代码。\n\n推荐固定走这一套：\n\n1. 先读这一章正文\n2. 再读这一章的桥接资料\n3. 再打开对应 `agents/sXX_*.py`\n4. 按“状态 -> 工具 -> 主推进函数 -> CLI 入口”的顺序看\n5. 跑一次这章的 demo\n6. 自己从空目录重写一个最小版本\n\n只要你每章都这样走一次，代码理解会非常稳。\n\n## 初学者最容易犯的 6 个代码阅读错误\n\n### 1. 先看最长文件\n\n这通常只会先把自己看晕。\n\n### 2. 先盯 `run_bash()` 这种工具细节\n\n工具实现细节不是主干。\n\n### 3. 不先找状态结构\n\n这样你永远不知道系统到底记住了什么。\n\n### 4. 把 `agent_loop()` 当成唯一重点\n\n主循环当然重要，但每章真正新增的边界，往往在状态容器和分支入口。\n\n### 5. 读完代码不跑 demo\n\n不实际跑一次，很难建立“这一章到底新增了哪条回路”的感觉。\n\n### 6. 一口气连看三四章代码，不停下来自己重写\n\n这样最容易出现“我好像都看过，但其实自己不会写”的错觉。\n\n## 一句话记住\n\n**代码阅读顺序也必须服从教学顺序：先看边界，再看状态，再看主线如何推进，而不是随机翻源码。**\n"
  },
  {
    "version": "s01",
    "slug": "s01-the-agent-loop",
    "locale": "zh",
    "title": "s01: The Agent Loop (智能体循环)",
    "kind": "chapter",
    "filename": "s01-the-agent-loop.md",
    "content": "# s01: The Agent Loop (智能体循环)\n\n`s00 > [ s01 ] > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *没有循环，就没有 agent。*  \n> 这一章先教你做出一个最小但正确的循环，再告诉你为什么后面还需要更完整的控制平面。\n\n## 这一章要解决什么问题\n\n语言模型本身只会“生成下一段内容”。\n\n它不会自己：\n\n- 打开文件\n- 运行命令\n- 观察报错\n- 把工具结果再接着用于下一步推理\n\n如果没有一层代码在中间反复做这件事：\n\n```text\n发请求给模型\n  -> 发现模型想调工具\n  -> 真的去执行工具\n  -> 把结果再喂回模型\n  -> 继续下一轮\n```\n\n那模型就只是一个“会说话的程序”，还不是一个“会干活的 agent”。\n\n所以这一章的核心目标只有一个：\n\n**把“模型 + 工具”连接成一个能持续推进任务的主循环。**\n\n## 先解释几个名词\n\n### 什么是 loop\n\n`loop` 就是循环。\n\n这里的意思不是“程序死循环”，而是：\n\n> 只要任务还没做完，系统就继续重复同一套步骤。\n\n### 什么是 turn\n\n`turn` 可以理解成“一轮”。\n\n最小版本里，一轮通常包含：\n\n1. 把当前消息发给模型\n2. 读取模型回复\n3. 如果模型调用了工具，就执行工具\n4. 把工具结果写回消息历史\n\n然后才进入下一轮。\n\n### 什么是 tool_result\n\n`tool_result` 就是工具执行结果。\n\n它不是随便打印在终端上的日志，而是：\n\n> 要重新写回对话历史、让模型下一轮真的能看见的结果块。\n\n### 什么是 state\n\n`state` 是“当前运行状态”。\n\n第一次看到这个词时，你可以先把它理解成：\n\n> 主循环继续往下走时，需要一直带着走的那份数据。\n\n最小版本里，最重要的状态就是：\n\n- `messages`\n- 当前是第几轮\n- 这一轮结束后为什么还要继续\n\n## 最小心智模型\n\n先把整个 agent 想成下面这条回路：\n\n```text\nuser message\n   |\n   v\nLLM\n   |\n   +-- 普通回答 ----------> 结束\n   |\n   +-- tool_use ----------> 执行工具\n                              |\n                              v\n                         tool_result\n                              |\n                              v\n                         写回 messages\n                              |\n                              v\n                         下一轮继续\n```\n\n这条图里最关键的，不是“有一个 while True”。\n\n真正关键的是这句：\n\n**工具结果必须重新进入消息历史，成为下一轮推理的输入。**\n\n如果少了这一步，模型就无法基于真实观察继续工作。\n\n## 关键数据结构\n\n### 1. Message\n\n最小教学版里，可以先把消息理解成：\n\n```python\n{\"role\": \"user\", \"content\": \"...\"}\n{\"role\": \"assistant\", \"content\": [...]}\n```\n\n这里最重要的不是字段名字，而是你要记住：\n\n**消息历史不是聊天记录展示层，而是模型下一轮要读的工作上下文。**\n\n### 2. Tool Result Block\n\n当工具执行完后，你要把它包装回消息流：\n\n```python\n{\n    \"type\": \"tool_result\",\n    \"tool_use_id\": \"...\",\n    \"content\": \"...\",\n}\n```\n\n`tool_use_id` 的作用很简单：\n\n> 告诉模型“这条结果对应的是你刚才哪一次工具调用”。\n\n### 3. LoopState\n\n这章建议你不要只用一堆零散局部变量。\n\n最小也应该显式收拢出一个循环状态：\n\n```python\nstate = {\n    \"messages\": [...],\n    \"turn_count\": 1,\n    \"transition_reason\": None,\n}\n```\n\n这里的 `transition_reason` 先只需要理解成：\n\n> 这一轮结束后，为什么要继续下一轮。\n\n最小教学版只用一种原因就够了：\n\n```python\n\"tool_result\"\n```\n\n也就是：\n\n> 因为刚执行完工具，所以要继续。\n\n后面到了控制面更完整的章节里，你会看到它逐渐长成更多种原因。  \n如果你想先看完整一点的形状，可以配合读：\n\n- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)\n\n## 最小实现\n\n### 第一步：准备初始消息\n\n用户的请求先进入 `messages`：\n\n```python\nmessages = [{\"role\": \"user\", \"content\": query}]\n```\n\n### 第二步：调用模型\n\n把消息历史、system prompt 和工具定义一起发给模型：\n\n```python\nresponse = client.messages.create(\n    model=MODEL,\n    system=SYSTEM,\n    messages=messages,\n    tools=TOOLS,\n    max_tokens=8000,\n)\n```\n\n### 第三步：追加 assistant 回复\n\n```python\nmessages.append({\"role\": \"assistant\", \"content\": response.content})\n```\n\n这一步非常重要。\n\n很多初学者会只关心“最后有没有答案”，忽略把 assistant 回复本身写回历史。  \n这样一来，下一轮上下文就会断掉。\n\n### 第四步：如果模型调用了工具，就执行\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### 第五步：把工具结果作为新消息写回去\n\n```python\nmessages.append({\"role\": \"user\", \"content\": results})\n```\n\n然后下一轮重新发给模型。\n\n### 组合成一个完整循环\n\n```python\ndef agent_loop(state):\n    while True:\n        response = client.messages.create(\n            model=MODEL,\n            system=SYSTEM,\n            messages=state[\"messages\"],\n            tools=TOOLS,\n            max_tokens=8000,\n        )\n\n        state[\"messages\"].append({\n            \"role\": \"assistant\",\n            \"content\": response.content,\n        })\n\n        if response.stop_reason != \"tool_use\":\n            state[\"transition_reason\"] = None\n            return\n\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                output = run_tool(block)\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": output,\n                })\n\n        state[\"messages\"].append({\"role\": \"user\", \"content\": results})\n        state[\"turn_count\"] += 1\n        state[\"transition_reason\"] = \"tool_result\"\n```\n\n这就是最小 agent loop。\n\n## 它如何接进整个系统\n\n从现在开始，后面所有章节本质上都在做同一件事：\n\n**往这个循环里增加新的状态、新的分支判断和新的执行能力。**\n\n例如：\n\n- `s02` 往里面接工具路由\n- `s03` 往里面接规划状态\n- `s06` 往里面接上下文压缩\n- `s07` 往里面接权限判断\n- `s11` 往里面接错误恢复\n\n所以请把这一章牢牢记成一句话：\n\n> agent 的核心不是“模型很聪明”，而是“系统持续把现实结果喂回模型”。\n\n## 为什么教学版先接受 `stop_reason == \"tool_use\"` 这个简化\n\n这一章里，我们先用：\n\n```python\nif response.stop_reason != \"tool_use\":\n    return\n```\n\n这完全合理。\n\n因为初学者在第一章真正要学会的，不是所有复杂边界，而是：\n\n1. assistant 回复要写回历史\n2. tool_result 要写回历史\n3. 主循环要持续推进\n\n但你也要知道，这只是第一层简化。\n\n更完整的系统不会只依赖 `stop_reason`，还会自己维护更明确的续行状态。  \n这是后面要补的，不是这一章一开始就要背下来的东西。\n\n## 初学者最容易犯的错\n\n### 1. 把工具结果打印出来，但不写回 `messages`\n\n这样模型下一轮根本看不到真实执行结果。\n\n### 2. 只保存用户消息，不保存 assistant 消息\n\n这样上下文会断层，模型会越来越不像“接着刚才做”。\n\n### 3. 不给工具结果绑定 `tool_use_id`\n\n模型会分不清哪条结果对应哪次调用。\n\n### 4. 一上来就把流式、并发、恢复、压缩全塞进第一章\n\n这会让主线变得非常难学。\n\n第一章最重要的是先把最小回路搭起来。\n\n### 5. 以为 `messages` 只是聊天展示\n\n不是。\n\n在 agent 里，`messages` 更像“下一轮工作输入”。\n\n## 教学边界\n\n这一章只需要先讲透一件事：\n\n**Agent 之所以从“会说”变成“会做”，是因为模型输出能走到工具，工具结果又能回到下一轮模型输入。**\n\n所以教学仓库在这里要刻意停住：\n\n- 不要一开始就拉进 streaming、retry、budget、recovery\n- 不要一开始就混入权限、Hook、任务系统\n- 不要把第一章写成整套系统所有后续机制的总图\n\n如果读者已经能凭记忆写出 `messages -> model -> tool_result -> next turn` 这条回路，这一章就已经达标了。\n\n## 一句话记住\n\n**Agent Loop 的本质，是把“模型的动作意图”变成“真实执行结果”，再把结果送回模型继续推理。**\n"
  },
  {
    "version": "s02",
    "slug": "s02-tool-use",
    "locale": "zh",
    "title": "s02: Tool Use (工具使用)",
    "kind": "chapter",
    "filename": "s02-tool-use.md",
    "content": "# s02: Tool Use (工具使用)\n\n`s00 > s01 > [ s02 ] > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *\"加一个工具, 只加一个 handler\"* -- 循环不用动, 新工具注册进 dispatch map 就行。\n>\n> **Harness 层**: 工具分发 -- 扩展模型能触达的边界。\n\n## 问题\n\n只有 `bash` 时, 所有操作都走 shell。`cat` 截断不可预测, `sed` 遇到特殊字符就崩, 每次 bash 调用都是不受约束的安全面。专用工具 (`read_file`, `write_file`) 可以在工具层面做路径沙箱。\n\n关键洞察: 加工具不需要改循环。\n\n## 解决方案\n\n```\n+--------+      +-------+      +------------------+\n|  User  | ---> |  LLM  | ---> | Tool Dispatch    |\n| prompt |      |       |      | {                |\n+--------+      +---+---+      |   bash: run_bash |\n                    ^           |   read: run_read |\n                    |           |   write: run_wr  |\n                    +-----------+   edit: run_edit |\n                    tool_result | }                |\n                                +------------------+\n\nThe dispatch map is a dict: {tool_name: handler_function}.\nOne lookup replaces any if/elif chain.\n```\n\n## 工作原理\n\n1. 每个工具有一个处理函数。路径沙箱防止逃逸工作区。\n\n```python\ndef safe_path(p: str) -> Path:\n    path = (WORKDIR / p).resolve()\n    if not path.is_relative_to(WORKDIR):\n        raise ValueError(f\"Path escapes workspace: {p}\")\n    return path\n\ndef run_read(path: str, limit: int = None) -> str:\n    text = safe_path(path).read_text()\n    lines = text.splitlines()\n    if limit and limit < len(lines):\n        lines = lines[:limit]\n    return \"\\n\".join(lines)[:50000]\n```\n\n2. dispatch map 将工具名映射到处理函数。\n\n```python\nTOOL_HANDLERS = {\n    \"bash\":       lambda **kw: run_bash(kw[\"command\"]),\n    \"read_file\":  lambda **kw: run_read(kw[\"path\"], kw.get(\"limit\")),\n    \"write_file\": lambda **kw: run_write(kw[\"path\"], kw[\"content\"]),\n    \"edit_file\":  lambda **kw: run_edit(kw[\"path\"], kw[\"old_text\"],\n                                        kw[\"new_text\"]),\n}\n```\n\n3. 循环中按名称查找处理函数。循环体本身与 s01 完全一致。\n\n```python\nfor block in response.content:\n    if block.type == \"tool_use\":\n        handler = TOOL_HANDLERS.get(block.name)\n        output = handler(**block.input) if handler \\\n            else f\"Unknown tool: {block.name}\"\n        results.append({\n            \"type\": \"tool_result\",\n            \"tool_use_id\": block.id,\n            \"content\": output,\n        })\n```\n\n加工具 = 加 handler + 加 schema。循环永远不变。\n\n## 相对 s01 的变更\n\n| 组件           | 之前 (s01)         | 之后 (s02)                     |\n|----------------|--------------------|--------------------------------|\n| Tools          | 1 (仅 bash)        | 4 (bash, read, write, edit)    |\n| Dispatch       | 硬编码 bash 调用   | `TOOL_HANDLERS` 字典           |\n| 路径安全       | 无                 | `safe_path()` 沙箱             |\n| Agent loop     | 不变               | 不变                           |\n\n## 试一试\n\n```sh\ncd learn-claude-code\npython agents/s02_tool_use.py\n```\n\n试试这些 prompt (英文 prompt 对 LLM 效果更好, 也可以用中文):\n\n1. `Read the file requirements.txt`\n2. `Create a file called greet.py with a greet(name) function`\n3. `Edit greet.py to add a docstring to the function`\n4. `Read greet.py to verify the edit worked`\n\n## 如果你开始觉得“工具不只是 handler map”\n\n到这里为止，教学主线先把工具讲成：\n\n- schema\n- handler\n- `tool_result`\n\n这是对的，而且必须先这么学。\n\n但如果你继续把系统做大，很快就会发现工具层还会继续长出：\n\n- 权限环境\n- 当前消息和 app state\n- MCP client\n- 文件读取缓存\n- 通知与 query 跟踪\n\n也就是说，在一个结构更完整的系统里，工具层最后会更像一条“工具控制平面”，而不只是一张分发表。\n\n这层不要抢正文主线。  \n你先把这一章吃透，再继续看：\n\n- [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)\n\n## 消息规范化\n\n教学版的 `messages` 列表直接发给 API, 所见即所发。但当系统变复杂后 (工具超时、用户取消、压缩替换), 内部消息列表会出现 API 不接受的格式问题。需要在发送前做一次规范化。\n\n### 为什么需要\n\nAPI 协议有三条硬性约束:\n1. 每个 `tool_use` 块**必须**有匹配的 `tool_result` (通过 `tool_use_id` 关联)\n2. `user` / `assistant` 消息必须**严格交替** (不能连续两条同角色)\n3. 只接受协议定义的字段 (内部元数据会导致 400 错误)\n\n### 实现\n\n```python\ndef normalize_messages(messages: list) -> list:\n    \"\"\"将内部消息列表规范化为 API 可接受的格式。\"\"\"\n    normalized = []\n\n    for msg in messages:\n        # Step 1: 剥离内部字段\n        clean = {\"role\": msg[\"role\"]}\n        if isinstance(msg.get(\"content\"), str):\n            clean[\"content\"] = msg[\"content\"]\n        elif isinstance(msg.get(\"content\"), list):\n            clean[\"content\"] = [\n                {k: v for k, v in block.items()\n                 if k not in (\"_internal\", \"_source\", \"_timestamp\")}\n                for block in msg[\"content\"]\n            ]\n        normalized.append(clean)\n\n    # Step 2: tool_result 配对补齐\n    # 收集所有已有的 tool_result ID\n    existing_results = set()\n    for msg in normalized:\n        if isinstance(msg.get(\"content\"), list):\n            for block in msg[\"content\"]:\n                if block.get(\"type\") == \"tool_result\":\n                    existing_results.add(block.get(\"tool_use_id\"))\n\n    # 找出缺失配对的 tool_use, 插入占位 result\n    for msg in normalized:\n        if msg[\"role\"] == \"assistant\" and isinstance(msg.get(\"content\"), list):\n            for block in msg[\"content\"]:\n                if (block.get(\"type\") == \"tool_use\"\n                        and block.get(\"id\") not in existing_results):\n                    # 在下一条 user 消息中补齐\n                    normalized.append({\"role\": \"user\", \"content\": [{\n                        \"type\": \"tool_result\",\n                        \"tool_use_id\": block[\"id\"],\n                        \"content\": \"(cancelled)\",\n                    }]})\n\n    # Step 3: 合并连续同角色消息\n    merged = [normalized[0]] if normalized else []\n    for msg in normalized[1:]:\n        if msg[\"role\"] == merged[-1][\"role\"]:\n            # 合并内容\n            prev = merged[-1]\n            prev_content = prev[\"content\"] if isinstance(prev[\"content\"], list) \\\n                else [{\"type\": \"text\", \"text\": prev[\"content\"]}]\n            curr_content = msg[\"content\"] if isinstance(msg[\"content\"], list) \\\n                else [{\"type\": \"text\", \"text\": msg[\"content\"]}]\n            prev[\"content\"] = prev_content + curr_content\n        else:\n            merged.append(msg)\n\n    return merged\n```\n\n在 agent loop 中, 每次 API 调用前运行:\n\n```python\nresponse = client.messages.create(\n    model=MODEL, system=system,\n    messages=normalize_messages(messages),  # 规范化后再发送\n    tools=TOOLS, max_tokens=8000,\n)\n```\n\n**关键洞察**: `messages` 列表是系统的内部表示, API 看到的是规范化后的副本。两者不是同一个东西。\n\n## 教学边界\n\n这一章最重要的，不是把完整工具运行时一次讲全，而是先讲清 3 个稳定点：\n\n- tool schema 是给模型看的说明\n- handler map 是代码里的分发入口\n- `tool_result` 是结果回流到主循环的统一出口\n\n只要这三点稳住，读者就已经能自己在不改主循环的前提下新增工具。\n\n权限、hook、并发、流式执行、外部工具来源这些后续层次当然重要，但都应该建立在这层最小分发模型之后。\n"
  },
  {
    "version": null,
    "slug": "s02a-tool-control-plane",
    "locale": "zh",
    "title": "s02a: Tool Control Plane (工具控制平面)",
    "kind": "bridge",
    "filename": "s02a-tool-control-plane.md",
    "content": "# s02a: Tool Control Plane (工具控制平面)\n\n> 这篇桥接文档用来回答另一个关键问题：\n>\n> **为什么“工具系统”不只是一个 `tool_name -> handler` 的映射表？**\n\n## 这一篇为什么要存在\n\n`s02` 先教你工具注册和分发，这完全正确。  \n因为如果你一开始连工具调用都没做出来，后面的一切都无从谈起。\n\n但当系统长大以后，工具层会逐渐承载越来越多的责任：\n\n- 权限判断\n- MCP 接入\n- 通知发送\n- subagent / teammate 共享状态\n- file state cache\n- 当前消息和当前会话环境\n- 某些工具专属限制\n\n这时候，“工具层”就已经不是一张函数表了。\n\n它更像一条总线：\n\n**模型通过工具名发出动作意图，系统通过工具控制平面决定这条意图在什么环境里执行。**\n\n## 先解释几个名词\n\n### 什么是工具控制平面\n\n这里的“控制平面”可以继续沿用上一份桥接文档的理解：\n\n> 不直接做业务结果，而是负责协调工具如何执行的一层。\n\n它关心的问题不是“这个工具最后返回了什么”，而是：\n\n- 它在哪执行\n- 它有没有权限\n- 它可不可以访问某些共享状态\n- 它是本地工具还是外部工具\n\n### 什么是执行上下文\n\n执行上下文，就是工具运行时能看到的环境。\n\n例如：\n\n- 当前工作目录\n- 当前 app state\n- 当前消息列表\n- 当前权限模式\n- 当前可用 MCP client\n\n### 什么是能力来源\n\n不是所有工具都来自同一个地方。\n\n系统里常见的能力来源有：\n\n- 本地原生工具\n- MCP 外部工具\n- agent 工具\n- task / worktree / team 这类平台工具\n\n## 最小心智模型\n\n工具系统可以先画成 4 层：\n\n```text\n1. ToolSpec\n   模型看见的工具名字、描述、输入 schema\n\n2. Tool Router\n   根据工具名把请求送去正确的能力来源\n\n3. ToolUseContext\n   工具运行时能访问的共享环境\n\n4. Tool Result Envelope\n   把输出包装回主循环\n```\n\n最重要的升级点在第三层：\n\n**更完整系统的核心，不是 tool table，而是 ToolUseContext。**\n\n## 关键数据结构\n\n### 1. ToolSpec\n\n这还是最基础的结构：\n\n```python\ntool = {\n    \"name\": \"read_file\",\n    \"description\": \"Read file contents.\",\n    \"input_schema\": {...},\n}\n```\n\n### 2. ToolDispatchMap\n\n```python\nhandlers = {\n    \"read_file\": read_file,\n    \"write_file\": write_file,\n    \"bash\": run_bash,\n}\n```\n\n这依旧需要，但它不是全部。\n\n### 3. ToolUseContext\n\n教学版可以先做一个简化版本：\n\n```python\ntool_use_context = {\n    \"tools\": handlers,\n    \"permission_context\": {...},\n    \"mcp_clients\": {},\n    \"messages\": [...],\n    \"app_state\": {...},\n    \"notifications\": [],\n    \"cwd\": \"...\",\n}\n```\n\n这个结构的关键点是：\n\n- 工具不再只拿到“输入参数”\n- 工具还能拿到“共享运行环境”\n\n### 4. ToolResultEnvelope\n\n不要把返回值只想成字符串。\n\n更稳妥的形状是：\n\n```python\nresult = {\n    \"ok\": True,\n    \"content\": \"...\",\n    \"is_error\": False,\n    \"attachments\": [],\n}\n```\n\n这样后面你才能平滑承接：\n\n- 普通文本结果\n- 结构化结果\n- 错误结果\n- 附件类结果\n\n## 为什么更完整的系统一定会出现 ToolUseContext\n\n想象两个系统。\n\n### 系统 A：只有 dispatch map\n\n```python\noutput = handlers[tool_name](**tool_input)\n```\n\n这适合最小 demo。\n\n### 系统 B：有 ToolUseContext\n\n```python\noutput = handlers[tool_name](tool_input, tool_use_context)\n```\n\n这个版本才更接近一个真实平台。\n\n因为工具现在不只是“做一个动作”，而是在一个复杂系统里做动作。\n\n例如：\n\n- `bash` 要看权限\n- `mcp__postgres__query` 要找对应 client\n- `agent` 工具要创建子执行环境\n- `task_output` 工具可能要写磁盘并发通知\n\n这些都要求它们共享同一个上下文总线。\n\n## 最小实现\n\n### 第一步：仍然保留 ToolSpec 和 handler\n\n这个主线不要丢。\n\n### 第二步：引入一个统一 context\n\n```python\nclass ToolUseContext:\n    def __init__(self):\n        self.handlers = {}\n        self.permission_context = {}\n        self.mcp_clients = {}\n        self.messages = []\n        self.app_state = {}\n        self.notifications = []\n```\n\n### 第三步：让所有 handler 都能看到 context\n\n```python\ndef run_tool(tool_name: str, tool_input: dict, ctx: ToolUseContext):\n    handler = ctx.handlers[tool_name]\n    return handler(tool_input, ctx)\n```\n\n### 第四步：在 router 层分不同能力来源\n\n```python\ndef route_tool(tool_name: str, tool_input: dict, ctx: ToolUseContext):\n    if tool_name.startswith(\"mcp__\"):\n        return run_mcp_tool(tool_name, tool_input, ctx)\n    return run_native_tool(tool_name, tool_input, ctx)\n```\n\n## 一张应该讲清楚的图\n\n```text\nLLM tool call\n  |\n  v\nTool Router\n  |\n  +-- native tools ----------> local handlers\n  |\n  +-- mcp tools -------------> mcp client\n  |\n  +-- agent/task/team tools --> platform handlers\n            |\n            v\n       ToolUseContext\n         - permissions\n         - messages\n         - app state\n         - notifications\n         - mcp clients\n```\n\n## 它和 `s02`、`s19` 的关系\n\n- `s02` 先教你工具调用为什么成立\n- 这篇解释更完整的系统里工具层为什么会长成一个控制平面\n- `s19` 再把 MCP 作为外部能力来源接进来\n\n也就是说：\n\n**MCP 不是另一套独立系统，而是 Tool Control Plane 的一个能力来源。**\n\n## 初学者最容易犯的错\n\n### 1. 以为工具上下文只是 `cwd`\n\n不是。\n\n更完整的系统里，工具上下文往往还包含权限、状态、外部连接和通知接口。\n\n### 2. 让每个工具自己去全局变量里找环境\n\n这样工具层会变得非常散。\n\n更清楚的做法，是显式传一个统一 context。\n\n### 3. 把本地工具和 MCP 工具拆成完全不同体系\n\n这会让系统边界越来越乱。\n\n更好的方式是：\n\n- 能力来源不同\n- 但都汇入统一 router 和统一 result envelope\n\n### 4. 把 tool result 永远当成纯字符串\n\n这样后面接附件、错误、结构化信息时会很别扭。\n\n## 教学边界\n\n这篇最重要的，不是把工具层做成一个庞大的企业总线，而是先把下面三层边界讲清：\n\n- tool call 不是直接执行，而是先进入统一调度入口\n- 工具 handler 不应该各自去偷拿环境，而应该共享一份显式 `ToolUseContext`\n- 本地工具、插件工具、MCP 工具可以来源不同，但结果都应该回到统一控制面\n\n类型化上下文、能力注册中心、大结果存储和更细的工具限额，都是你把这条最小控制总线讲稳以后再补的扩展。\n\n## 一句话记住\n\n**最小工具系统靠 dispatch map，更完整的工具系统靠 ToolUseContext 这条控制总线。**\n"
  },
  {
    "version": null,
    "slug": "s02b-tool-execution-runtime",
    "locale": "zh",
    "title": "s02b: Tool Execution Runtime (工具执行运行时)",
    "kind": "bridge",
    "filename": "s02b-tool-execution-runtime.md",
    "content": "# s02b: Tool Execution Runtime (工具执行运行时)\n\n> 这篇桥接文档解决的不是“工具怎么注册”，而是：\n>\n> **当模型一口气发出多个工具调用时，系统到底按什么规则执行、并发、回写、合并上下文？**\n\n## 这一篇为什么要存在\n\n`s02` 先教你：\n\n- 工具 schema\n- dispatch map\n- tool_result 回流\n\n这完全正确。  \n因为工具调用先得成立，后面才谈得上复杂度。\n\n但系统一旦长大，真正棘手的问题会变成下面这些：\n\n- 多个工具能不能并行执行\n- 哪些工具必须串行\n- 工具执行过程中要不要先发进度消息\n- 并发工具的结果应该按完成顺序回写，还是按原始出现顺序回写\n- 工具执行会不会改共享上下文\n- 多个并发工具如果都要改上下文，最后怎么合并\n\n这些问题已经不是“工具注册”能解释的了。\n\n它们属于更深一层：\n\n**工具执行运行时。**\n\n## 先解释几个名词\n\n### 什么叫工具执行运行时\n\n这里的运行时，不是指编程语言 runtime。\n\n这里说的是：\n\n> 当工具真正开始执行时，系统用什么规则去调度、并发、跟踪和回写这些工具。\n\n### 什么叫 concurrency safe\n\n你可以先把它理解成：\n\n> 这个工具能不能和别的同类工具同时跑，而不会把共享状态搞乱。\n\n例如很多只读工具常常是 concurrency safe：\n\n- `read_file`\n- 某些搜索工具\n- 某些纯查询类 MCP 工具\n\n而很多写操作不是：\n\n- `write_file`\n- `edit_file`\n- 某些会改全局状态的工具\n\n### 什么叫 progress message\n\n有些工具跑得慢，不适合一直静默。\n\nprogress message 就是：\n\n> 工具还没结束，但系统先把“它正在做什么”告诉上层。\n\n### 什么叫 context modifier\n\n有些工具执行完不只是返回结果，还会修改共享环境。\n\n例如：\n\n- 更新通知队列\n- 更新 app state\n- 更新“哪些工具正在运行”\n\n这种“对共享上下文的修改动作”，就可以理解成 context modifier。\n\n## 最小心智模型\n\n先不要把工具执行想成：\n\n```text\ntool_use -> handler -> result\n```\n\n更接近真实可扩展系统的理解是：\n\n```text\ntool_use blocks\n  ->\n按执行安全性分批\n  ->\n每批决定串行还是并行\n  ->\n执行过程中可能产出 progress\n  ->\n最终按稳定顺序回写结果\n  ->\n必要时再合并 context modifiers\n```\n\n这里最关键的升级点有两个：\n\n- 并发不是默认全开\n- 上下文修改不是谁先跑完谁先直接乱写\n\n## 关键数据结构\n\n### 1. ToolExecutionBatch\n\n教学版最小可以先用这样一个概念：\n\n```python\nbatch = {\n    \"is_concurrency_safe\": True,\n    \"blocks\": [tool_use_1, tool_use_2, tool_use_3],\n}\n```\n\n它的意义是：\n\n- 不是每个工具都单独处理\n- 系统会先把工具调用按可否并发分成一批一批\n\n### 2. TrackedTool\n\n如果你准备把执行层做得更稳、更清楚，建议显式跟踪每个工具：\n\n```python\ntracked_tool = {\n    \"id\": \"toolu_01\",\n    \"name\": \"read_file\",\n    \"status\": \"queued\",   # queued / executing / completed / yielded\n    \"is_concurrency_safe\": True,\n    \"pending_progress\": [],\n    \"results\": [],\n    \"context_modifiers\": [],\n}\n```\n\n这类结构的价值很大。\n\n因为系统终于开始能回答：\n\n- 哪些工具还在排队\n- 哪些已经开始\n- 哪些已经完成\n- 哪些已经先吐出了中间进度\n\n### 3. MessageUpdate\n\n工具执行过程中，不一定只有最终结果。\n\n最小可以先理解成：\n\n```python\nupdate = {\n    \"message\": maybe_message,\n    \"new_context\": current_context,\n}\n```\n\n更完整的执行层里，一个工具执行运行时往往会产出两类更新：\n\n- 要立刻往上游发的消息更新\n- 只影响内部共享环境的 context 更新\n\n### 4. Queued Context Modifiers\n\n这是最容易被忽略、但很关键的一层。\n\n在并发工具批次里，更稳的策略不是“谁先完成谁先改 context”，而是：\n\n> 先把 context modifier 暂存起来，最后按原始工具顺序统一合并。\n\n最小理解方式：\n\n```python\nqueued_context_modifiers = {\n    \"toolu_01\": [modify_ctx_a],\n    \"toolu_02\": [modify_ctx_b],\n}\n```\n\n## 最小实现\n\n### 第一步：先分清哪些工具能并发\n\n```python\ndef is_concurrency_safe(tool_name: str, tool_input: dict) -> bool:\n    return tool_name in {\"read_file\", \"search_files\"}\n```\n\n### 第二步：先分批，再执行\n\n```python\nbatches = partition_tool_calls(tool_uses)\n\nfor batch in batches:\n    if batch[\"is_concurrency_safe\"]:\n        run_concurrently(batch[\"blocks\"])\n    else:\n        run_serially(batch[\"blocks\"])\n```\n\n### 第三步：并发批次先吐进度，再收最终结果\n\n```python\nfor update in run_concurrently(...):\n    if update.get(\"message\"):\n        yield update[\"message\"]\n```\n\n### 第四步：context modifier 不要乱序落地\n\n```python\nqueued_modifiers = {}\n\nfor update in concurrent_updates:\n    if update.get(\"context_modifier\"):\n        queued_modifiers[update[\"tool_id\"]].append(update[\"context_modifier\"])\n\nfor tool in original_batch_order:\n    for modifier in queued_modifiers.get(tool[\"id\"], []):\n        context = modifier(context)\n```\n\n这一步是整篇里最容易被低估，但其实最接近真实系统开始长出执行运行时的点之一。\n\n## 一张真正应该建立的图\n\n```text\ntool_use blocks\n  |\n  v\npartition by concurrency safety\n  |\n  +-- read-only / safe batch -----> concurrent execution\n  |                                   |\n  |                                   +-- progress updates\n  |                                   +-- final results\n  |                                   +-- queued context modifiers\n  |\n  +-- exclusive batch ------------> serial execution\n                                      |\n                                      +-- direct result + direct context update\n```\n\n## 为什么这层比“dispatch map”更接近真实系统主脉络\n\n最小 demo 里：\n\n```python\nhandlers[tool_name](tool_input)\n```\n\n就够了。\n\n但在更完整系统里，真正复杂的不是“找到 handler”。\n\n真正复杂的是：\n\n- 多工具之间如何共存\n- 哪些能并发\n- 并发时如何保证回写顺序稳定\n- 并发时如何避免共享 context 被抢写\n- 工具报错时是否中止其他工具\n\n所以这层讲的不是边角优化，而是：\n\n> 工具系统从“可调用”升级到“可调度”的关键一步。\n\n## 它和前后章节怎么接\n\n- `s02` 先教你工具为什么能被调用\n- [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) 讲工具为什么会长成统一控制面\n- 这篇继续讲，工具真的开始运行以后，系统如何调度它们\n- `s07`、`s13`、`s19` 往后都还会继续用到这层心智\n\n尤其是：\n\n- 权限系统会影响工具能不能执行\n- 后台任务会影响工具是否立即结束\n- MCP / plugin 会让工具来源更多、执行形态更复杂\n\n## 初学者最容易犯的错\n\n### 1. 看到多个工具调用，就默认全部并发\n\n这样很容易把共享状态搞乱。\n\n### 2. 只按完成顺序回写结果\n\n如果你完全按“谁先跑完谁先写”，主循环看到的顺序会越来越不稳定。\n\n### 3. 并发工具直接同时改共享 context\n\n这会制造很多很难解释的隐性状态问题。\n\n### 4. 认为 progress message 是“可有可无的 UI 装饰”\n\n它其实会影响：\n\n- 上层何时知道工具还活着\n- 长工具调用期间用户是否困惑\n- streaming 执行体验是否稳定\n\n### 5. 只讲工具 schema，不讲工具调度\n\n这样读者最后只会“注册工具”，却不理解真实 agent 为什么还要长出工具执行运行时。\n\n## 教学边界\n\n这篇最重要的，不是把工具调度层一次讲成一个庞大 runtime，而是先让读者守住三件事：\n\n- 工具调用要先分批，而不是默认看到多个 `tool_use` 就全部并发\n- 并发执行和稳定回写是两件事，不应该混成一个动作\n- 共享 context 的修改最好先排队，再按稳定顺序统一合并\n\n只要这三条边界已经清楚，后面的权限、后台任务和 MCP 接入就都有地方挂。  \n更细的队列模型、取消策略、流式输出协议，都可以放到你把这条最小运行时自己手搓出来以后再补。\n\n## 读完这一篇你应该能说清楚\n\n至少能完整说出这句话：\n\n> 工具系统不只是 `tool_name -> handler`，它还需要一层执行运行时来决定哪些工具并发、哪些串行、结果如何回写、共享上下文如何稳定合并。\n\n如果这句话你已经能稳定说清，那么你对 agent 工具层的理解，就已经比“会注册几个工具”深一大层了。\n"
  },
  {
    "version": "s03",
    "slug": "s03-todo-write",
    "locale": "zh",
    "title": "s03: TodoWrite (会话内规划)",
    "kind": "chapter",
    "filename": "s03-todo-write.md",
    "content": "# s03: TodoWrite (会话内规划)\n\n`s00 > s01 > s02 > [ s03 ] > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *计划不是替模型思考，而是把“正在做什么”明确写出来。*\n\n## 这一章要解决什么问题\n\n到了 `s02`，agent 已经会读文件、写文件、跑命令。\n\n问题也马上出现了：\n\n- 多步任务容易走一步忘一步\n- 明明已经做过的检查，会重复再做\n- 一口气列出很多步骤后，很快又回到即兴发挥\n\n这是因为模型虽然“能想”，但它的当前注意力始终受上下文影响。  \n如果没有一块**显式、稳定、可反复更新**的计划状态，大任务就很容易漂。\n\n所以这一章要补上的，不是“更强的工具”，而是：\n\n**让 agent 把当前会话里的计划外显出来，并且持续更新。**\n\n## 先解释几个名词\n\n### 什么是会话内规划\n\n这里说的规划，不是长期项目管理，也不是磁盘上的任务系统。\n\n它更像：\n\n> 为了完成当前这次请求，先把接下来几步写出来，并在过程中不断更新。\n\n### 什么是 todo\n\n`todo` 在这一章里只是一个载体。\n\n你不要把它理解成“某个特定产品里的某个工具名”，更应该把它理解成：\n\n> 模型用来写入当前计划的一条入口。\n\n### 什么是 active step\n\n`active step` 可以理解成“当前正在做的那一步”。\n\n教学版里我们用 `in_progress` 表示它。  \n这么做的目的不是形式主义，而是帮助模型维持焦点：\n\n> 同一时间，先把一件事做完，再进入下一件。\n\n### 什么是提醒\n\n提醒不是替模型规划，而是当它连续几轮都忘记更新计划时，轻轻拉它回来。\n\n## 先立清边界：这章不是任务系统\n\n这是这一章最重要的边界。\n\n`s03` 讲的是：\n\n- 当前会话里的轻量计划\n- 用来帮助模型聚焦下一步\n- 可以随任务推进不断改写\n\n它**不是**：\n\n- 持久化任务板\n- 依赖图\n- 多 agent 共用的工作图\n- 后台运行时任务管理\n\n这些会在 `s12-s14` 再系统展开。\n\n如果你现在就把 `s03` 讲成完整任务平台，初学者会很快混淆：\n\n- “当前这一步要做什么”\n- “整个系统长期还有哪些工作项”\n\n## 最小心智模型\n\n把这一章先想成一个很简单的结构：\n\n```text\n用户提出大任务\n   |\n   v\n模型先写一份当前计划\n   |\n   v\n计划状态\n  - [ ] 还没做\n  - [>] 正在做\n  - [x] 已完成\n   |\n   v\n每做完一步，就更新计划\n```\n\n更具体一点：\n\n```text\n1. 先拆几步\n2. 选一项作为当前 active step\n3. 做完后标记 completed\n4. 把下一项改成 in_progress\n5. 如果好几轮没更新，系统提醒一下\n```\n\n这就是最小版本最该教清楚的部分。\n\n## 关键数据结构\n\n### 1. PlanItem\n\n最小条目可以长这样：\n\n```python\n{\n    \"content\": \"Read the failing test\",\n    \"status\": \"pending\" | \"in_progress\" | \"completed\",\n    \"activeForm\": \"Reading the failing test\",\n}\n```\n\n这里的字段分别表示：\n\n- `content`：这一步要做什么\n- `status`：这一步现在处在什么状态\n- `activeForm`：当它正在进行中时，可以用更自然的进行时描述\n\n### 2. PlanningState\n\n除了计划条目本身，还应该有一点最小运行状态：\n\n```python\n{\n    \"items\": [...],\n    \"rounds_since_update\": 0,\n}\n```\n\n`rounds_since_update` 的意思很简单：\n\n> 连续多少轮过去了，模型还没有更新这份计划。\n\n### 3. 状态约束\n\n教学版推荐先立一条简单规则：\n\n```text\n同一时间，最多一个 in_progress\n```\n\n这不是宇宙真理。  \n它只是一个非常适合初学者的教学约束：\n\n**强制模型聚焦当前一步。**\n\n## 最小实现\n\n### 第一步：准备一个计划管理器\n\n```python\nclass TodoManager:\n    def __init__(self):\n        self.items = []\n```\n\n### 第二步：允许模型整体更新当前计划\n\n```python\ndef update(self, items: list) -> str:\n    validated = []\n    in_progress_count = 0\n\n    for item in items:\n        status = item.get(\"status\", \"pending\")\n        if status == \"in_progress\":\n            in_progress_count += 1\n        validated.append({\n            \"content\": item[\"content\"],\n            \"status\": status,\n            \"activeForm\": item.get(\"activeForm\", \"\"),\n        })\n\n    if in_progress_count > 1:\n        raise ValueError(\"Only one item can be in_progress\")\n\n    self.items = validated\n    return self.render()\n```\n\n教学版让模型“整份重写”当前计划，比做一堆局部增删改更容易理解。\n\n### 第三步：把计划渲染成可读文本\n\n```python\ndef render(self) -> str:\n    lines = []\n    for item in self.items:\n        marker = {\n            \"pending\": \"[ ]\",\n            \"in_progress\": \"[>]\",\n            \"completed\": \"[x]\",\n        }[item[\"status\"]]\n        lines.append(f\"{marker} {item['content']}\")\n    return \"\\n\".join(lines)\n```\n\n### 第四步：把 `todo` 接成一个工具\n\n```python\nTOOL_HANDLERS = {\n    \"read_file\": run_read,\n    \"write_file\": run_write,\n    \"edit_file\": run_edit,\n    \"bash\": run_bash,\n    \"todo\": lambda **kw: TODO.update(kw[\"items\"]),\n}\n```\n\n### 第五步：如果连续几轮没更新计划，就提醒\n\n```python\nif rounds_since_update >= 3:\n    results.insert(0, {\n        \"type\": \"text\",\n        \"text\": \"<reminder>Refresh your plan before continuing.</reminder>\",\n    })\n```\n\n这一步的核心意义不是“催促”本身，而是：\n\n> 系统开始把“计划状态是否失活”也看成主循环的一部分。\n\n## 它如何接到主循环里\n\n这一章以后，主循环不再只维护：\n\n- `messages`\n\n还开始维护一份额外的会话状态：\n\n- `PlanningState`\n\n也就是说，agent loop 现在不只是在“对话”。\n\n它还在维持一块当前工作面板：\n\n```text\nmessages          -> 模型看到的历史\nplanning state    -> 当前计划的显式外部状态\n```\n\n这就是这一章真正想让你学会的升级：\n\n**把“当前要做什么”从模型脑内，移到系统可观察的状态里。**\n\n## 为什么这章故意不讲成任务图\n\n因为这里的重点是：\n\n- 帮模型聚焦下一步\n- 让当前进度变得外显\n- 给主循环一个“过程性状态”\n\n而不是：\n\n- 任务依赖\n- 长期持久化\n- 多人协作任务板\n- 后台运行槽位\n\n如果你已经开始关心这些问题，说明你快进入：\n\n- [`s12-task-system.md`](./s12-task-system.md)\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n\n## 初学者最容易犯的错\n\n### 1. 把计划写得过长\n\n计划不是越多越好。\n\n如果一上来列十几步，模型很快就会失去维护意愿。\n\n### 2. 不区分“当前一步”和“未来几步”\n\n如果同时有很多个 `in_progress`，焦点就会散。\n\n### 3. 把会话计划当成长期任务系统\n\n这会让 `s03` 和 `s12` 的边界完全混掉。\n\n### 4. 只在开始时写一次计划，后面从不更新\n\n那这份计划就失去价值了。\n\n### 5. 以为 reminder 是可有可无的小装饰\n\n不是。\n\n提醒机制说明了一件很重要的事：\n\n> 主循环不仅要执行动作，还要维护动作过程中的结构化状态。\n\n## 教学边界\n\n这一章讲的是：\n\n**会话里的外显计划状态。**\n\n它还不是后面那种持久任务系统，所以边界要守住：\n\n- 这里的 `todo` 只服务当前会话，不负责跨阶段持久化\n- `{id, text, status}` 这种小结构已经够教会核心模式\n- reminder 直接一点没问题，重点是让模型持续更新计划\n\n这一章真正要让读者看见的是：\n\n**当计划进入结构化状态，而不是散在自然语言里时，agent 的漂移会明显减少。**\n\n## 一句话记住\n\n**`s03` 的 todo，不是任务平台，而是当前会话里的“外显计划状态”。**\n"
  },
  {
    "version": "s04",
    "slug": "s04-subagent",
    "locale": "zh",
    "title": "s04: Subagents (子智能体)",
    "kind": "chapter",
    "filename": "s04-subagent.md",
    "content": "# s04: Subagents (子智能体)\n\n`s00 > s01 > s02 > s03 > [ s04 ] > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *一个大任务，不一定要塞进一个上下文里做完。*\n\n## 这一章到底要解决什么问题\n\n当 agent 连续做很多事时，`messages` 会越来越长。\n\n比如用户只问：\n\n> “这个项目用什么测试框架？”\n\n但 agent 可能为了回答这个问题：\n\n- 读了 `pyproject.toml`\n- 读了 `requirements.txt`\n- 搜了 `pytest`\n- 跑了测试命令\n\n真正有价值的最终答案，可能只有一句话：\n\n> “这个项目主要用 `pytest`。”\n\n如果这些中间过程都永久堆在父对话里，后面的问题会越来越难回答，因为上下文被大量局部任务的噪声填满了。\n\n这就是子智能体要解决的问题：\n\n**把局部任务放进独立上下文里做，做完只把必要结果带回来。**\n\n## 先解释几个名词\n\n### 什么是“父智能体”\n\n当前正在和用户对话、持有主 `messages` 的 agent，就是父智能体。\n\n### 什么是“子智能体”\n\n父智能体临时派生出来，专门处理某个子任务的 agent，就是子智能体。\n\n### 什么叫“上下文隔离”\n\n意思是：\n\n- 父智能体有自己的 `messages`\n- 子智能体也有自己的 `messages`\n- 子智能体的中间过程不会自动写回父智能体\n\n## 最小心智模型\n\n```text\nParent agent\n  |\n  | 1. 决定把一个局部任务外包出去\n  v\nSubagent\n  |\n  | 2. 在自己的上下文里读文件 / 搜索 / 执行工具\n  v\nSummary\n  |\n  | 3. 只把最终摘要或结果带回父智能体\n  v\nParent agent continues\n```\n\n最重要的点只有一个：\n\n**子智能体的价值，不是“多一个模型实例”本身，而是“多一个干净上下文”。**\n\n## 最小实现长什么样\n\n### 第一步：给父智能体一个 `task` 工具\n\n父智能体需要一个工具，让模型可以主动说：\n\n> “这个子任务我想交给一个独立上下文去做。”\n\n最小 schema 可以非常简单：\n\n```python\n{\n    \"name\": \"task\",\n    \"description\": \"Run a subtask in a clean context and return a summary.\",\n    \"input_schema\": {\n        \"type\": \"object\",\n        \"properties\": {\n            \"prompt\": {\"type\": \"string\"}\n        },\n        \"required\": [\"prompt\"]\n    }\n}\n```\n\n### 第二步：子智能体使用自己的消息列表\n\n```python\ndef run_subagent(prompt: str) -> str:\n    sub_messages = [{\"role\": \"user\", \"content\": prompt}]\n    ...\n```\n\n这就是隔离的关键。\n\n不是共享父智能体的 `messages`，而是从一份新的列表开始。\n\n### 第三步：子智能体只拿必要工具\n\n子智能体通常不需要拥有和父智能体完全一样的能力。\n\n最小版本里，常见做法是：\n\n- 给它文件读取、搜索、bash 之类的基础工具\n- 不给它继续派生子智能体的能力\n\n这样可以防止它无限递归。\n\n### 第四步：只把结果带回父智能体\n\n子智能体做完事后，不把全部内部历史写回去，而是返回一段总结。\n\n```python\nreturn {\n    \"type\": \"tool_result\",\n    \"tool_use_id\": block.id,\n    \"content\": summary_text,\n}\n```\n\n## 这一章最关键的数据结构\n\n如果你只记一个结构，就记这个：\n\n```python\nclass SubagentContext:\n    messages: list\n    tools: list\n    handlers: dict\n    max_turns: int\n```\n\n解释一下：\n\n- `messages`：子智能体自己的上下文\n- `tools`：子智能体可以调用哪些工具\n- `handlers`：这些工具到底对应哪些 Python 函数\n- `max_turns`：防止子智能体无限跑\n\n这就是最小子智能体的骨架。\n\n## 为什么它真的有用\n\n### 用处 1：给父上下文减负\n\n局部任务的中间噪声不会全都留在主对话里。\n\n### 用处 2：让任务描述更清楚\n\n一个子智能体接到的 prompt 可以非常聚焦：\n\n- “读完这几个文件，给我一句总结”\n- “检查这个目录里有没有测试”\n- “对这个函数写一个最小修复”\n\n### 用处 3：让后面的多 agent 协作有基础\n\n你可以把子智能体理解成多 agent 系统的最小起点。\n\n先把一次性子任务外包做明白，后面再升级到长期 teammate、任务认领、团队协议，会顺很多。\n\n## 从 0 到 1 的实现顺序\n\n推荐按这个顺序写：\n\n### 版本 1：空白上下文子智能体\n\n先只实现：\n\n- 一个 `task` 工具\n- 一个 `run_subagent(prompt)` 函数\n- 子智能体自己的 `messages`\n- 子智能体最后返回摘要\n\n这已经够了。\n\n### 版本 2：限制工具集\n\n给子智能体一个更小、更安全的工具集。\n\n比如：\n\n- 允许 `read_file`\n- 允许 `grep`\n- 允许只读 bash\n- 不允许 `task`\n\n### 版本 3：加入最大轮数和失败保护\n\n至少补两个保护：\n\n- 最多跑多少轮\n- 工具出错时怎么退出\n\n### 版本 4：再考虑 fork\n\n只有当你已经稳定跑通前面三步，才考虑 fork。\n\n## 什么是 fork，为什么它是“下一步”，不是“起步”\n\n前面的最小实现是：\n\n- 子智能体从空白上下文开始\n\n这叫最朴素的子智能体。\n\n但有时一个子任务必须知道父智能体之前在聊什么。\n\n例如：\n\n> “基于我们刚才已经讨论出来的方案，去补测试。”\n\n这时可以用 `fork`：\n\n- 不是从空白 `messages` 开始\n- 而是先复制父智能体的已有上下文，再追加子任务 prompt\n\n```python\nsub_messages = list(parent_messages)\nsub_messages.append({\"role\": \"user\", \"content\": prompt})\n```\n\n这就是 fork 的本质：\n\n**继承上下文，而不是重头开始。**\n\n## 初学者最容易踩的坑\n\n### 坑 1：把子智能体当成“为了炫技的并发”\n\n子智能体首先是为了解决上下文问题，不是为了展示“我有很多 agent”。\n\n### 坑 2：把父历史全部原样灌回去\n\n如果你最后又把子智能体全量历史粘回父对话，那隔离价值就几乎没了。\n\n### 坑 3：一上来就做特别复杂的角色系统\n\n比如一开始就加：\n\n- explorer\n- reviewer\n- planner\n- tester\n- implementer\n\n这些都可以做，但不应该先做。\n\n先把“一个干净上下文的子任务执行器”做对，后面角色化只是在它上面再包一层。\n\n### 坑 4：忘记给子智能体设置停止条件\n\n如果没有：\n\n- 最大轮数\n- 异常处理\n- 工具过滤\n\n子智能体很容易无限转。\n\n## 教学边界\n\n这章要先打牢的，不是“多 agent 很高级”，而是：\n\n**子智能体首先是一个上下文边界。**\n\n所以教学版先停在这里就够了：\n\n- 一次性子任务就够\n- 摘要返回就够\n- 新 `messages` + 工具过滤就够\n\n不要提前把 `fork`、后台运行、transcript 持久化、worktree 绑定一起塞进来。\n\n真正该守住的顺序仍然是：\n\n**先做隔离，再做高级化。**\n\n## 和后续章节的关系\n\n- `s04` 解决的是“局部任务的上下文隔离”\n- `s15-s17` 解决的是“多个长期角色如何协作”\n- `s18` 解决的是“多个执行者如何在文件系统层面隔离”\n\n它们不是重复关系，而是递进关系。\n\n## 这一章学完后，你应该能回答\n\n- 为什么大任务不应该总塞在一个 `messages` 里？\n- 子智能体最小版为什么只需要独立上下文和摘要返回？\n- fork 是什么，为什么它不该成为第一步？\n- 为什么子智能体的第一价值是“减噪”，而不是“炫多 agent”？\n\n---\n\n**一句话记住：子智能体的核心，不是多一个角色，而是多一个干净上下文。**\n"
  },
  {
    "version": "s05",
    "slug": "s05-skill-loading",
    "locale": "zh",
    "title": "s05: Skills (按需知识加载)",
    "kind": "chapter",
    "filename": "s05-skill-loading.md",
    "content": "# s05: Skills (按需知识加载)\n\n`s00 > s01 > s02 > s03 > s04 > [ s05 ] > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *不是把所有知识永远塞进 prompt，而是在需要的时候再加载正确那一份。*\n\n## 这一章要解决什么问题\n\n到了 `s04`，你的 agent 已经会：\n\n- 调工具\n- 做会话内规划\n- 把大任务分给子 agent\n\n接下来很自然会遇到另一个问题：\n\n> 不同任务需要的领域知识不一样。\n\n例如：\n\n- 做代码审查，需要一套审查清单\n- 做 Git 操作，需要一套提交约定\n- 做 MCP 集成，需要一套专门步骤\n\n如果你把这些知识包全部塞进 system prompt，就会出现两个问题：\n\n1. 大部分 token 都浪费在当前用不到的说明上\n2. prompt 越来越臃肿，主线规则越来越不清楚\n\n所以这一章真正要做的是：\n\n**把“长期可选知识”从 system prompt 主体里拆出来，改成按需加载。**\n\n## 先解释几个名词\n\n### 什么是 skill\n\n这里的 `skill` 可以先简单理解成：\n\n> 一份围绕某类任务的可复用说明书。\n\n它通常会告诉 agent：\n\n- 什么时候该用它\n- 做这类任务时有哪些步骤\n- 有哪些注意事项\n\n### 什么是 discovery\n\n`discovery` 指“发现有哪些 skill 可用”。\n\n这一层只需要很轻量的信息，例如：\n\n- skill 名字\n- 一句描述\n\n### 什么是 loading\n\n`loading` 指“把某个 skill 的完整正文真正读进来”。\n\n这一层才是昂贵的，因为它会把完整内容放进当前上下文。\n\n## 最小心智模型\n\n把这一章先理解成两层：\n\n```text\n第 1 层：轻量目录\n  - skill 名称\n  - skill 描述\n  - 让模型知道“有哪些可用”\n\n第 2 层：按需正文\n  - 只有模型真正需要时才加载\n  - 通过工具结果注入当前上下文\n```\n\n可以画成这样：\n\n```text\nsystem prompt\n  |\n  +-- Skills available:\n      - code-review: review checklist\n      - git-workflow: branch and commit guidance\n      - mcp-builder: build an MCP server\n```\n\n当模型判断自己需要某份知识时：\n\n```text\nload_skill(\"code-review\")\n   |\n   v\ntool_result\n   |\n   v\n<skill name=\"code-review\">\n完整审查说明\n</skill>\n```\n\n这就是这一章最核心的设计。\n\n## 关键数据结构\n\n### 1. SkillManifest\n\n先准备一份很轻的元信息：\n\n```python\n{\n    \"name\": \"code-review\",\n    \"description\": \"Checklist for reviewing code changes\",\n}\n```\n\n它的作用只是让模型知道：\n\n> 这份 skill 存在，并且大概是干什么的。\n\n### 2. SkillDocument\n\n真正被加载时，再读取完整内容：\n\n```python\n{\n    \"manifest\": {...},\n    \"body\": \"... full skill text ...\",\n}\n```\n\n### 3. SkillRegistry\n\n你最好不要把 skill 散着读取。\n\n更清楚的方式是做一个统一注册表：\n\n```python\nregistry = {\n    \"code-review\": SkillDocument(...),\n    \"git-workflow\": SkillDocument(...),\n}\n```\n\n它至少要能回答两个问题：\n\n1. 有哪些 skill 可用\n2. 某个 skill 的完整内容是什么\n\n## 最小实现\n\n### 第一步：把每个 skill 放成一个目录\n\n最小结构可以这样：\n\n```text\nskills/\n  code-review/\n    SKILL.md\n  git-workflow/\n    SKILL.md\n```\n\n### 第二步：从 `SKILL.md` 里读取最小元信息\n\n```python\nclass SkillRegistry:\n    def __init__(self, skills_dir):\n        self.skills = {}\n        self._load_all()\n\n    def _load_all(self):\n        for path in skills_dir.rglob(\"SKILL.md\"):\n            meta, body = parse_frontmatter(path.read_text())\n            name = meta.get(\"name\", path.parent.name)\n            self.skills[name] = {\n                \"manifest\": {\n                    \"name\": name,\n                    \"description\": meta.get(\"description\", \"\"),\n                },\n                \"body\": body,\n            }\n```\n\n这里的 `frontmatter` 你可以先简单理解成：\n\n> 放在正文前面的一小段结构化元数据。\n\n### 第三步：把 skill 目录放进 system prompt\n\n```python\nSYSTEM = f\"\"\"You are a coding agent.\nSkills available:\n{SKILL_REGISTRY.describe_available()}\n\"\"\"\n```\n\n注意这里放的是**目录信息**，不是完整正文。\n\n### 第四步：提供一个 `load_skill` 工具\n\n```python\nTOOL_HANDLERS = {\n    \"load_skill\": lambda **kw: SKILL_REGISTRY.load_full_text(kw[\"name\"]),\n}\n```\n\n当模型调用它时，把完整 skill 正文作为 `tool_result` 返回。\n\n### 第五步：让 skill 正文只在当前需要时进入上下文\n\n这一步的核心思想就是：\n\n> 平时只展示“有哪些知识包”，真正工作时才把那一包展开。\n\n## skill、memory、CLAUDE.md 的边界\n\n这三个概念很容易混。\n\n### skill\n\n可选知识包。  \n只有在某类任务需要时才加载。\n\n### memory\n\n跨会话仍然有价值的信息。  \n它是系统记住的东西，不是任务手册。\n\n### CLAUDE.md\n\n更稳定、更长期的规则说明。  \n它通常比单个 skill 更“全局”。\n\n一个简单判断法：\n\n- 这是某类任务才需要的做法或知识：`skill`\n- 这是需要长期记住的事实或偏好：`memory`\n- 这是更稳定的全局规则：`CLAUDE.md`\n\n## 它如何接到主循环里\n\n这一章以后，system prompt 不再只是一段固定身份说明。\n\n它开始长出一个很重要的新段落：\n\n- 可用技能目录\n\n而消息流里则会出现新的按需注入内容：\n\n- 某个 skill 的完整正文\n\n也就是说，系统输入现在开始分成两层：\n\n```text\n稳定层：\n  身份、规则、工具、skill 目录\n\n按需层：\n  当前真的加载进来的 skill 正文\n```\n\n这也是 `s10` 会继续系统化展开的东西。\n\n## 初学者最容易犯的错\n\n### 1. 把所有 skill 正文永远塞进 system prompt\n\n这样会让 prompt 很快臃肿到难以维护。\n\n### 2. skill 目录信息写得太弱\n\n如果只有名字，没有描述，模型就不知道什么时候该加载它。\n\n### 3. 把 skill 当成“绝对规则”\n\nskill 更像“可选工作手册”，不是所有轮次都必须用。\n\n### 4. 把 skill 和 memory 混成一类\n\nskill 解决的是“怎么做一类事”，memory 解决的是“记住长期事实”。\n\n### 5. 一上来就讲太多多源加载细节\n\n教学主线真正要先讲清的是：\n\n**轻量发现，重内容按需加载。**\n\n## 教学边界\n\n这章只要先守住两层就够了：\n\n- 轻量发现：先告诉模型有哪些 skill\n- 按需深加载：真正需要时再把正文放进输入\n\n所以这里不用提前扩到：\n\n- 多来源收集\n- 条件激活\n- skill 参数化\n- fork 式执行\n- 更复杂的 prompt 管道拼装\n\n如果读者已经明白“为什么不能把所有 skill 永远塞进 system prompt，而应该先列目录、再按需加载”，这章就已经讲到位了。\n\n## 一句话记住\n\n**Skill 系统的核心，不是“多一个工具”，而是“把可选知识从常驻 prompt 里拆出来，改成按需加载”。**\n"
  },
  {
    "version": "s06",
    "slug": "s06-context-compact",
    "locale": "zh",
    "title": "s06: Context Compact (上下文压缩)",
    "kind": "chapter",
    "filename": "s06-context-compact.md",
    "content": "# s06: Context Compact (上下文压缩)\n\n`s00 > s01 > s02 > s03 > s04 > s05 > [ s06 ] > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *上下文不是越多越好，而是要把“仍然有用的部分”留在活跃工作面里。*\n\n## 这一章要解决什么问题\n\n到了 `s05`，agent 已经会：\n\n- 读写文件\n- 规划步骤\n- 派子 agent\n- 按需加载 skill\n\n也正因为它会做的事情更多了，上下文会越来越快膨胀：\n\n- 读一个大文件，会塞进很多文本\n- 跑一条长命令，会得到大段输出\n- 多轮任务推进后，旧结果会越来越多\n\n如果没有压缩机制，很快就会出现这些问题：\n\n1. 模型注意力被旧结果淹没\n2. API 请求越来越重，越来越贵\n3. 最终直接撞上上下文上限，任务中断\n\n所以这一章真正要解决的是：\n\n**怎样在不丢掉主线连续性的前提下，把活跃上下文重新腾出空间。**\n\n## 先解释几个名词\n\n### 什么是上下文窗口\n\n你可以把上下文窗口理解成：\n\n> 模型这一轮真正能一起看到的输入容量。\n\n它不是无限的。\n\n### 什么是活跃上下文\n\n并不是历史上出现过的所有内容，都必须一直留在窗口里。\n\n活跃上下文更像：\n\n> 当前这几轮继续工作时，最值得模型马上看到的那一部分。\n\n### 什么是压缩\n\n这里的压缩，不是 ZIP 压缩文件。\n\n它的意思是：\n\n> 用更短的表示方式，保留继续工作真正需要的信息。\n\n例如：\n\n- 大输出只保留预览，全文写到磁盘\n- 很久以前的工具结果改成占位提示\n- 整段长历史总结成一份摘要\n\n## 最小心智模型\n\n这一章建议你先记三层，不要一上来记八层十层：\n\n```text\n第 1 层：大结果不直接塞进上下文\n  -> 写到磁盘，只留预览\n\n第 2 层：旧结果不一直原样保留\n  -> 替换成简短占位\n\n第 3 层：整体历史太长时\n  -> 生成一份连续性摘要\n```\n\n可以画成这样：\n\n```text\ntool output\n   |\n   +-- 太大 -----------------> 保存到磁盘 + 留预览\n   |\n   v\nmessages\n   |\n   +-- 太旧 -----------------> 替换成占位提示\n   |\n   v\nif whole context still too large:\n   |\n   v\ncompact history -> summary\n```\n\n手动触发 `/compact` 或 `compact` 工具，本质上也是走第 3 层。\n\n## 关键数据结构\n\n### 1. Persisted Output Marker\n\n当工具输出太大时，不要把全文强塞进当前对话。\n\n最小标记可以长这样：\n\n```text\n<persisted-output>\nFull output saved to: .task_outputs/tool-results/abc123.txt\nPreview:\n...\n</persisted-output>\n```\n\n这个结构表达的是：\n\n- 全文没有丢\n- 只是搬去了磁盘\n- 当前上下文里只保留一个足够让模型继续判断的预览\n\n### 2. CompactState\n\n最小教学版建议你显式维护一份压缩状态：\n\n```python\n{\n    \"has_compacted\": False,\n    \"last_summary\": \"\",\n    \"recent_files\": [],\n}\n```\n\n这里的字段分别表示：\n\n- `has_compacted`：这一轮之前是否已经做过完整压缩\n- `last_summary`：最近一次压缩得到的摘要\n- `recent_files`：最近碰过哪些文件，压缩后方便继续追踪\n\n### 3. Micro-Compact Boundary\n\n教学版可以先设一条简单规则：\n\n```text\n只保留最近 3 个工具结果的完整内容\n更旧的改成占位提示\n```\n\n这就已经足够让初学者理解：\n\n**不是所有历史都要原封不动地一直带着跑。**\n\n## 最小实现\n\n### 第一步：大工具结果先写磁盘\n\n```python\ndef persist_large_output(tool_use_id: str, output: str) -> str:\n    if len(output) <= PERSIST_THRESHOLD:\n        return output\n\n    stored_path = save_to_disk(tool_use_id, output)\n    preview = output[:2000]\n    return (\n        \"<persisted-output>\\n\"\n        f\"Full output saved to: {stored_path}\\n\"\n        f\"Preview:\\n{preview}\\n\"\n        \"</persisted-output>\"\n    )\n```\n\n这一步的关键思想是：\n\n> 让模型知道“发生了什么”，但不强迫它一直背着整份原始大输出。\n\n### 第二步：旧工具结果做微压缩\n\n```python\ndef micro_compact(messages: list) -> list:\n    tool_results = collect_tool_results(messages)\n    for result in tool_results[:-3]:\n        result[\"content\"] = \"[Earlier tool result omitted for brevity]\"\n    return messages\n```\n\n这一步不是为了优雅，而是为了防止上下文被旧结果持续霸占。\n\n### 第三步：整体历史过长时，做一次完整压缩\n\n```python\ndef compact_history(messages: list) -> list:\n    summary = summarize_conversation(messages)\n    return [{\n        \"role\": \"user\",\n        \"content\": (\n            \"This conversation was compacted for continuity.\\n\\n\"\n            + summary\n        ),\n    }]\n```\n\n这里最重要的不是摘要格式多么复杂，而是你要保住这几类信息：\n\n- 当前目标是什么\n- 已经做了什么\n- 改过哪些文件\n- 还有什么没完成\n- 哪些决定不能丢\n\n### 第四步：在主循环里接入压缩\n\n```python\ndef agent_loop(state):\n    while True:\n        state[\"messages\"] = micro_compact(state[\"messages\"])\n\n        if estimate_context_size(state[\"messages\"]) > CONTEXT_LIMIT:\n            state[\"messages\"] = compact_history(state[\"messages\"])\n            state[\"has_compacted\"] = True\n\n        response = call_model(...)\n        ...\n```\n\n### 第五步：手动压缩和自动压缩复用同一条机制\n\n教学版里，`compact` 工具不需要重新发明另一套逻辑。\n\n它只需要表达：\n\n> 用户或模型现在主动要求执行一次完整压缩。\n\n## 压缩后，真正要保住什么\n\n这是这章最容易讲虚的地方。\n\n压缩不是“把历史缩短”这么简单。\n\n真正重要的是：\n\n**让模型还能继续接着干活。**\n\n所以一份合格的压缩结果，至少要保住下面这些东西：\n\n1. 当前任务目标\n2. 已完成的关键动作\n3. 已修改或重点查看过的文件\n4. 关键决定与约束\n5. 下一步应该做什么\n\n如果这些没有保住，那压缩虽然腾出了空间，却打断了工作连续性。\n\n## 它如何接到主循环里\n\n从这一章开始，主循环不再只是：\n\n- 收消息\n- 调模型\n- 跑工具\n\n它还多了一个很关键的责任：\n\n- 管理活跃上下文的预算\n\n也就是说，agent loop 现在开始同时维护两件事：\n\n```text\n任务推进\n上下文预算\n```\n\n这一步非常重要，因为后面的很多机制都会和它联动：\n\n- `s09` memory 决定什么信息值得长期保存\n- `s10` prompt pipeline 决定哪些块应该重新注入\n- `s11` error recovery 会处理压缩不足时的恢复分支\n\n## 初学者最容易犯的错\n\n### 1. 以为压缩等于删除\n\n不是。\n\n更准确地说，是把“不必常驻活跃上下文”的内容换一种表示。\n\n### 2. 只在撞到上限后才临时乱补\n\n更好的做法是从一开始就有三层思路：\n\n- 大结果先落盘\n- 旧结果先缩短\n- 整体过长再摘要\n\n### 3. 摘要只写成一句空话\n\n如果摘要没有保住文件、决定、下一步，它对继续工作没有帮助。\n\n### 4. 把压缩和 memory 混成一类\n\n压缩解决的是：\n\n- 当前会话太长了怎么办\n\nmemory 解决的是：\n\n- 哪些信息跨会话仍然值得保留\n\n### 5. 一上来就给初学者讲过多产品化层级\n\n教学主线先讲清最小正确模型，比堆很多层名词更重要。\n\n## 教学边界\n\n这章不要滑成“所有产品化压缩技巧大全”。\n\n教学版只需要讲清三件事：\n\n1. 什么该留在活跃上下文里\n2. 什么该搬到磁盘或占位标记里\n3. 完整压缩后，哪些连续性信息一定不能丢\n\n这已经足够建立稳定心智：\n\n**压缩不是删历史，而是把细节搬走，好让系统继续工作。**\n\n如果读者已经能用 `persisted output + micro compact + summary compact` 保住长会话连续性，这章就已经够深了。\n\n## 一句话记住\n\n**上下文压缩的核心，不是尽量少字，而是让模型在更短的活跃上下文里，仍然保住继续工作的连续性。**\n"
  },
  {
    "version": "s07",
    "slug": "s07-permission-system",
    "locale": "zh",
    "title": "s07: Permission System (权限系统)",
    "kind": "chapter",
    "filename": "s07-permission-system.md",
    "content": "# s07: Permission System (权限系统)\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > [ s07 ] > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *模型可以提出行动建议，但真正执行之前，必须先过安全关。*\n\n## 这一章的核心目标\n\n到了 `s06`，你的 agent 已经能读文件、改文件、跑命令、做规划、压缩上下文。\n\n问题也随之出现了：\n\n- 模型可能会写错文件\n- 模型可能会执行危险命令\n- 模型可能会在不该动手的时候动手\n\n所以从这一章开始，系统需要一条新的管道：\n\n**“意图”不能直接变成“执行”，中间必须经过权限检查。**\n\n## 建议联读\n\n- 如果你开始把“模型提议动作”和“系统真的执行动作”混成一件事，先回 [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)，重新确认 query 是怎么进入控制面的。\n- 如果你还没彻底稳住“工具请求为什么不能直接落到 handler”，建议把 [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) 放在手边一起读。\n- 如果你在 `PermissionRule / PermissionDecision / tool_result` 这几层对象上开始打结，先回 [`data-structures.md`](./data-structures.md)，把状态边界重新拆开。\n\n## 先解释几个名词\n\n### 什么是权限系统\n\n权限系统不是“有没有权限”这样一个布尔值。\n\n它更像一条管道，用来回答：\n\n1. 这次调用要不要直接拒绝？\n2. 能不能自动放行？\n3. 剩下的要不要问用户？\n\n### 什么是权限模式\n\n权限模式是系统当前的总体风格。\n\n例如：\n\n- 谨慎一点：大多数操作都问用户\n- 保守一点：只允许读，不允许写\n- 流畅一点：简单安全的操作自动放行\n\n### 什么是规则\n\n规则就是“遇到某种工具调用时，该怎么处理”的小条款。\n\n最小规则通常包含三部分：\n\n```python\n{\n    \"tool\": \"bash\",\n    \"content\": \"sudo *\",\n    \"behavior\": \"deny\",\n}\n```\n\n意思是：\n\n- 针对 `bash`\n- 如果命令内容匹配 `sudo *`\n- 就拒绝\n\n## 最小权限系统应该长什么样\n\n如果你是从 0 开始手写，一个最小但正确的权限系统只需要四步：\n\n```text\ntool_call\n  |\n  v\n1. deny rules     -> 命中了就拒绝\n  |\n  v\n2. mode check     -> 根据当前模式决定\n  |\n  v\n3. allow rules    -> 命中了就放行\n  |\n  v\n4. ask user       -> 剩下的交给用户确认\n```\n\n这四步已经能覆盖教学仓库 80% 的核心需要。\n\n## 为什么顺序是这样\n\n### 第 1 步先看 deny rules\n\n因为有些东西不应该交给“模式”去决定。\n\n比如：\n\n- 明显危险的命令\n- 明显越界的路径\n\n这些应该优先挡掉。\n\n### 第 2 步看 mode\n\n因为模式决定当前会话的大方向。\n\n例如在 `plan` 模式下，系统就应该天然更保守。\n\n### 第 3 步看 allow rules\n\n有些安全、重复、常见的操作可以直接过。\n\n比如：\n\n- 读文件\n- 搜索代码\n- 查看 git 状态\n\n### 第 4 步才 ask\n\n前面都没命中的灰区，才交给用户。\n\n## 推荐先实现的 3 种模式\n\n不要一上来就做特别多模式。  \n先把下面三种做稳：\n\n| 模式 | 含义 | 适合什么场景 |\n|---|---|---|\n| `default` | 未命中规则时问用户 | 日常交互 |\n| `plan` | 只允许读，不允许写 | 计划、审查、分析 |\n| `auto` | 简单安全操作自动过，危险操作再问 | 高流畅度探索 |\n\n先有这三种，你就已经有了一个可用的权限系统。\n\n## 这一章最重要的数据结构\n\n### 1. 权限规则\n\n```python\nPermissionRule = {\n    \"tool\": str,\n    \"behavior\": \"allow\" | \"deny\" | \"ask\",\n    \"path\": str | None,\n    \"content\": str | None,\n}\n```\n\n你不一定一开始就需要 `path` 和 `content` 都支持。  \n但规则至少要能表达：\n\n- 针对哪个工具\n- 命中后怎么处理\n\n### 2. 权限模式\n\n```python\nmode = \"default\" | \"plan\" | \"auto\"\n```\n\n### 3. 权限决策结果\n\n```python\n{\n    \"behavior\": \"allow\" | \"deny\" | \"ask\",\n    \"reason\": \"why this decision was made\"\n}\n```\n\n这三个结构已经足够搭起最小系统。\n\n## 最小实现怎么写\n\n```python\ndef check_permission(tool_name: str, tool_input: dict) -> dict:\n    # 1. deny rules\n    for rule in deny_rules:\n        if matches(rule, tool_name, tool_input):\n            return {\"behavior\": \"deny\", \"reason\": \"matched deny rule\"}\n\n    # 2. mode\n    if mode == \"plan\" and tool_name in WRITE_TOOLS:\n        return {\"behavior\": \"deny\", \"reason\": \"plan mode blocks writes\"}\n    if mode == \"auto\" and tool_name in READ_ONLY_TOOLS:\n        return {\"behavior\": \"allow\", \"reason\": \"auto mode allows reads\"}\n\n    # 3. allow rules\n    for rule in allow_rules:\n        if matches(rule, tool_name, tool_input):\n            return {\"behavior\": \"allow\", \"reason\": \"matched allow rule\"}\n\n    # 4. fallback\n    return {\"behavior\": \"ask\", \"reason\": \"needs confirmation\"}\n```\n\n然后在执行工具前接进去：\n\n```python\ndecision = perms.check(tool_name, tool_input)\n\nif decision[\"behavior\"] == \"deny\":\n    return f\"Permission denied: {decision['reason']}\"\nif decision[\"behavior\"] == \"ask\":\n    ok = ask_user(...)\n    if not ok:\n        return \"Permission denied by user\"\n\nreturn handler(**tool_input)\n```\n\n## Bash 为什么值得单独讲\n\n所有工具里，`bash` 通常最危险。\n\n因为：\n\n- `read_file` 只能读文件\n- `write_file` 只能写文件\n- 但 `bash` 几乎能做任何事\n\n所以你不能只把 bash 当成一个普通字符串。\n\n一个更成熟的系统，通常会把 bash 当成一门小语言来检查。\n\n哪怕教学版不做完整语法分析，也建议至少先挡住这些明显危险点：\n\n- `sudo`\n- `rm -rf`\n- 命令替换\n- 可疑重定向\n- 明显的 shell 元字符拼接\n\n这背后的核心思想只有一句：\n\n**bash 不是普通文本，而是可执行动作描述。**\n\n## 初学者怎么把这章做对\n\n### 第一步：先做 3 个模式\n\n不要一开始就做 6 个模式、10 个来源、复杂 classifier。\n\n先稳稳做出：\n\n- `default`\n- `plan`\n- `auto`\n\n### 第二步：先做 deny / allow 两类规则\n\n这已经足够表达很多现实需求。\n\n### 第三步：给 bash 加最小安全检查\n\n哪怕只是模式匹配版，也比完全裸奔好很多。\n\n### 第四步：加拒绝计数\n\n如果 agent 连续多次被拒绝，说明它可能卡住了。\n\n这时可以：\n\n- 给出提示\n- 建议切到 `plan`\n- 让用户重新澄清目标\n\n## 教学边界\n\n这一章先只讲透一条权限管道就够了：\n\n- 工具意图先进入权限判断\n- 权限结果只分成 `allow / ask / deny`\n- 通过以后才真的执行\n\n先把这条主线做稳，比一开始塞进很多模式名、规则来源、写回配置、额外目录、自动分类器都更重要。\n\n换句话说，这章要先让读者真正理解的是：\n\n**任何工具调用，都不应该直接执行；中间必须先过一条权限管道。**\n\n## 这章不应该讲太多什么\n\n为了不打乱初学者心智，这章不应该过早陷入：\n\n- 企业策略源的全部优先级\n- 非常复杂的自动分类器\n- 产品环境里的所有无头模式细节\n- 某个特定生产代码里的全部 validator 名称\n\n这些东西存在，但不属于第一层理解。\n\n第一层理解只有一句话：\n\n**任何工具调用，都不应该直接执行；中间必须先过一条权限管道。**\n\n## 这一章和后续章节的关系\n\n- `s07` 决定“能不能执行”\n- `s08` 决定“执行前后还能不能插入额外逻辑”\n- `s10` 会把当前模式和权限说明放进 prompt 组装里\n\n所以这章是后面很多机制的安全前提。\n\n## 学完这章后，你应该能回答\n\n- 为什么权限系统不是一个简单开关？\n- 为什么 deny 要先于 allow？\n- 为什么要先做 3 个模式，而不是一上来做很复杂？\n- 为什么 bash 要被特殊对待？\n\n---\n\n**一句话记住：权限系统不是为了让 agent 更笨，而是为了让 agent 的行动先经过一道可靠的安全判断。**\n"
  },
  {
    "version": "s08",
    "slug": "s08-hook-system",
    "locale": "zh",
    "title": "s08: Hook System (Hook 系统)",
    "kind": "chapter",
    "filename": "s08-hook-system.md",
    "content": "# s08: Hook System (Hook 系统)\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > [ s08 ] > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *不改主循环代码，也能在关键时机插入额外行为。*\n\n## 这章要解决什么问题\n\n到了 `s07`，我们已经能在工具执行前做权限判断。\n\n但很多真实需求并不属于“允许 / 拒绝”这条线，而属于：\n\n- 在某个固定时机顺手做一点事\n- 不改主循环主体，也能接入额外规则\n- 让用户或插件在系统边缘扩展能力\n\n例如：\n\n- 会话开始时打印欢迎信息\n- 工具执行前做一次额外检查\n- 工具执行后补一条审计日志\n\n如果每增加一个需求，你都去修改主循环，主循环就会越来越重，最后谁都不敢动。\n\n所以这一章要引入的机制是：\n\n**主循环只负责暴露“时机”，真正的附加行为交给 hook。**\n\n## 建议联读\n\n- 如果你还在把 hook 想成“往主循环里继续塞 if/else”，先回 [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)，重新确认主循环和控制面的边界。\n- 如果你开始把主循环、tool handler、hook side effect 混成一层，建议先看 [`entity-map.md`](./entity-map.md)，把谁负责推进主状态、谁只是旁路观察分开。\n- 如果你准备继续读后面的 prompt、recovery、teams，可以把 [`s00e-reference-module-map.md`](./s00e-reference-module-map.md) 一起放在旁边，因为从这一章开始“控制面 + 侧车扩展”会反复一起出现。\n\n## 什么是 hook\n\n你可以把 `hook` 理解成一个“预留插口”。\n\n意思是：\n\n1. 主系统运行到某个固定时机\n2. 把当前上下文交给 hook\n3. hook 返回结果\n4. 主系统再决定下一步怎么继续\n\n最重要的一句话是：\n\n**hook 让系统可扩展，但不要求主循环理解每个扩展需求。**\n\n主循环只需要知道三件事：\n\n- 现在是什么事件\n- 要把哪些上下文交出去\n- 收到结果以后怎么处理\n\n## 最小心智模型\n\n教学版先只讲 3 个事件：\n\n- `SessionStart`\n- `PreToolUse`\n- `PostToolUse`\n\n这样做不是因为系统永远只有 3 个事件，  \n而是因为初学者先把这 3 个事件学明白，就已经能自己做出一套可用的 hook 机制。\n\n可以把它想成这条流程：\n\n```text\n主循环继续往前跑\n  |\n  +-- 到了某个预留时机\n  |\n  +-- 调用 hook runner\n  |\n  +-- 收到 hook 返回结果\n  |\n  +-- 决定继续、阻止、还是补充说明\n```\n\n## 教学版统一返回约定\n\n这一章最容易把人讲乱的地方，就是“不同 hook 事件的返回语义”。\n\n教学版建议先统一成下面这套规则：\n\n| 退出码 | 含义 |\n|---|---|\n| `0` | 正常继续 |\n| `1` | 阻止当前动作 |\n| `2` | 注入一条补充消息，再继续 |\n\n这套规则的价值不在于“最真实”，而在于“最容易学会”。\n\n因为它让你先记住 hook 最核心的 3 种作用：\n\n- 观察\n- 拦截\n- 补充\n\n等教学版跑通以后，再去做“不同事件采用不同语义”的细化，也不会乱。\n\n## 关键数据结构\n\n### 1. HookEvent\n\n```python\nevent = {\n    \"name\": \"PreToolUse\",\n    \"payload\": {\n        \"tool_name\": \"bash\",\n        \"input\": {\"command\": \"pytest\"},\n    },\n}\n```\n\n它回答的是：\n\n- 现在发生了什么事\n- 这件事的上下文是什么\n\n### 2. HookResult\n\n```python\nresult = {\n    \"exit_code\": 0,\n    \"message\": \"\",\n}\n```\n\n它回答的是：\n\n- hook 想不想阻止主流程\n- 要不要向模型补一条说明\n\n### 3. HookRunner\n\n```python\nclass HookRunner:\n    def run(self, event_name: str, payload: dict) -> dict:\n        ...\n```\n\n主循环不直接关心“每个 hook 的细节实现”。  \n它只把事件交给统一的 runner。\n\n这就是这一章的关键抽象边界：\n\n**主循环知道事件名，hook runner 知道怎么调扩展逻辑。**\n\n## 最小执行流程\n\n先看最重要的 `PreToolUse` / `PostToolUse`：\n\n```text\nmodel 发起 tool_use\n    |\n    v\nrun_hook(\"PreToolUse\", ...)\n    |\n    +-- exit 1 -> 阻止工具执行\n    +-- exit 2 -> 先补一条消息给模型，再继续\n    +-- exit 0 -> 直接继续\n    |\n    v\n执行工具\n    |\n    v\nrun_hook(\"PostToolUse\", ...)\n    |\n    +-- exit 2 -> 追加补充说明\n    +-- exit 0 -> 正常结束\n```\n\n再加上 `SessionStart`，一整套最小 hook 机制就立住了。\n\n## 最小实现\n\n### 第一步：准备一个事件到处理器的映射\n\n```python\nHOOKS = {\n    \"SessionStart\": [on_session_start],\n    \"PreToolUse\": [pre_tool_guard],\n    \"PostToolUse\": [post_tool_log],\n}\n```\n\n这里先用“一个事件对应一组处理函数”的最小结构就够了。\n\n### 第二步：统一运行 hook\n\n```python\ndef run_hooks(event_name: str, payload: dict) -> dict:\n    for handler in HOOKS.get(event_name, []):\n        result = handler(payload)\n        if result[\"exit_code\"] in (1, 2):\n            return result\n    return {\"exit_code\": 0, \"message\": \"\"}\n```\n\n教学版里先用“谁先返回阻止/注入，谁就优先”的简单规则。\n\n### 第三步：接进主循环\n\n```python\npre = run_hooks(\"PreToolUse\", {\n    \"tool_name\": block.name,\n    \"input\": block.input,\n})\n\nif pre[\"exit_code\"] == 1:\n    results.append(blocked_tool_result(pre[\"message\"]))\n    continue\n\nif pre[\"exit_code\"] == 2:\n    messages.append({\"role\": \"user\", \"content\": pre[\"message\"]})\n\noutput = run_tool(...)\n\npost = run_hooks(\"PostToolUse\", {\n    \"tool_name\": block.name,\n    \"input\": block.input,\n    \"output\": output,\n})\n```\n\n这一步最关键的不是代码量，而是心智：\n\n**hook 不是主循环的替代品，hook 是主循环在固定时机对外发出的调用。**\n\n## 这一章的教学边界\n\n如果你后面继续扩展平台，hook 事件面当然会继续扩大。\n\n常见扩展方向包括：\n\n- 生命周期事件：开始、结束、配置变化\n- 工具事件：执行前、执行后、失败后\n- 压缩事件：压缩前、压缩后\n- 多 agent 事件：子 agent 启动、任务完成、队友空闲\n\n但教学仓这里要守住一个原则：\n\n**先把 hook 的统一模型讲清，再慢慢增加事件种类。**\n\n不要一开始就把几十种事件、几十套返回语义全部灌给读者。\n\n## 初学者最容易犯的错\n\n### 1. 把 hook 当成“到处插 if”\n\n如果还是散落在主循环里写条件分支，那还不是真正的 hook 设计。\n\n### 2. 没有统一的返回结构\n\n今天返回字符串，明天返回布尔值，后天返回整数，最后主循环一定会变乱。\n\n### 3. 一上来就把所有事件做全\n\n教学顺序应该是：\n\n1. 先学会 3 个事件\n2. 再学会统一返回协议\n3. 最后才扩事件面\n\n### 4. 忘了说明“教学版统一语义”和“高完成度细化语义”的区别\n\n如果这层不提前说清，读者后面看到更复杂实现时会以为前面学错了。\n\n其实不是学错了，而是：\n\n**先学统一模型，再学事件细化。**\n\n## 学完这一章，你应该真正掌握什么\n\n学完以后，你应该能自己清楚说出下面几句话：\n\n1. hook 的作用，是在固定时机扩展系统，而不是改写主循环。\n2. hook 至少需要“事件名 + payload + 返回结果”这三样东西。\n3. 教学版可以先用统一的 `0 / 1 / 2` 返回约定。\n4. `PreToolUse` 和 `PostToolUse` 已经足够支撑最核心的扩展能力。\n\n如果这 4 句话你已经能独立复述，说明这一章的核心心智已经建立起来了。\n\n## 下一章学什么\n\n这一章解决的是：\n\n> 在固定时机插入行为。\n\n下一章 `s09` 要解决的是：\n\n> 哪些信息应该跨会话留下，哪些不该留。\n\n也就是从“扩展点”进一步走向“持久状态”。\n"
  },
  {
    "version": "s09",
    "slug": "s09-memory-system",
    "locale": "zh",
    "title": "s09: Memory System (记忆系统)",
    "kind": "chapter",
    "filename": "s09-memory-system.md",
    "content": "# s09: Memory System (记忆系统)\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > [ s09 ] > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *不是所有信息都该进入 memory；只有跨会话仍然有价值的信息，才值得留下。*\n\n## 这一章在解决什么问题\n\n如果一个 agent 每次新会话都完全从零开始，它就会不断重复忘记这些事情：\n\n- 用户长期偏好\n- 用户多次纠正过的错误\n- 某些不容易从代码直接看出来的项目约定\n- 某些外部资源在哪里找\n\n这会让系统显得“每次都像第一次合作”。\n\n所以需要 memory。\n\n## 但先立一个边界：memory 不是什么都存\n\n这是这一章最容易讲歪的地方。\n\nmemory 不是“把一切有用信息都记下来”。\n\n如果你这样做，很快就会出现两个问题：\n\n1. memory 变成垃圾堆，越存越乱\n2. agent 开始依赖过时记忆，而不是读取当前真实状态\n\n所以这章必须先立一个原则：\n\n**只有那些跨会话仍然有价值，而且不能轻易从当前仓库状态直接推出来的信息，才适合进入 memory。**\n\n## 建议联读\n\n- 如果你还把 memory 想成“更长一点的上下文窗口”，先回 [`s06-context-compact.md`](./s06-context-compact.md)，重新确认 compact 和长期记忆是两套机制。\n- 如果你在 `messages[]`、摘要块、memory store 这三层之间开始读混，建议边看边对照 [`data-structures.md`](./data-structures.md)。\n- 如果你准备继续读 `s10`，最好把 [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md) 放在旁边，因为 memory 真正重要的是它怎样重新进入下一轮输入。\n\n## 先解释几个名词\n\n### 什么是“跨会话”\n\n意思是：\n\n- 当前对话结束了\n- 下次重新开始一个新对话\n- 这条信息仍然可能有用\n\n### 什么是“不可轻易重新推导”\n\n例如：\n\n- 用户明确说“我讨厌这种写法”\n- 某个架构决定背后的真实原因是合规要求\n- 某个团队总在某个外部看板里跟踪问题\n\n这些东西，往往不是你重新扫一遍代码就能立刻知道的。\n\n## 最适合先教的 4 类 memory\n\n### 1. `user`\n\n用户偏好。\n\n例如：\n\n- 喜欢什么代码风格\n- 回答希望简洁还是详细\n- 更偏好什么工具链\n\n### 2. `feedback`\n\n用户明确纠正过你的地方。\n\n例如：\n\n- “不要这样改”\n- “这个判断方式之前错过”\n- “以后遇到这种情况要先做 X”\n\n### 3. `project`\n\n这里只保存**不容易从代码直接重新看出来**的项目约定或背景。\n\n例如：\n\n- 某个设计决定是因为合规而不是技术偏好\n- 某个目录虽然看起来旧，但短期内不能动\n- 某条规则是团队故意定下来的，不是历史残留\n\n### 4. `reference`\n\n外部资源指针。\n\n例如：\n\n- 某个问题单在哪个看板里\n- 某个监控面板在哪里\n- 某个资料库在哪个 URL\n\n## 哪些东西不要存进 memory\n\n这是比“该存什么”更重要的一张表：\n\n| 不要存的东西 | 为什么 |\n|---|---|\n| 文件结构、函数签名、目录布局 | 这些可以重新读代码得到 |\n| 当前任务进度 | 这属于 task / plan，不属于 memory |\n| 临时分支名、当前 PR 号 | 很快会过时 |\n| 修 bug 的具体代码细节 | 代码和提交记录才是准确信息 |\n| 密钥、密码、凭证 | 安全风险 |\n\n这条边界一定要稳。\n\n否则 memory 会从“帮助系统长期变聪明”变成“帮助系统长期产生幻觉”。\n\n## 最小心智模型\n\n```text\nconversation\n   |\n   | 用户提到一个长期重要信息\n   v\nsave_memory\n   |\n   v\n.memory/\n  ├── MEMORY.md        # 索引\n  ├── prefer_tabs.md\n  ├── feedback_tests.md\n  └── incident_board.md\n   |\n   v\n下次新会话开始时重新加载\n```\n\n## 这一章最关键的数据结构\n\n### 1. 单条 memory 文件\n\n最简单也最清晰的做法，是每条 memory 一个文件。\n\n```md\n---\nname: prefer_tabs\ndescription: User prefers tabs for indentation\ntype: user\n---\nThe user explicitly prefers tabs over spaces when editing source files.\n```\n\n这里的 `frontmatter` 可以理解成：\n\n**放在正文前面的结构化元数据。**\n\n它让系统先知道：\n\n- 这条 memory 叫什么\n- 大致是什么\n- 属于哪一类\n\n### 2. 索引文件 `MEMORY.md`\n\n最小实现里，再加一个索引文件就够了：\n\n```md\n# Memory Index\n\n- prefer_tabs: User prefers tabs for indentation [user]\n- avoid_mock_heavy_tests: User dislikes mock-heavy tests [feedback]\n```\n\n索引的作用不是重复保存全部内容。  \n它只是帮系统快速知道“有哪些 memory 可用”。\n\n## 最小实现步骤\n\n### 第一步：定义 memory 类型\n\n```python\nMEMORY_TYPES = (\"user\", \"feedback\", \"project\", \"reference\")\n```\n\n### 第二步：写一个 `save_memory` 工具\n\n最小参数就四个：\n\n- `name`\n- `description`\n- `type`\n- `content`\n\n### 第三步：每条 memory 独立落盘\n\n```python\ndef save_memory(name, description, mem_type, content):\n    path = memory_dir / f\"{safe_name}.md\"\n    path.write_text(frontmatter + content)\n    rebuild_index()\n```\n\n### 第四步：会话开始时重新加载\n\n把 memory 文件重新读出来，拼成一段 memory section。\n\n### 第五步：把 memory section 接进系统输入\n\n这一步会在 `s10` 的 prompt 组装里系统化。\n\n## memory、task、plan、CLAUDE.md 的边界\n\n这是最值得初学者反复区分的一组概念。\n\n### memory\n\n保存跨会话仍有价值的信息。\n\n### task\n\n保存当前工作要做什么、依赖关系如何、进度如何。\n\n### plan\n\n保存“这一轮我要怎么做”的过程性安排。\n\n### CLAUDE.md\n\n保存更稳定、更像长期规则的说明文本。\n\n一个简单判断法：\n\n- 只对这次任务有用：`task / plan`\n- 以后很多会话可能都还会有用：`memory`\n- 属于长期系统级或项目级固定说明：`CLAUDE.md`\n\n## 初学者最容易犯的错\n\n### 错误 1：把代码结构也存进 memory\n\n例如：\n\n- “这个项目有 `src/` 和 `tests/`”\n- “这个函数在 `app.py`”\n\n这些都不该存。\n\n因为系统完全可以重新去读。\n\n### 错误 2：把当前任务状态存进 memory\n\n例如：\n\n- “我现在正在改认证模块”\n- “这个 PR 还有两项没做”\n\n这些是 task / plan，不是 memory。\n\n### 错误 3：把 memory 当成绝对真相\n\nmemory 可能过时。\n\n所以更稳妥的规则是：\n\n**memory 用来提供方向，不用来替代当前观察。**\n\n如果 memory 和当前代码状态冲突，优先相信你现在看到的真实状态。\n\n## 从教学版到高完成度版：记忆系统还要补的 6 条边界\n\n最小教学版只要先把“该存什么 / 不该存什么”讲清楚。  \n但如果你要把系统做到更稳、更像真实工作平台，下面这 6 条边界也必须讲清。\n\n### 1. 不是所有 memory 都该放在同一个作用域\n\n更完整系统里，至少要分清：\n\n- `private`：只属于当前用户或当前 agent 的记忆\n- `team`：整个项目团队都该共享的记忆\n\n一个很稳的教学判断法是：\n\n- `user` 类型，几乎总是 `private`\n- `feedback` 类型，默认 `private`；只有它明确是团队规则时才升到 `team`\n- `project` 和 `reference`，通常更偏向 `team`\n\n这样做的价值是：\n\n- 不把个人偏好误写成团队规范\n- 不把团队规范只锁在某一个人的私有记忆里\n\n### 2. 不只保存“你做错了”，也要保存“这样做是对的”\n\n很多人讲 memory 时，只会想到纠错。\n\n这不够。\n\n因为真正能长期使用的系统，还需要记住：\n\n- 哪种不明显的做法，用户已经明确认可\n- 哪个判断方式，项目里已经被验证有效\n\n也就是说，`feedback` 不只来自负反馈，也来自被验证的正反馈。\n\n如果只存纠错，不存被确认有效的做法，系统会越来越保守，却不一定越来越聪明。\n\n### 3. 有些东西即使用户要求你存，也不该直接存\n\n这条边界一定要说死。\n\n就算用户说“帮我记住”，下面这些东西也不应该直接写进 memory：\n\n- 本周 PR 列表\n- 当前分支名\n- 今天改了哪些文件\n- 某个函数现在在什么路径\n- 当前正在做哪两个子任务\n\n这些内容的问题不是“没有价值”，而是：\n\n- 太容易过时\n- 更适合存在代码、任务板、git 记录里\n- 会把 memory 变成活动日志\n\n更好的做法是追问一句：\n\n> 这里面真正值得长期留下的、非显然的信息到底是什么？\n\n### 4. memory 会漂移，所以回答前要先核对当前状态\n\nmemory 记录的是“曾经成立过的事实”，不是永久真理。\n\n所以更稳的工作方式是：\n\n1. 先把 memory 当作方向提示\n2. 再去读当前文件、当前资源、当前配置\n3. 如果冲突，优先相信你刚观察到的真实状态\n\n这点对初学者尤其重要。  \n因为他们最容易把 memory 当成“已经查证过的答案”。\n\n### 5. 用户说“忽略 memory”时，就当它是空的\n\n这是一个很容易漏讲的行为边界。\n\n如果用户明确说：\n\n- “这次不要参考 memory”\n- “忽略之前的记忆”\n\n那系统更合理的处理不是：\n\n- 一边继续用 memory\n- 一边嘴上说“我知道但先忽略”\n\n而是：\n\n**在这一轮里，按 memory 为空来工作。**\n\n### 6. 推荐具体路径、函数、外部资源前，要再验证一次\n\nmemory 很适合保存：\n\n- 哪个看板通常有上下文\n- 哪个目录以前是关键入口\n- 某种项目约定为什么存在\n\n但在你真的要对用户说：\n\n- “去改 `src/auth.py`”\n- “调用 `AuthManager`”\n- “看这个 URL 就对了”\n\n之前，最好再核对一次。\n\n因为命名、路径、系统入口、外部链接，都是会变的。\n\n所以更稳妥的做法不是：\n\n> memory 里写过，就直接复述。\n\n而是：\n\n> memory 先告诉我去哪里验证；验证完，再给用户结论。\n\n## 教学边界\n\n这章最重要的，不是 memory 以后还能多自动、多复杂，而是先把存储边界讲清楚：\n\n- 什么值得跨会话留下\n- 什么只是当前任务状态，不该进 memory\n- memory 和 task / plan / CLAUDE.md 各自负责什么\n\n只要这几层边界清楚，教学目标就已经达成了。\n\n更复杂的自动整合、作用域分层、自动抽取，都应该放在这个最小边界之后。\n\n## 学完这章后，你应该能回答\n\n- 为什么 memory 不是“什么都记”？\n- 什么样的信息适合跨会话保存？\n- 为什么代码结构和当前任务状态不应该进 memory？\n- memory 和 task / plan / CLAUDE.md 的边界是什么？\n\n---\n\n**一句话记住：memory 保存的是“以后还可能有价值、但当前代码里不容易直接重新看出来”的信息。**\n"
  },
  {
    "version": "s10",
    "slug": "s10-system-prompt",
    "locale": "zh",
    "title": "s10: System Prompt Construction (系统提示词构建)",
    "kind": "chapter",
    "filename": "s10-system-prompt.md",
    "content": "# s10: System Prompt Construction (系统提示词构建)\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > [ s10 ] > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *系统提示词不是一整块大字符串，而是一条可维护的组装流水线。*\n\n## 这一章为什么重要\n\n很多初学者一开始会把 system prompt 写成一大段固定文本。\n\n这样在最小 demo 里当然能跑。\n\n但一旦系统开始长功能，你很快会遇到这些问题：\n\n- 工具列表会变\n- skills 会变\n- memory 会变\n- 当前目录、日期、模式会变\n- 某些提醒只在这一轮有效，不该永远塞进系统说明\n\n所以到了这个阶段，system prompt 不能再当成一块硬编码文本。\n\n它应该升级成：\n\n**由多个来源共同组装出来的一条流水线。**\n\n## 建议联读\n\n- 如果你还习惯把 prompt 看成“神秘大段文本”，先回 [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)，重新确认模型输入在进模型前经历了哪些控制层。\n- 如果你想真正稳住“哪些内容先拼、哪些后拼”，建议把 [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md) 放在手边，这页就是本章最关键的桥。\n- 如果你开始把 system rules、工具说明、memory、runtime state 混成一个大块，先看 [`data-structures.md`](./data-structures.md)，把这些输入片段的来源重新拆开。\n\n## 先解释几个名词\n\n### 什么是 system prompt\n\nsystem prompt 是给模型的系统级说明。\n\n它通常负责告诉模型：\n\n- 你是谁\n- 你能做什么\n- 你应该遵守什么规则\n- 你现在处在什么环境里\n\n### 什么是“组装流水线”\n\n意思是：\n\n- 不同信息来自不同地方\n- 最后按顺序拼接成一份输入\n\n它不是一个死字符串，而是一条构建过程。\n\n### 什么是动态信息\n\n有些信息经常变化，例如：\n\n- 当前日期\n- 当前工作目录\n- 本轮新增的提醒\n\n这些信息不适合和所有稳定说明混在一起。\n\n## 最小心智模型\n\n最容易理解的方式，是把 system prompt 想成 6 段：\n\n```text\n1. 核心身份和行为说明\n2. 工具列表\n3. skills 元信息\n4. memory 内容\n5. CLAUDE.md 指令链\n6. 动态环境信息\n```\n\n然后按顺序拼起来：\n\n```text\ncore\n+ tools\n+ skills\n+ memory\n+ claude_md\n+ dynamic_context\n= final system prompt\n```\n\n## 为什么不能把所有东西都硬塞进一个大字符串\n\n因为这样会有三个问题：\n\n### 1. 不好维护\n\n你很难知道：\n\n- 哪一段来自哪里\n- 该修改哪一部分\n- 哪一段是固定说明，哪一段是临时上下文\n\n### 2. 不好测试\n\n如果 system prompt 是一大坨文本，你很难分别测试：\n\n- 工具说明生成得对不对\n- memory 是否被正确拼进去\n- CLAUDE.md 是否被正确读取\n\n### 3. 不好做缓存和动态更新\n\n一些稳定内容其实不需要每轮大变。  \n一些临时内容又只该活一轮。\n\n这就要求你把“稳定块”和“动态块”分开思考。\n\n## 最小实现结构\n\n### 第一步：做一个 builder\n\n```python\nclass SystemPromptBuilder:\n    def build(self) -> str:\n        parts = []\n        parts.append(self._build_core())\n        parts.append(self._build_tools())\n        parts.append(self._build_skills())\n        parts.append(self._build_memory())\n        parts.append(self._build_claude_md())\n        parts.append(self._build_dynamic())\n        return \"\\n\\n\".join(p for p in parts if p)\n```\n\n这就是这一章最核心的设计。\n\n### 第二步：每一段只负责一种来源\n\n例如：\n\n- `_build_tools()` 只负责把工具说明生成出来\n- `_build_memory()` 只负责拿 memory\n- `_build_claude_md()` 只负责读指令文件\n\n这样每一段的职责就很清楚。\n\n## 这一章最关键的结构化边界\n\n### 边界 1：稳定说明 vs 动态提醒\n\n最重要的一组边界是：\n\n- 稳定的系统说明\n- 每轮临时变化的提醒\n\n这两类东西不应该混为一谈。\n\n### 边界 2：system prompt vs system reminder\n\nsystem prompt 适合放：\n\n- 身份\n- 规则\n- 工具\n- 长期约束\n\nsystem reminder 适合放：\n\n- 这一轮才临时需要的补充上下文\n- 当前变动的状态\n\n所以更清晰的做法是：\n\n- 主 system prompt 保持相对稳定\n- 每轮额外变化的内容，用单独的 reminder 方式追加\n\n## 一个实用的教学版本\n\n教学版可以先这样分：\n\n```text\n静态部分：\n- core\n- tools\n- skills\n- memory\n- CLAUDE.md\n\n动态部分：\n- date\n- cwd\n- model\n- current mode\n```\n\n如果你还想再清楚一点，可以加一个边界标记：\n\n```text\n=== DYNAMIC_BOUNDARY ===\n```\n\n它的作用不是神秘魔法。\n\n它只是提醒你：\n\n**上面更稳定，下面更容易变。**\n\n## CLAUDE.md 为什么要单独一段\n\n因为它的角色不是“某一次任务的临时上下文”，而是更稳定的长期说明。\n\n教学仓里，最容易理解的链条是：\n\n1. 用户全局级\n2. 项目根目录级\n3. 当前子目录级\n\n然后全部拼进去，而不是互相覆盖。\n\n这样读者更容易理解“规则来源可以分层叠加”这个思想。\n\n## memory 为什么要和 system prompt 有关系\n\n因为 memory 的本质是：\n\n**把跨会话仍然有价值的信息，重新带回模型当前的工作环境。**\n\n如果保存了 memory，却从来不在系统输入中重新呈现，那它就等于没被真正用起来。\n\n所以 memory 最终一定要进入 prompt 组装链条。\n\n## 初学者最容易混淆的点\n\n### 1. 把 system prompt 讲成一个固定字符串\n\n这会让读者看不到系统是如何长大的。\n\n### 2. 把所有变化信息都塞进 system prompt\n\n这会把稳定说明和临时提醒搅在一起。\n\n### 3. 把 CLAUDE.md、memory、skills 写成同一种东西\n\n它们都可能进入 prompt，但来源和职责不同：\n\n- `skills`：可选能力或知识包\n- `memory`：跨会话记住的信息\n- `CLAUDE.md`：长期规则说明\n\n## 教学边界\n\n这一章先只建立一个核心心智：\n\n**prompt 不是一整块静态文本，而是一条被逐段组装出来的输入流水线。**\n\n所以这里先不要扩到太多外层细节：\n\n- 不要先讲复杂的 section 注册系统\n- 不要先讲缓存与预算\n- 不要先讲所有外部能力如何追加 prompt 说明\n\n只要读者已经能把稳定规则、动态提醒、memory、skills 这些来源看成不同输入段，而不是同一种“大 prompt”，这一章就已经讲到位了。\n\n## 如果你开始分不清 prompt、message、reminder\n\n这是非常正常的。\n\n因为到了这一章，系统输入已经不再只有一个 system prompt 了。  \n它至少会同时出现：\n\n- system prompt blocks\n- 普通对话消息\n- tool_result 消息\n- memory attachment\n- 当前轮 reminder\n\n如果你开始有这类困惑：\n\n- “这个信息到底该放 prompt 里，还是放 message 里？”\n- “为什么 system prompt 不是全部输入？”\n- “reminder 和长期规则到底差在哪？”\n\n建议继续看：\n\n- [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md)\n- [`entity-map.md`](./entity-map.md)\n\n## 这章和后续章节的关系\n\n这一章像一个汇合点：\n\n- `s05` skills 会汇进来\n- `s09` memory 会汇进来\n- `s07` 的当前模式也可能汇进来\n- `s19` MCP 以后也可能给 prompt 增加说明\n\n所以 `s10` 的价值不是“新加一个功能”，  \n而是“把前面长出来的功能组织成一份清楚的系统输入”。\n\n## 学完这章后，你应该能回答\n\n- 为什么 system prompt 不能只是一整块硬编码文本？\n- 为什么要把不同来源拆成独立 section？\n- system prompt 和 system reminder 的边界是什么？\n- memory、skills、CLAUDE.md 为什么都可能进入 prompt，但又不是一回事？\n\n---\n\n**一句话记住：system prompt 的关键不是“写一段很长的话”，而是“把不同来源的信息按清晰边界组装起来”。**\n"
  },
  {
    "version": null,
    "slug": "s10a-message-prompt-pipeline",
    "locale": "zh",
    "title": "s10a: Message & Prompt Pipeline (消息与提示词管道)",
    "kind": "bridge",
    "filename": "s10a-message-prompt-pipeline.md",
    "content": "# s10a: Message & Prompt Pipeline (消息与提示词管道)\n\n> 这篇桥接文档是 `s10` 的扩展。  \n> 它要补清一个很关键的心智：\n>\n> **system prompt 很重要，但它不是模型完整输入的全部。**\n\n## 为什么要补这一篇\n\n`s10` 已经把 system prompt 从“大字符串”升级成“可维护的组装流水线”，这一步非常重要。\n\n但当系统开始长出更多输入来源时，还会继续往前走一步：\n\n它会发现，真正送给模型的输入，不只包含：\n\n- system prompt\n\n还包含：\n\n- 规范化后的 messages\n- memory attachments\n- hook 注入消息\n- system reminder\n- 当前轮次的动态上下文\n\n也就是说，真正的输入更像一条完整管道：\n\n**Prompt Pipeline，而不只是 Prompt Builder。**\n\n## 先解释几个名词\n\n### 什么是 prompt block\n\n你可以把 `prompt block` 理解成：\n\n> system prompt 内部的一段结构化片段。\n\n例如：\n\n- 核心身份说明\n- 工具说明\n- memory section\n- CLAUDE.md section\n\n### 什么是 normalized message\n\n`normalized message` 的意思是：\n\n> 把不同来源、不同格式的消息整理成统一、稳定、可发给模型的消息形式。\n\n为什么需要这一步？\n\n因为系统里可能出现：\n\n- 普通用户消息\n- assistant 回复\n- tool_result\n- 系统提醒\n- attachment 包裹消息\n\n如果不先整理，模型输入层会越来越乱。\n\n### 什么是 system reminder\n\n这在 `s10` 已经提到过。\n\n它不是长期规则，而是：\n\n> 只在当前轮或当前阶段临时追加的一小段系统信息。\n\n## 最小心智模型\n\n把完整输入先理解成下面这条流水线：\n\n```text\n多种输入来源\n  |\n  +-- system prompt blocks\n  +-- messages\n  +-- attachments\n  +-- reminders\n  |\n  v\nnormalize\n  |\n  v\nfinal api payload\n```\n\n这条图里最重要的不是“normalize”这个词有多高级，而是：\n\n**所有来源先分清边界，再在最后一步统一整理。**\n\n## system prompt 为什么不是全部\n\n这是初学者非常容易混的一个点。\n\nsystem prompt 适合放：\n\n- 身份\n- 规则\n- 工具能力描述\n- 长期说明\n\n但有些东西不适合放进去：\n\n- 这一轮刚发生的 tool_result\n- 某个 hook 刚注入的补充说明\n- 某条 memory attachment\n- 当前临时提醒\n\n这些更适合存在消息流里，而不是塞进 prompt block。\n\n## 关键数据结构\n\n### 1. SystemPromptBlock\n\n```python\nblock = {\n    \"text\": \"...\",\n    \"cache_scope\": None,\n}\n```\n\n最小教学版可以只理解成：\n\n- 一段文本\n- 可选的缓存信息\n\n### 2. PromptParts\n\n```python\nparts = {\n    \"core\": \"...\",\n    \"tools\": \"...\",\n    \"skills\": \"...\",\n    \"memory\": \"...\",\n    \"claude_md\": \"...\",\n    \"dynamic\": \"...\",\n}\n```\n\n### 3. NormalizedMessage\n\n```python\nmessage = {\n    \"role\": \"user\" | \"assistant\",\n    \"content\": [...],\n}\n```\n\n这里的 `content` 建议直接理解成“块列表”，而不是只是一段字符串。  \n因为后面你会自然遇到：\n\n- text block\n- tool_use block\n- tool_result block\n- attachment-like block\n\n### 4. ReminderMessage\n\n```python\nreminder = {\n    \"role\": \"system\",\n    \"content\": \"Current mode: plan\",\n}\n```\n\n教学版里你不一定真的要用 `system` role 单独传，但心智上要区分：\n\n- 这是长期 prompt block\n- 还是当前轮临时 reminder\n\n## 最小实现\n\n### 第一步：继续保留 `SystemPromptBuilder`\n\n这一步不能丢。\n\n### 第二步：把消息输入做成独立管道\n\n```python\ndef build_messages(raw_messages, attachments, reminders):\n    messages = normalize_messages(raw_messages)\n    messages = attach_memory(messages, attachments)\n    messages = append_reminders(messages, reminders)\n    return messages\n```\n\n### 第三步：在最后一层统一生成 API payload\n\n```python\npayload = {\n    \"system\": build_system_prompt(),\n    \"messages\": build_messages(...),\n    \"tools\": build_tools(...),\n}\n```\n\n这一步特别关键。\n\n它会让读者明白：\n\n**system prompt、messages、tools 是并列输入面，而不是互相替代。**\n\n## 一张更完整但仍然容易理解的图\n\n```text\nPrompt Blocks\n  - core\n  - tools\n  - memory\n  - CLAUDE.md\n  - dynamic context\n\nMessages\n  - user messages\n  - assistant messages\n  - tool_result messages\n  - injected reminders\n\nAttachments\n  - memory attachment\n  - hook attachment\n\n          |\n          v\n   normalize + assemble\n          |\n          v\n     final API payload\n```\n\n## 什么时候该放在 prompt，什么时候该放在 message\n\n可以先记这个简单判断法：\n\n### 更适合放在 prompt block\n\n- 长期稳定规则\n- 工具列表\n- 长期身份说明\n- CLAUDE.md\n\n### 更适合放在 message 流\n\n- 当前轮 tool_result\n- 刚发生的提醒\n- 当前轮追加的上下文\n- 某次 hook 输出\n\n### 更适合做 attachment\n\n- 大块但可选的补充信息\n- 需要按需展开的说明\n\n## 初学者最容易犯的错\n\n### 1. 把所有东西都塞进 system prompt\n\n这样会让 prompt 越来越脏，也会模糊稳定信息和动态信息的边界。\n\n### 2. 完全不做 normalize\n\n随着消息来源增多，输入格式会越来越不稳定。\n\n### 3. 把 memory、hook、tool_result 都当成一类东西\n\n它们都能影响模型，但进入输入层的方式并不相同。\n\n### 4. 忽略“临时 reminder”这一层\n\n这会让很多本该只活一轮的信息，被错误地塞进长期 system prompt。\n\n## 它和 `s10`、`s19` 的关系\n\n- `s10` 讲 prompt builder\n- 这篇讲 message + prompt 的完整输入管道\n- `s19` 则会把 MCP 带来的额外说明和外部能力继续接入这条管道\n\n也就是说：\n\n**builder 是 prompt 的内部结构，pipeline 是模型输入的整体结构。**\n\n## 教学边界\n\n这篇最重要的，不是罗列所有输入来源，而是先把三条管线边界讲稳：\n\n- 什么该进 system blocks\n- 什么该进 normalized messages\n- 什么只应该作为临时 reminder 或 attachment\n\n只要这三层边界清楚，读者就已经能自己搭出一条可靠输入管道。  \n更细的 cache scope、attachment 去重和大结果外置，都可以放到后续扩展里再补。\n\n## 一句话记住\n\n**真正送给模型的，不只是一个 prompt，而是“prompt blocks + normalized messages + attachments + reminders”组成的输入管道。**\n"
  },
  {
    "version": "s11",
    "slug": "s11-error-recovery",
    "locale": "zh",
    "title": "s11: Error Recovery (错误恢复)",
    "kind": "chapter",
    "filename": "s11-error-recovery.md",
    "content": "# s11: Error Recovery (错误恢复)\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > [ s11 ] > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *错误不是例外，而是主循环必须预留出来的一条正常分支。*\n\n## 这一章要解决什么问题\n\n到了 `s10`，你的 agent 已经有了：\n\n- 主循环\n- 工具调用\n- 规划\n- 上下文压缩\n- 权限、hook、memory、system prompt\n\n这时候系统已经不再是一个“只会聊天”的 demo，而是一个真的在做事的程序。\n\n问题也随之出现：\n\n- 模型输出写到一半被截断\n- 上下文太长，请求直接失败\n- 网络暂时抖动，API 超时或限流\n\n如果没有恢复机制，主循环会在第一个错误上直接停住。  \n这对初学者很危险，因为他们会误以为“agent 不稳定是模型的问题”。\n\n实际上，很多失败并不是“任务真的失败了”，而只是：\n\n**这一轮需要换一种继续方式。**\n\n所以这一章的目标只有一个：\n\n**把“报错就崩”升级成“先判断错误类型，再选择恢复路径”。**\n\n## 建议联读\n\n- 如果你开始分不清“为什么这一轮还在继续”，先回 [`s00c-query-transition-model.md`](./s00c-query-transition-model.md)，重新确认 transition reason 为什么是独立状态。\n- 如果你在恢复逻辑里又把上下文压缩和错误恢复混成一团，建议顺手回看 [`s06-context-compact.md`](./s06-context-compact.md)，区分“为了缩上下文而压缩”和“因为失败而恢复”。\n- 如果你准备继续往 `s12` 走，建议把 [`data-structures.md`](./data-structures.md) 放在旁边，因为后面任务系统会在“恢复状态之外”再引入新的 durable work 状态。\n\n## 先解释几个名词\n\n### 什么叫恢复\n\n恢复，不是把所有错误都藏起来。\n\n恢复的意思是：\n\n- 先判断这是不是临时问题\n- 如果是，就尝试一个有限次数的补救动作\n- 如果补救失败，再把失败明确告诉用户\n\n### 什么叫重试预算\n\n重试预算，就是“最多试几次”。\n\n比如：\n\n- 续写最多 3 次\n- 网络重连最多 3 次\n\n如果没有这个预算，程序就可能无限循环。\n\n### 什么叫状态机\n\n状态机这个词听起来很大，其实意思很简单：\n\n> 一个东西会在几个明确状态之间按规则切换。\n\n在这一章里，主循环就从“普通执行”变成了：\n\n- 正常执行\n- 续写恢复\n- 压缩恢复\n- 退避重试\n- 最终失败\n\n## 最小心智模型\n\n不要把错误恢复想得太神秘。\n\n教学版只需要先区分 3 类问题：\n\n```text\n1. 输出被截断\n   模型还没说完，但 token 用完了\n\n2. 上下文太长\n   请求装不进模型窗口了\n\n3. 临时连接失败\n   网络、超时、限流、服务抖动\n```\n\n对应 3 条恢复路径：\n\n```text\nLLM call\n  |\n  +-- stop_reason == \"max_tokens\"\n  |      -> 注入续写提示\n  |      -> 再试一次\n  |\n  +-- prompt too long\n  |      -> 压缩旧上下文\n  |      -> 再试一次\n  |\n  +-- timeout / rate limit / transient API error\n         -> 等一会儿\n         -> 再试一次\n```\n\n这就是最小但正确的恢复模型。\n\n## 关键数据结构\n\n### 1. 恢复状态\n\n```python\nrecovery_state = {\n    \"continuation_attempts\": 0,\n    \"compact_attempts\": 0,\n    \"transport_attempts\": 0,\n}\n```\n\n它的作用不是“记录一切”，而是：\n\n- 防止无限重试\n- 让每种恢复路径各算各的次数\n\n### 2. 恢复决策\n\n```python\n{\n    \"kind\": \"continue\" | \"compact\" | \"backoff\" | \"fail\",\n    \"reason\": \"why this branch was chosen\",\n}\n```\n\n把“错误长什么样”和“接下来怎么做”分开，会更清楚。\n\n### 3. 续写提示\n\n```python\nCONTINUE_MESSAGE = (\n    \"Output limit hit. Continue directly from where you stopped. \"\n    \"Do not restart or repeat.\"\n)\n```\n\n这条提示非常重要。\n\n因为如果你只说“继续”，模型经常会：\n\n- 重新总结\n- 重新开头\n- 重复已经输出过的内容\n\n## 最小实现\n\n先写一个恢复选择器：\n\n```python\ndef choose_recovery(stop_reason: str | None, error_text: str | None) -> dict:\n    if stop_reason == \"max_tokens\":\n        return {\"kind\": \"continue\", \"reason\": \"output truncated\"}\n\n    if error_text and \"prompt\" in error_text and \"long\" in error_text:\n        return {\"kind\": \"compact\", \"reason\": \"context too large\"}\n\n    if error_text and any(word in error_text for word in [\n        \"timeout\", \"rate\", \"unavailable\", \"connection\"\n    ]):\n        return {\"kind\": \"backoff\", \"reason\": \"transient transport failure\"}\n\n    return {\"kind\": \"fail\", \"reason\": \"unknown or non-recoverable error\"}\n```\n\n再把它接进主循环：\n\n```python\nwhile True:\n    try:\n        response = client.messages.create(...)\n        decision = choose_recovery(response.stop_reason, None)\n    except Exception as e:\n        response = None\n        decision = choose_recovery(None, str(e).lower())\n\n    if decision[\"kind\"] == \"continue\":\n        messages.append({\"role\": \"user\", \"content\": CONTINUE_MESSAGE})\n        continue\n\n    if decision[\"kind\"] == \"compact\":\n        messages = auto_compact(messages)\n        continue\n\n    if decision[\"kind\"] == \"backoff\":\n        time.sleep(backoff_delay(...))\n        continue\n\n    if decision[\"kind\"] == \"fail\":\n        break\n\n    # 正常工具处理\n```\n\n注意这里的重点不是代码花哨，而是：\n\n- 先分类\n- 再选动作\n- 每条动作有自己的预算\n\n## 三条恢复路径分别在补什么洞\n\n### 路径 1：输出被截断时，做续写\n\n这个问题的本质不是“模型不会”，而是“这一轮输出空间不够”。\n\n所以最小补法是：\n\n1. 追加一条续写消息\n2. 告诉模型不要重来，不要重复\n3. 让主循环继续\n\n```python\nif response.stop_reason == \"max_tokens\":\n    if state[\"continuation_attempts\"] >= 3:\n        return \"Error: output recovery exhausted\"\n    state[\"continuation_attempts\"] += 1\n    messages.append({\"role\": \"user\", \"content\": CONTINUE_MESSAGE})\n    continue\n```\n\n### 路径 2：上下文太长时，先压缩再重试\n\n这里要先明确一点：\n\n压缩不是“把历史删掉”，而是：\n\n**把旧对话从原文，变成一份仍然可继续工作的摘要。**\n\n最小压缩结果建议至少保留：\n\n- 当前任务是什么\n- 已经做了什么\n- 关键决定是什么\n- 下一步准备做什么\n\n```python\ndef auto_compact(messages: list) -> list:\n    summary = summarize_messages(messages)\n    return [{\n        \"role\": \"user\",\n        \"content\": \"This session was compacted. Continue from this summary:\\n\" + summary,\n    }]\n```\n\n### 路径 3：连接抖动时，退避重试\n\n“退避”这个词的意思是：\n\n> 别立刻再打一次，而是等一小会儿再试。\n\n为什么要等？\n\n因为这类错误往往是临时拥堵：\n\n- 刚超时\n- 刚限流\n- 服务器刚好抖了一下\n\n如果你瞬间连续重打，只会更容易失败。\n\n```python\ndef backoff_delay(attempt: int) -> float:\n    return min(1.0 * (2 ** attempt), 30.0) + random.uniform(0, 1)\n```\n\n## 如何接到主循环里\n\n最干净的接法，是把恢复逻辑放在两个位置：\n\n### 位置 1：模型调用外层\n\n负责处理：\n\n- API 报错\n- 网络错误\n- 超时\n\n### 位置 2：拿到 response 以后\n\n负责处理：\n\n- `stop_reason == \"max_tokens\"`\n- 正常的 `tool_use`\n- 正常的结束\n\n也就是说，主循环现在不只是“调模型 -> 执行工具”，而是：\n\n```text\n1. 调模型\n2. 如果调用报错，判断是否可以恢复\n3. 如果拿到响应，判断是否被截断\n4. 如果需要恢复，就修改 messages 或等待\n5. 如果不需要恢复，再进入正常工具分支\n```\n\n## 初学者最容易犯的错\n\n### 1. 把所有错误都当成一种错误\n\n这样会导致：\n\n- 该续写的去压缩\n- 该等待的去重试\n- 该失败的却无限拖延\n\n### 2. 没有重试预算\n\n没有预算，主循环就可能永远卡在“继续”“继续”“继续”。\n\n### 3. 续写提示写得太模糊\n\n只写一个“continue”通常不够。  \n你要明确告诉模型：\n\n- 不要重复\n- 不要重新总结\n- 直接从中断点接着写\n\n### 4. 压缩后没有告诉模型“这是续场”\n\n如果压缩后只给一份摘要，不告诉模型“这是前文摘要”，模型很可能重新向用户提问。\n\n### 5. 恢复过程完全没有日志\n\n教学系统最好打印类似：\n\n- `[Recovery] continue`\n- `[Recovery] compact`\n- `[Recovery] backoff`\n\n这样读者才看得见主循环到底做了什么。\n\n## 这一章和前后章节怎么衔接\n\n- `s06` 讲的是“什么时候该压缩”\n- `s10` 讲的是“系统提示词怎么组装”\n- `s11` 讲的是“当执行失败时，主循环怎么续下去”\n- `s12` 开始，恢复机制会保护更长、更复杂的任务流\n\n所以 `s11` 的位置非常关键。\n\n它不是外围小功能，而是：\n\n**把 agent 从“能跑”推进到“遇到问题也能继续跑”。**\n\n## 教学边界\n\n这一章先把 3 条最小恢复路径讲稳就够了：\n\n- 输出截断后续写\n- 上下文过长后压缩再试\n- 请求抖动后退避重试\n\n对教学主线来说，重点不是把所有“为什么继续下一轮”的原因一次讲全，而是先让读者明白：\n\n**恢复不是简单 try/except，而是系统知道该怎么续下去。**\n\n更大的 query 续行模型、预算续行、hook 介入这些内容，应该放回控制平面的桥接文档里看，而不是抢掉这章主线。\n\n## 试一试\n\n```sh\ncd learn-claude-code\npython agents/s11_error_recovery.py\n```\n\n可以试试这些任务：\n\n1. 让模型生成一段特别长的内容，观察它是否会自动续写。\n2. 连续读取一些大文件，观察上下文压缩是否会介入。\n3. 临时制造一次请求失败，观察系统是否会退避重试。\n\n读这一章时，你真正要记住的不是某个具体异常名，而是这条主线：\n\n**错误先分类，恢复再执行，失败最后才暴露给用户。**\n"
  },
  {
    "version": "s12",
    "slug": "s12-task-system",
    "locale": "zh",
    "title": "s12: Task System (任务系统)",
    "kind": "chapter",
    "filename": "s12-task-system.md",
    "content": "# s12: Task System (任务系统)\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > [ s12 ] > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *Todo 只能提醒你“有事要做”，任务系统才能告诉你“先做什么、谁在等谁、哪一步还卡着”。*\n\n## 这一章要解决什么问题\n\n`s03` 的 todo 已经能帮 agent 把大目标拆成几步。\n\n但 todo 仍然有两个明显限制：\n\n- 它更像当前会话里的临时清单\n- 它不擅长表达“谁先谁后、谁依赖谁”\n\n例如下面这组工作：\n\n```text\n1. 先写解析器\n2. 再写语义检查\n3. 测试和文档可以并行\n4. 最后整体验收\n```\n\n这已经不是单纯的列表，而是一张“依赖关系图”。\n\n如果没有专门的任务系统，agent 很容易出现这些问题：\n\n- 前置工作没做完，就贸然开始后面的任务\n- 某个任务完成以后，不知道解锁了谁\n- 多个 agent 协作时，没有统一任务板可读\n\n所以这一章要做的升级是：\n\n**把“会话里的 todo”升级成“可持久化的任务图”。**\n\n## 建议联读\n\n- 如果你刚从 `s03` 过来，先回 [`data-structures.md`](./data-structures.md)，重新确认 `TodoItem / PlanState` 和 `TaskRecord` 不是同一层状态。\n- 如果你开始把“对象边界”读混，先回 [`entity-map.md`](./entity-map.md)，把 message、task、runtime task、teammate 这几层拆开。\n- 如果你准备继续读 `s13`，建议把 [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) 先放在手边，因为从这里开始最容易把 durable task 和 runtime task 混成一个词。\n\n## 先把几个词讲明白\n\n### 什么是任务\n\n这里的 `task` 指的是：\n\n> 一个可以被跟踪、被分配、被完成、被阻塞的小工作单元。\n\n它不是整段用户需求，而是用户需求拆出来的一小块工作。\n\n### 什么是依赖\n\n依赖的意思是：\n\n> 任务 B 必须等任务 A 完成，才能开始。\n\n### 什么是任务图\n\n任务图就是：\n\n> 任务节点 + 依赖连线\n\n你可以把它理解成：\n\n- 点：每个任务\n- 线：谁依赖谁\n\n### 什么是 ready\n\n`ready` 的意思很简单：\n\n> 这条任务现在已经满足开工条件。\n\n也就是：\n\n- 自己还没开始\n- 前置依赖已经全部完成\n\n## 最小心智模型\n\n本章最重要的，不是复杂调度算法，而是先回答 4 个问题：\n\n1. 现在有哪些任务？\n2. 每个任务是什么状态？\n3. 哪些任务还被卡住？\n4. 哪些任务已经可以开始？\n\n只要这 4 个问题能稳定回答，一个最小任务系统就已经成立了。\n\n## 关键数据结构\n\n### 1. TaskRecord\n\n```python\ntask = {\n    \"id\": 1,\n    \"subject\": \"Write parser\",\n    \"description\": \"\",\n    \"status\": \"pending\",\n    \"blockedBy\": [],\n    \"blocks\": [],\n    \"owner\": \"\",\n}\n```\n\n每个字段都对应一个很实用的问题：\n\n- `id`：怎么唯一找到这条任务\n- `subject`：这条任务一句话在做什么\n- `description`：还有哪些补充说明\n- `status`：现在走到哪一步\n- `blockedBy`：还在等谁\n- `blocks`：它完成后会解锁谁\n- `owner`：现在由谁来做\n\n### 2. TaskStatus\n\n教学版先只保留最少 4 个状态：\n\n```text\npending -> in_progress -> completed\ndeleted\n```\n\n解释如下：\n\n- `pending`：还没开始\n- `in_progress`：已经有人在做\n- `completed`：已经做完\n- `deleted`：逻辑删除，不再参与工作流\n\n### 3. Ready Rule\n\n这是本章最关键的一条判断规则：\n\n```python\ndef is_ready(task: dict) -> bool:\n    return task[\"status\"] == \"pending\" and not task[\"blockedBy\"]\n```\n\n如果你把这条规则讲明白，读者就会第一次真正明白：\n\n**任务系统的核心不是“保存清单”，而是“判断什么时候能开工”。**\n\n## 最小实现\n\n### 第一步：让任务落盘\n\n不要只把任务放在 `messages` 里。  \n教学版最简单的做法，就是“一任务一文件”：\n\n```text\n.tasks/\n  task_1.json\n  task_2.json\n  task_3.json\n```\n\n创建任务时，直接写成一条 JSON 记录：\n\n```python\nclass TaskManager:\n    def create(self, subject: str, description: str = \"\") -> dict:\n        task = {\n            \"id\": self._next_id(),\n            \"subject\": subject,\n            \"description\": description,\n            \"status\": \"pending\",\n            \"blockedBy\": [],\n            \"blocks\": [],\n            \"owner\": \"\",\n        }\n        self._save(task)\n        return task\n```\n\n### 第二步：把依赖关系写成双向\n\n如果任务 A 完成后会解锁任务 B，最好同时维护两边：\n\n- A 的 `blocks` 里有 B\n- B 的 `blockedBy` 里有 A\n\n```python\ndef add_dependency(self, task_id: int, blocks_id: int):\n    task = self._load(task_id)\n    blocked = self._load(blocks_id)\n\n    if blocks_id not in task[\"blocks\"]:\n        task[\"blocks\"].append(blocks_id)\n    if task_id not in blocked[\"blockedBy\"]:\n        blocked[\"blockedBy\"].append(task_id)\n\n    self._save(task)\n    self._save(blocked)\n```\n\n这样做的好处是：\n\n- 从前往后读得懂\n- 从后往前也读得懂\n\n### 第三步：完成任务时自动解锁后续任务\n\n```python\ndef complete(self, task_id: int):\n    task = self._load(task_id)\n    task[\"status\"] = \"completed\"\n    self._save(task)\n\n    for other in self._all_tasks():\n        if task_id in other[\"blockedBy\"]:\n            other[\"blockedBy\"].remove(task_id)\n            self._save(other)\n```\n\n这一步非常关键。\n\n因为它说明：\n\n**任务系统不是静态记录表，而是会随着完成事件自动推进的工作图。**\n\n### 第四步：把任务工具接给模型\n\n教学版最小工具集建议先只做这 4 个：\n\n- `task_create`\n- `task_update`\n- `task_get`\n- `task_list`\n\n这样模型就能：\n\n- 新建任务\n- 更新状态\n- 看单条任务\n- 看整张任务板\n\n## 如何接到主循环里\n\n从 `s12` 开始，主循环第一次拥有了“会话外状态”。\n\n典型流程是：\n\n```text\n用户提出复杂目标\n  ->\n模型决定先拆任务\n  ->\n调用 task_create / task_update\n  ->\n任务落到 .tasks/\n  ->\n后续轮次继续读取并推进\n```\n\n这里要牢牢记住一句话：\n\n**todo 更像本轮计划，task 更像长期工作板。**\n\n## 这一章和 s03、s13 的边界\n\n这一层边界必须讲清楚，不然后面一定会混。\n\n### 和 `s03` 的区别\n\n| 机制 | 更适合什么 |\n|---|---|\n| `todo` | 当前会话里快速列步骤 |\n| `task` | 持久化工作、依赖关系、多人协作 |\n\n如果只是“先看文件，再改代码，再跑测试”，todo 往往就够。  \n如果是“跨很多轮、多人协作、还要管依赖”，就要上 task。\n\n### 和 `s13` 的区别\n\n本章的 `task` 指的是：\n\n> 一条工作目标\n\n它回答的是：\n\n- 要做什么\n- 现在做到哪一步\n- 谁在等谁\n\n它不是：\n\n- 某个正在后台跑的 `pytest`\n- 某个正在执行的 worker\n- 某条当前活着的执行线程\n\n后面这些属于下一章要讲的：\n\n> 运行中的执行任务\n\n## 初学者最容易犯的错\n\n### 1. 只会创建任务，不会维护依赖\n\n那最后得到的还是一张普通清单，不是任务图。\n\n### 2. 任务只放内存，不落盘\n\n系统一重启，整个工作结构就没了。\n\n### 3. 完成任务后不自动解锁后续任务\n\n这样系统永远不知道下一步谁可以开工。\n\n### 4. 把工作目标和运行中的执行混成一层\n\n这会导致后面 `s13` 的后台任务系统很难讲清。\n\n## 教学边界\n\n这一章先要守住的，不是任务平台以后还能长出多少管理功能，而是任务记录本身的最小主干：\n\n- `TaskRecord`\n- 依赖关系\n- 持久化\n- 就绪判断\n\n只要读者已经能把 todo 和 task、工作目标和运行执行明确分开，并且能手写一个会解锁后续任务的最小任务图，这章就已经讲到位了。\n\n## 学完这一章，你应该真正掌握什么\n\n学完以后，你应该能独立说清这几件事：\n\n1. 任务系统比 todo 多出来的核心能力，是“依赖关系”和“持久化”。\n2. `TaskRecord` 是本章最关键的数据结构。\n3. `blockedBy` / `blocks` 让系统能看懂前后关系。\n4. `is_ready()` 让系统能判断“谁现在可以开始”。\n\n如果这 4 件事都已经清楚，说明你已经能从 0 到 1 手写一个最小任务系统。\n\n## 下一章学什么\n\n这一章解决的是：\n\n> 工作目标如何被长期组织。\n\n下一章 `s13` 要解决的是：\n\n> 某个慢命令正在后台跑时，主循环怎么继续前进。\n\n也就是从“工作图”走向“运行时执行层”。\n"
  },
  {
    "version": "s13",
    "slug": "s13-background-tasks",
    "locale": "zh",
    "title": "s13: Background Tasks (后台任务)",
    "kind": "chapter",
    "filename": "s13-background-tasks.md",
    "content": "# s13: Background Tasks (后台任务)\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > [ s13 ] > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *慢命令可以在旁边等，主循环不必陪着发呆。*\n\n## 这一章要解决什么问题\n\n前面几章里，工具调用基本都是：\n\n```text\n模型发起\n  ->\n立刻执行\n  ->\n立刻返回结果\n```\n\n这对短命令没有问题。  \n但一旦遇到这些慢操作，就会卡住：\n\n- `npm install`\n- `pytest`\n- `docker build`\n- 大型代码生成或检查任务\n\n如果主循环一直同步等待，会出现两个坏处：\n\n- 模型在等待期间什么都做不了\n- 用户明明还想继续别的工作，却被整轮流程堵住\n\n所以这一章要解决的是：\n\n**把“慢执行”移到后台，让主循环继续推进别的事情。**\n\n## 建议联读\n\n- 如果你还没有彻底稳住“任务目标”和“执行槽位”是两层对象，先看 [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)。\n- 如果你开始分不清哪些状态该落在 `RuntimeTaskRecord`、哪些还应留在任务板，回看 [`data-structures.md`](./data-structures.md)。\n- 如果你开始把后台执行理解成“另一条主循环”，先看 [`s02b-tool-execution-runtime.md`](./s02b-tool-execution-runtime.md)，重新校正“并行的是执行与等待，不是主循环本身”。\n\n## 先把几个词讲明白\n\n### 什么叫前台\n\n前台指的是：\n\n> 主循环这轮发起以后，必须立刻等待结果的执行路径。\n\n### 什么叫后台\n\n后台不是神秘系统。  \n后台只是说：\n\n> 命令先在另一条执行线上跑，主循环先去做别的事。\n\n### 什么叫通知队列\n\n通知队列就是一条“稍后再告诉主循环”的收件箱。\n\n后台任务完成以后，不是直接把全文硬塞回模型，  \n而是先写一条摘要通知，等下一轮再统一带回去。\n\n## 最小心智模型\n\n这一章最关键的句子是：\n\n**主循环仍然只有一条，并行的是等待，不是主循环本身。**\n\n可以把结构画成这样：\n\n```text\n主循环\n  |\n  +-- background_run(\"pytest\")\n  |      -> 立刻返回 task_id\n  |\n  +-- 继续别的工作\n  |\n  +-- 下一轮模型调用前\n         -> drain_notifications()\n         -> 把摘要注入 messages\n\n后台执行线\n  |\n  +-- 真正执行 pytest\n  +-- 完成后写入通知队列\n```\n\n如果读者能牢牢记住这张图，后面扩展成更复杂的异步系统也不会乱。\n\n## 关键数据结构\n\n### 1. RuntimeTaskRecord\n\n```python\ntask = {\n    \"id\": \"a1b2c3d4\",\n    \"command\": \"pytest\",\n    \"status\": \"running\",\n    \"started_at\": 1710000000.0,\n    \"result_preview\": \"\",\n    \"output_file\": \"\",\n}\n```\n\n这些字段分别表示：\n\n- `id`：唯一标识\n- `command`：正在跑什么命令\n- `status`：运行中、完成、失败、超时\n- `started_at`：什么时候开始\n- `result_preview`：先给模型看的简短摘要\n- `output_file`：完整输出写到了哪里\n\n教学版再往前走一步时，建议把它直接落成两份文件：\n\n```text\n.runtime-tasks/\n  a1b2c3d4.json   # RuntimeTaskRecord\n  a1b2c3d4.log    # 完整输出\n```\n\n这样读者会更容易理解：\n\n- `json` 记录的是运行状态\n- `log` 保存的是完整产物\n- 通知只负责把 `preview` 带回主循环\n\n### 2. Notification\n\n```python\nnotification = {\n    \"type\": \"background_completed\",\n    \"task_id\": \"a1b2c3d4\",\n    \"status\": \"completed\",\n    \"preview\": \"tests passed\",\n}\n```\n\n通知只负责做一件事：\n\n> 告诉主循环“有结果回来了，你要不要看”。\n\n它不是完整日志本体。\n\n## 最小实现\n\n### 第一步：登记后台任务\n\n```python\nclass BackgroundManager:\n    def __init__(self):\n        self.tasks = {}\n        self.notifications = []\n        self.lock = threading.Lock()\n```\n\n这里最少要有两块状态：\n\n- `tasks`：当前有哪些后台任务\n- `notifications`：哪些结果已经回来，等待主循环领取\n\n### 第二步：启动后台执行线\n\n“线程”这个词第一次见可能会有点紧张。  \n你可以先把它理解成：\n\n> 同一个程序里，另一条可以独立往前跑的执行线。\n\n```python\ndef run(self, command: str) -> str:\n    task_id = new_id()\n    self.tasks[task_id] = {\n        \"id\": task_id,\n        \"command\": command,\n        \"status\": \"running\",\n    }\n\n    thread = threading.Thread(\n        target=self._execute,\n        args=(task_id, command),\n        daemon=True,\n    )\n    thread.start()\n    return task_id\n```\n\n这一步最重要的不是线程本身，而是：\n\n**主循环拿到 `task_id` 后就可以先继续往前走。**\n\n### 第三步：完成后写通知\n\n```python\ndef _execute(self, task_id: str, command: str):\n    try:\n        result = subprocess.run(..., timeout=300)\n        status = \"completed\"\n        preview = (result.stdout + result.stderr)[:500]\n    except subprocess.TimeoutExpired:\n        status = \"timeout\"\n        preview = \"command timed out\"\n\n    with self.lock:\n        self.tasks[task_id][\"status\"] = status\n        self.notifications.append({\n            \"type\": \"background_completed\",\n            \"task_id\": task_id,\n            \"status\": status,\n            \"preview\": preview,\n        })\n```\n\n这里体现的思想很重要：\n\n**后台执行负责产出结果，通知队列负责把结果送回主循环。**\n\n### 第四步：下一轮前排空通知\n\n```python\ndef before_model_call(messages: list):\n    notifications = bg.drain_notifications()\n    if not notifications:\n        return\n\n    text = \"\\n\".join(\n        f\"[bg:{n['task_id']}] {n['status']} - {n['preview']}\"\n        for n in notifications\n    )\n    messages.append({\"role\": \"user\", \"content\": text})\n```\n\n这样模型在下一轮就会知道：\n\n- 哪个后台任务完成了\n- 是成功、失败还是超时\n- 如果要看全文，该再去读文件\n\n## 为什么完整输出不要直接塞回 prompt\n\n这是本章必须讲透的点。\n\n如果后台任务输出几万行日志，你不能每次都把全文塞回上下文。  \n更稳的做法是：\n\n1. 完整输出写磁盘\n2. 通知里只放简短摘要\n3. 模型真的要看全文时，再调用 `read_file`\n\n这背后的心智很重要：\n\n**通知负责提醒，文件负责存原文。**\n\n## 如何接到主循环里\n\n从 `s13` 开始，主循环多出一个标准前置步骤：\n\n```text\n1. 先排空通知队列\n2. 再调用模型\n3. 普通工具照常同步执行\n4. 如果模型调用 background_run，就登记后台任务并立刻返回 task_id\n5. 下一轮再把后台结果带回模型\n```\n\n教学版最小工具建议先做两个：\n\n- `background_run`\n- `background_check`\n\n这样已经足够支撑最小异步执行闭环。\n\n## 这一章和任务系统的边界\n\n这是本章最容易和 `s12` 混掉的地方。\n\n### `s12` 的 task 是什么\n\n`s12` 里的 `task` 是：\n\n> 工作目标\n\n它关心的是：\n\n- 要做什么\n- 谁依赖谁\n- 现在总体进度如何\n\n### `s13` 的 background task 是什么\n\n本章里的后台任务是：\n\n> 正在运行的执行单元\n\n它关心的是：\n\n- 哪个命令正在跑\n- 跑到什么状态\n- 结果什么时候回来\n\n所以最稳的记法是：\n\n- `task` 更像工作板\n- `background task` 更像运行中的作业\n\n两者相关，但不是同一个东西。\n\n## 初学者最容易犯的错\n\n### 1. 以为“后台”就是更复杂的主循环\n\n不是。  \n主循环仍然尽量保持单主线。\n\n### 2. 只开线程，不登记状态\n\n这样任务一多，你根本不知道：\n\n- 谁还在跑\n- 谁已经完成\n- 谁失败了\n\n### 3. 把长日志全文塞进上下文\n\n上下文很快就会被撑爆。\n\n### 4. 把 `s12` 的工作目标和本章的运行任务混为一谈\n\n这会让后面多 agent 和调度章节全部打结。\n\n## 教学边界\n\n这一章只需要先把一个最小运行时模式讲清楚：\n\n- 慢工作在后台跑\n- 主循环继续保持单主线\n- 结果通过通知路径在后面回到模型\n\n只要这条模式稳了，线程池、更多 worker 类型、更复杂的事件系统都可以后补。\n\n这章真正要让读者守住的是：\n\n**并行的是等待与执行槽位，不是主循环本身。**\n\n## 学完这一章，你应该真正掌握什么\n\n学完以后，你应该能独立复述下面几句话：\n\n1. 主循环只有一条，并行的是等待，不是主循环本身。\n2. 后台任务至少需要“任务表 + 通知队列”两块状态。\n3. `background_run` 应该立刻返回 `task_id`，而不是同步卡住。\n4. 通知只放摘要，完整输出放文件。\n\n如果这 4 句话都已经非常清楚，说明你已经掌握了后台任务系统的核心。\n\n## 下一章学什么\n\n这一章解决的是：\n\n> 慢命令如何在后台运行。\n\n下一章 `s14` 要解决的是：\n\n> 如果连“启动后台任务”这件事都不一定由当前用户触发，而是由时间触发，该怎么做。\n\n也就是从“异步运行”继续走向“定时触发”。\n"
  },
  {
    "version": null,
    "slug": "s13a-runtime-task-model",
    "locale": "zh",
    "title": "s13a: Runtime Task Model (运行时任务模型)",
    "kind": "bridge",
    "filename": "s13a-runtime-task-model.md",
    "content": "# s13a: Runtime Task Model (运行时任务模型)\n\n> 这篇桥接文档专门解决一个非常容易混淆的问题：\n>\n> **任务板里的 task，和后台/队友/监控这些“正在运行的任务”，不是同一个东西。**\n\n## 建议怎么联读\n\n这篇最好夹在下面几份文档中间读：\n\n- 先看 [`s12-task-system.md`](./s12-task-system.md)，确认工作图任务在讲什么。\n- 再看 [`s13-background-tasks.md`](./s13-background-tasks.md)，确认后台执行在讲什么。\n- 如果词开始混，再回 [`glossary.md`](./glossary.md)。\n- 如果想把字段和状态彻底对上，再对照 [`data-structures.md`](./data-structures.md) 和 [`entity-map.md`](./entity-map.md)。\n\n## 为什么必须单独讲这一篇\n\n主线里：\n\n- `s12` 讲的是任务系统\n- `s13` 讲的是后台任务\n\n这两章各自都没错。  \n但如果不额外补一层桥接，很多读者很快就会把两种“任务”混在一起。\n\n例如：\n\n- 任务板里的 “实现 auth 模块”\n- 后台执行里的 “正在跑 pytest”\n- 队友执行里的 “alice 正在做代码改动”\n\n这些都可以叫“任务”，但它们不在同一层。\n\n为了让整个仓库接近满分，这一层必须讲透。\n\n## 先解释两个完全不同的“任务”\n\n### 第一种：工作图任务\n\n这就是 `s12` 里的任务板节点。\n\n它回答的是：\n\n- 要做什么\n- 谁依赖谁\n- 谁认领了\n- 当前进度如何\n\n它更像：\n\n> 工作计划中的一个可跟踪工作单元。\n\n### 第二种：运行时任务\n\n这类任务回答的是：\n\n- 现在有什么执行单元正在跑\n- 它是什么类型\n- 是在运行、完成、失败还是被杀掉\n- 输出文件在哪\n\n它更像：\n\n> 系统当前活着的一条执行槽位。\n\n## 最小心智模型\n\n你可以先把两者画成两张表：\n\n```text\n工作图任务\n  - durable\n  - 面向目标与依赖\n  - 生命周期更长\n\n运行时任务\n  - runtime\n  - 面向执行与输出\n  - 生命周期更短\n```\n\n它们的关系不是“二选一”，而是：\n\n```text\n一个工作图任务\n  可以派生\n一个或多个运行时任务\n```\n\n例如：\n\n```text\n工作图任务：\n  \"实现 auth 模块\"\n\n运行时任务：\n  1. 后台跑测试\n  2. 启动一个 coder teammate\n  3. 监控一个 MCP 服务返回结果\n```\n\n## 为什么这层区别非常重要\n\n如果不区分这两层，后面很多章节都会开始缠在一起：\n\n- `s13` 的后台任务会和 `s12` 的任务板混淆\n- `s15-s17` 的队友任务会不知道该挂在哪\n- `s18` 的 worktree 到底绑定哪一层任务，也会变模糊\n\n所以你要先记住一句：\n\n**工作图任务管“目标”，运行时任务管“执行”。**\n\n## 关键数据结构\n\n### 1. WorkGraphTaskRecord\n\n这就是 `s12` 里的那条 durable task。\n\n```python\ntask = {\n    \"id\": 12,\n    \"subject\": \"Implement auth module\",\n    \"status\": \"in_progress\",\n    \"blockedBy\": [],\n    \"blocks\": [13],\n    \"owner\": \"alice\",\n    \"worktree\": \"auth-refactor\",\n}\n```\n\n### 2. RuntimeTaskState\n\n教学版可以先用这个最小形状：\n\n```python\nruntime_task = {\n    \"id\": \"b8k2m1qz\",\n    \"type\": \"local_bash\",\n    \"status\": \"running\",\n    \"description\": \"Run pytest\",\n    \"start_time\": 1710000000.0,\n    \"end_time\": None,\n    \"output_file\": \".task_outputs/b8k2m1qz.txt\",\n    \"notified\": False,\n}\n```\n\n这里的字段重点在于：\n\n- `type`：它是什么执行单元\n- `status`：它现在在运行态还是终态\n- `output_file`：它的产出在哪\n- `notified`：结果有没有回通知系统\n\n### 3. RuntimeTaskType\n\n你不必在教学版里一次性实现所有类型，  \n但应该让读者知道“运行时任务”是一个类型族，而不只是 `background shell` 一种。\n\n最小类型表可以先这样讲：\n\n```text\nlocal_bash\nlocal_agent\nremote_agent\nin_process_teammate\nmonitor\nworkflow\n```\n\n## 最小实现\n\n### 第一步：继续保留 `s12` 的任务板\n\n这一层不要动。\n\n### 第二步：单独加一个 RuntimeTaskManager\n\n```python\nclass RuntimeTaskManager:\n    def __init__(self):\n        self.tasks = {}\n```\n\n### 第三步：后台运行时创建 runtime task\n\n```python\ndef spawn_bash_task(command: str):\n    task_id = new_runtime_id()\n    runtime_tasks[task_id] = {\n        \"id\": task_id,\n        \"type\": \"local_bash\",\n        \"status\": \"running\",\n        \"description\": command,\n    }\n```\n\n### 第四步：必要时把 runtime task 关联回工作图任务\n\n```python\nruntime_tasks[task_id][\"work_graph_task_id\"] = 12\n```\n\n这一步不是必须一上来就做，但如果系统进入多 agent / worktree 阶段，就会越来越重要。\n\n## 一张真正清楚的图\n\n```text\nWork Graph\n  task #12: Implement auth module\n        |\n        +-- spawns runtime task A: local_bash (pytest)\n        +-- spawns runtime task B: local_agent (coder worker)\n        +-- spawns runtime task C: monitor (watch service status)\n\nRuntime Task Layer\n  A/B/C each have:\n  - own runtime ID\n  - own status\n  - own output\n  - own lifecycle\n```\n\n## 它和后面章节怎么连\n\n这层一旦讲清楚，后面几章会顺很多：\n\n- `s13` 后台命令，本质上是 runtime task\n- `s15-s17` 队友/agent，也可以看成 runtime task 的一种\n- `s18` worktree 主要绑定工作图任务，但也会影响运行时执行环境\n- `s19` 某些外部监控或异步调用，也可能落成 runtime task\n\n所以后面只要你看到“有东西在后台活着并推进工作”，都可以先问自己两句：\n\n- 它是不是某个 durable work graph task 派生出来的执行槽位。\n- 它的状态是不是应该放在 runtime layer，而不是任务板节点里。\n\n## 初学者最容易犯的错\n\n### 1. 把后台 shell 直接写成任务板状态\n\n这样 durable task 和 runtime state 就混在一起了。\n\n### 2. 认为一个工作图任务只能对应一个运行时任务\n\n现实里很常见的是一个工作目标派生多个执行单元。\n\n### 3. 用同一套状态名描述两层对象\n\n例如：\n\n- 工作图任务的 `pending / in_progress / completed`\n- 运行时任务的 `running / completed / failed / killed`\n\n这两套状态最好不要混。\n\n### 4. 忽略 output file 和 notified 这类运行时字段\n\n工作图任务不太关心这些，运行时任务非常关心。\n\n## 教学边界\n\n这篇最重要的，不是把运行时字段一次加满，而是先把下面三层对象彻底拆开：\n\n- durable task 是长期工作目标\n- runtime task 是当前活着的执行槽位\n- notification / output 只是运行时把结果带回来的通道\n\n运行时任务类型枚举、增量输出 offset、槽位清理策略，都可以等你先把这三层边界手写清楚以后再扩展。\n\n## 一句话记住\n\n**工作图任务管“长期目标和依赖”，运行时任务管“当前活着的执行单元和输出”。**\n\n**`s12` 的 task 是工作图节点，`s13+` 的 runtime task 是系统里真正跑起来的执行单元。**\n"
  },
  {
    "version": "s14",
    "slug": "s14-cron-scheduler",
    "locale": "zh",
    "title": "s14: Cron Scheduler (定时调度)",
    "kind": "chapter",
    "filename": "s14-cron-scheduler.md",
    "content": "# s14: Cron Scheduler (定时调度)\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > [ s14 ] > s15 > s16 > s17 > s18 > s19`\n\n> *如果后台任务解决的是“稍后回来拿结果”，那么定时调度解决的是“将来某个时间再开始做事”。*\n\n## 这一章要解决什么问题\n\n`s13` 已经让系统学会了把慢命令放到后台。\n\n但后台任务默认还是“现在就启动”。\n\n很多真实需求并不是现在做，而是：\n\n- 每天晚上跑一次测试\n- 每周一早上生成报告\n- 30 分钟后提醒我继续检查某个结果\n\n如果没有调度能力，用户就只能每次手动再说一遍。  \n这会让系统看起来像“只能响应当下”，而不是“能安排未来工作”。\n\n所以这一章要加上的能力是：\n\n**把一条未来要执行的意图，先记下来，等时间到了再触发。**\n\n## 建议联读\n\n- 如果你还没完全分清 `schedule`、`task`、`runtime task` 各自表示什么，先回 [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)。\n- 如果你想重新看清“一条触发最终是怎样回到主循环里的”，可以配合读 [`s00b-one-request-lifecycle.md`](./s00b-one-request-lifecycle.md)。\n- 如果你开始把“未来触发”误以为“又多了一套执行系统”，先回 [`data-structures.md`](./data-structures.md)，确认调度记录和运行时记录不是同一个表。\n\n## 先解释几个名词\n\n### 什么是调度器\n\n调度器，就是一段专门负责“看时间、查任务、决定是否触发”的代码。\n\n### 什么是 cron 表达式\n\n`cron` 是一种很常见的定时写法。\n\n最小 5 字段版本长这样：\n\n```text\n分 时 日 月 周\n```\n\n例如：\n\n```text\n*/5 * * * *   每 5 分钟\n0 9 * * 1     每周一 9 点\n30 14 * * *   每天 14:30\n```\n\n如果你是初学者，不用先背全。\n\n这一章真正重要的不是语法细节，而是：\n\n> “系统如何把一条未来任务记住，并在合适时刻放回主循环。”\n\n### 什么是持久化调度\n\n持久化，意思是：\n\n> 就算程序重启，这条调度记录还在。\n\n## 最小心智模型\n\n先把调度看成 3 个部分：\n\n```text\n1. 调度记录\n2. 定时检查器\n3. 通知队列\n```\n\n它们之间的关系是：\n\n```text\nschedule_create(...)\n  ->\n把记录写到列表或文件里\n  ->\n后台检查器每分钟看一次“现在是否匹配”\n  ->\n如果匹配，就把 prompt 放进通知队列\n  ->\n主循环下一轮把它当成新的用户消息喂给模型\n```\n\n这条链路很重要。\n\n因为它说明了一点：\n\n**定时调度并不是另一套 agent。它最终还是回到同一条主循环。**\n\n## 关键数据结构\n\n### 1. ScheduleRecord\n\n```python\nschedule = {\n    \"id\": \"job_001\",\n    \"cron\": \"0 9 * * 1\",\n    \"prompt\": \"Run the weekly status report.\",\n    \"recurring\": True,\n    \"durable\": True,\n    \"created_at\": 1710000000.0,\n    \"last_fired_at\": None,\n}\n```\n\n字段含义：\n\n- `id`：唯一编号\n- `cron`：定时规则\n- `prompt`：到点后要注入主循环的提示\n- `recurring`：是不是反复触发\n- `durable`：是否落盘保存\n- `created_at`：创建时间\n- `last_fired_at`：上次触发时间\n\n### 2. 调度通知\n\n```python\n{\n    \"type\": \"scheduled_prompt\",\n    \"schedule_id\": \"job_001\",\n    \"prompt\": \"Run the weekly status report.\",\n}\n```\n\n### 3. 检查周期\n\n教学版建议先按“分钟级”思考，而不是“秒级严格精度”。\n\n因为大多数 cron 任务本来就不是为了卡秒执行。\n\n## 最小实现\n\n### 第一步：允许创建一条调度记录\n\n```python\ndef create(self, cron_expr: str, prompt: str, recurring: bool = True):\n    job = {\n        \"id\": new_id(),\n        \"cron\": cron_expr,\n        \"prompt\": prompt,\n        \"recurring\": recurring,\n        \"created_at\": time.time(),\n        \"last_fired_at\": None,\n    }\n    self.jobs.append(job)\n    return job\n```\n\n### 第二步：写一个定时检查循环\n\n```python\ndef check_loop(self):\n    while True:\n        now = datetime.now()\n        self.check_jobs(now)\n        time.sleep(60)\n```\n\n最小教学版先每分钟检查一次就足够。\n\n### 第三步：时间到了就发通知\n\n```python\ndef check_jobs(self, now):\n    for job in self.jobs:\n        if cron_matches(job[\"cron\"], now):\n            self.queue.put({\n                \"type\": \"scheduled_prompt\",\n                \"schedule_id\": job[\"id\"],\n                \"prompt\": job[\"prompt\"],\n            })\n            job[\"last_fired_at\"] = now.timestamp()\n```\n\n### 第四步：主循环像处理后台通知一样处理定时通知\n\n```python\nnotifications = scheduler.drain()\nfor item in notifications:\n    messages.append({\n        \"role\": \"user\",\n        \"content\": f\"[scheduled:{item['schedule_id']}] {item['prompt']}\",\n    })\n```\n\n这样一来，定时任务最终还是由模型接手继续做。\n\n## 为什么这章放在后台任务之后\n\n因为这两章解决的问题很接近，但不是同一件事。\n\n可以这样区分：\n\n| 机制 | 回答的问题 |\n|---|---|\n| 后台任务 | “已经启动的慢操作，结果什么时候回来？” |\n| 定时调度 | “一件事应该在未来什么时候开始？” |\n\n这个顺序对初学者很友好。\n\n因为先理解“异步结果回来”，再理解“未来触发一条新意图”，心智会更顺。\n\n## 初学者最容易犯的错\n\n### 1. 一上来沉迷 cron 语法细节\n\n这章最容易跑偏到一大堆表达式规则。\n\n但教学主线其实不是“背语法”，而是：\n\n**调度记录如何进入通知队列，又如何回到主循环。**\n\n### 2. 没有 `last_fired_at`\n\n没有这个字段，系统很容易在短时间内重复触发同一条任务。\n\n### 3. 只放内存，不支持落盘\n\n如果用户希望“明天再提醒我”，程序一重启就没了，这就不是真正的调度。\n\n### 4. 把调度触发结果直接在后台默默执行\n\n教学主线里更清楚的做法是：\n\n- 时间到了\n- 先发通知\n- 再让主循环决定怎么处理\n\n这样系统行为更透明，读者也更容易理解。\n\n### 5. 误以为定时任务必须绝对准点\n\n很多初学者会把调度想成秒表。\n\n但这里更重要的是“有计划地触发”，而不是追求毫秒级精度。\n\n## 如何接到整个系统里\n\n到了这一章，系统已经有两条重要的“外部事件输入”：\n\n- 后台任务完成通知\n- 定时调度触发通知\n\n二者最好的统一方式是：\n\n**都走通知队列，再在下一次模型调用前统一注入。**\n\n这样主循环结构不会越来越乱。\n\n## 教学边界\n\n这一章先讲清一条主线就够了：\n\n**调度器做的是“记住未来”，不是“取代主循环”。**\n\n所以教学版先只需要让读者看清：\n\n- schedule record 负责记住未来何时开工\n- 真正执行工作时，仍然回到任务系统和通知队列\n- 它只是多了一种“开始入口”，不是多了一条新的主循环\n\n多进程锁、漏触发补报、自然语言时间语法这些，都应该排在这条主线之后。\n\n## 试一试\n\n```sh\ncd learn-claude-code\npython agents/s14_cron_scheduler.py\n```\n\n可以试试这些任务：\n\n1. 建一个每分钟触发一次的小任务，观察它是否会按时进入通知队列。\n2. 建一个只触发一次的任务，确认触发后是否会消失。\n3. 重启程序，检查持久化的调度记录是否还在。\n\n读完这一章，你应该能自己说清这句话：\n\n**后台任务是在“等结果”，定时调度是在“等开始”。**\n"
  },
  {
    "version": "s15",
    "slug": "s15-agent-teams",
    "locale": "zh",
    "title": "s15: Agent Teams (智能体团队)",
    "kind": "chapter",
    "filename": "s15-agent-teams.md",
    "content": "# s15: Agent Teams (智能体团队)\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > [ s15 ] > s16 > s17 > s18 > s19`\n\n> *子 agent 适合一次性委派；团队系统解决的是“有人长期在线、能继续接活、能互相协作”。*\n\n## 这一章要解决什么问题\n\n`s04` 的 subagent 已经能帮主 agent 拆小任务。\n\n但 subagent 有一个很明显的边界：\n\n```text\n创建 -> 执行 -> 返回摘要 -> 消失\n```\n\n这很适合一次性的小委派。  \n可如果你想做这些事，就不够用了：\n\n- 让一个测试 agent 长期待命\n- 让两个 agent 长期分工\n- 让某个 agent 未来收到新任务后继续工作\n\n也就是说，系统现在缺的不是“再开一个模型调用”，而是：\n\n**一批有身份、能长期存在、能反复协作的队友。**\n\n## 建议联读\n\n- 如果你还在把 teammate 和 `s04` 的 subagent 混成一类，先回 [`entity-map.md`](./entity-map.md)。\n- 如果你准备继续读 `s16-s18`，建议把 [`team-task-lane-model.md`](./team-task-lane-model.md) 放在手边，它会把 teammate、protocol request、task、runtime slot、worktree lane 这五层一起拆开。\n- 如果你开始怀疑“长期队友”和“活着的执行槽位”到底是什么关系，配合看 [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)。\n\n## 先把几个词讲明白\n\n### 什么是队友\n\n这里的 `teammate` 指的是：\n\n> 一个拥有名字、角色、消息入口和生命周期的持久 agent。\n\n### 什么是名册\n\n名册就是团队成员列表。\n\n它回答的是：\n\n- 现在队伍里有谁\n- 每个人是什么角色\n- 每个人现在是空闲、工作中还是已关闭\n\n### 什么是邮箱\n\n邮箱就是每个队友的收件箱。\n\n别人把消息发给它，  \n它在自己的下一轮工作前先去收消息。\n\n## 最小心智模型\n\n这一章最简单的理解方式，是把每个队友都想成：\n\n> 一个有自己循环、自己收件箱、自己上下文的人。\n\n```text\nlead\n  |\n  +-- spawn alice (coder)\n  +-- spawn bob (tester)\n  |\n  +-- send message --> alice inbox\n  +-- send message --> bob inbox\n\nalice\n  |\n  +-- 自己的 messages\n  +-- 自己的 inbox\n  +-- 自己的 agent loop\n\nbob\n  |\n  +-- 自己的 messages\n  +-- 自己的 inbox\n  +-- 自己的 agent loop\n```\n\n和 `s04` 的最大区别是：\n\n**subagent 是一次性执行单元，teammate 是长期存在的协作成员。**\n\n## 关键数据结构\n\n### 1. TeamMember\n\n```python\nmember = {\n    \"name\": \"alice\",\n    \"role\": \"coder\",\n    \"status\": \"working\",\n}\n```\n\n教学版先只保留这 3 个字段就够了：\n\n- `name`：名字\n- `role`：角色\n- `status`：状态\n\n### 2. TeamConfig\n\n```python\nconfig = {\n    \"team_name\": \"default\",\n    \"members\": [member1, member2],\n}\n```\n\n它通常可以放在：\n\n```text\n.team/config.json\n```\n\n这份名册让系统重启以后，仍然知道：\n\n- 团队里曾经有谁\n- 每个人当前是什么角色\n\n### 3. MessageEnvelope\n\n```python\nmessage = {\n    \"type\": \"message\",\n    \"from\": \"lead\",\n    \"content\": \"Please review auth module.\",\n    \"timestamp\": 1710000000.0,\n}\n```\n\n`envelope` 这个词本来是“信封”的意思。  \n程序里用它表示：\n\n> 把消息正文和元信息一起包起来的一条记录。\n\n## 最小实现\n\n### 第一步：先有一份队伍名册\n\n```python\nclass TeammateManager:\n    def __init__(self, team_dir: Path):\n        self.team_dir = team_dir\n        self.config_path = team_dir / \"config.json\"\n        self.config = self._load_config()\n```\n\n名册是本章的起点。  \n没有名册，就没有真正的“团队实体”。\n\n### 第二步：spawn 一个持久队友\n\n```python\ndef spawn(self, name: str, role: str, prompt: str):\n    member = {\"name\": name, \"role\": role, \"status\": \"working\"}\n    self.config[\"members\"].append(member)\n    self._save_config()\n\n    thread = threading.Thread(\n        target=self._teammate_loop,\n        args=(name, role, prompt),\n        daemon=True,\n    )\n    thread.start()\n```\n\n这里的关键不在于线程本身，而在于：\n\n**队友一旦被创建，就不只是一次性工具调用，而是一个有持续生命周期的成员。**\n\n### 第三步：给每个队友一个邮箱\n\n教学版最简单的做法可以直接用 JSONL 文件：\n\n```text\n.team/inbox/alice.jsonl\n.team/inbox/bob.jsonl\n```\n\n发消息时追加一行：\n\n```python\ndef send(self, sender: str, to: str, content: str):\n    with open(f\"{to}.jsonl\", \"a\") as f:\n        f.write(json.dumps({\n            \"type\": \"message\",\n            \"from\": sender,\n            \"content\": content,\n            \"timestamp\": time.time(),\n        }) + \"\\n\")\n```\n\n收消息时：\n\n1. 读出全部\n2. 解析为消息列表\n3. 清空收件箱\n\n### 第四步：队友每轮先看邮箱，再继续工作\n\n```python\ndef teammate_loop(name: str, role: str, prompt: str):\n    messages = [{\"role\": \"user\", \"content\": prompt}]\n\n    while True:\n        inbox = bus.read_inbox(name)\n        for item in inbox:\n            messages.append({\"role\": \"user\", \"content\": json.dumps(item)})\n\n        response = client.messages.create(...)\n        ...\n```\n\n这一步一定要讲透。\n\n因为它说明：\n\n**队友不是靠“被重新创建”来获得新任务，而是靠“下一轮先检查邮箱”来接收新工作。**\n\n## 如何接到前面章节的系统里\n\n这章最容易出现的误解是：\n\n> 好像系统突然“多了几个人”，但不知道这些人到底接在之前哪一层。\n\n更准确的接法应该是：\n\n```text\n用户目标 / lead 判断需要长期分工\n  ->\nspawn teammate\n  ->\n写入 .team/config.json\n  ->\n通过 inbox 分派消息、摘要、任务线索\n  ->\nteammate 先 drain inbox\n  ->\n进入自己的 agent loop 和工具调用\n  ->\n把结果回送给 lead，或继续等待下一轮工作\n```\n\n这里要特别看清三件事：\n\n1. `s12-s14` 已经给了你任务板、后台执行、时间触发这些“工作层”。\n2. `s15` 现在补的是“长期执行者”，也就是谁长期在线、谁能反复接活。\n3. 本章还没有进入“自己找活”或“自动认领”。\n\n也就是说，`s15` 的默认工作方式仍然是：\n\n- 由 lead 手动创建队友\n- 由 lead 通过邮箱分派事情\n- 队友在自己的循环里持续处理\n\n真正的自治认领，要到 `s17` 才展开。\n\n## Teammate、Subagent、Runtime Task 到底怎么区分\n\n这是这一组章节里最容易混的点。\n\n可以直接记这张表：\n\n| 机制 | 更像什么 | 生命周期 | 关键边界 |\n|---|---|---|\n| subagent | 一次性外包助手 | 干完就结束 | 重点是“隔离一小段探索性上下文” |\n| runtime task | 正在运行的后台执行槽位 | 任务跑完或取消就结束 | 重点是“慢任务稍后回来”，不是长期身份 |\n| teammate | 长期在线队友 | 可以反复接任务 | 重点是“有名字、有邮箱、有独立循环” |\n\n再换成更口语的话说：\n\n- subagent 适合“帮我查一下再回来汇报”\n- runtime task 适合“这件事你后台慢慢跑，结果稍后通知我”\n- teammate 适合“你以后长期负责测试方向”\n\n## 这一章的教学边界\n\n本章先只把 3 件事讲稳：\n\n- 名册\n- 邮箱\n- 独立循环\n\n这已经足够把“长期队友”这个实体立起来。\n\n但它还没有展开后面两层能力：\n\n### 第一层：结构化协议\n\n也就是：\n\n- 哪些消息只是普通交流\n- 哪些消息是带 `request_id` 的结构化请求\n\n这部分放到下一章 `s16`。\n\n### 第二层：自治认领\n\n也就是：\n\n- 队友空闲时能不能自己找活\n- 能不能自己恢复工作\n\n这部分放到 `s17`。\n\n## 初学者最容易犯的错\n\n### 1. 把队友当成“名字不同的 subagent”\n\n如果生命周期还是“执行完就销毁”，那本质上还不是 teammate。\n\n### 2. 队友之间共用同一份 messages\n\n这样上下文会互相污染。\n\n每个队友都应该有自己的对话状态。\n\n### 3. 没有持久名册\n\n如果系统关掉以后完全不知道“团队里曾经有谁”，那就很难继续做长期协作。\n\n### 4. 没有邮箱，靠共享变量直接喊话\n\n教学上不建议一开始就这么做。\n\n因为它会把“队友通信”和“进程内部细节”绑得太死。\n\n## 学完这一章，你应该真正掌握什么\n\n学完以后，你应该能独立说清下面几件事：\n\n1. teammate 的核心不是“多一个模型调用”，而是“多一个长期存在的执行者”。\n2. 团队系统至少需要“名册 + 邮箱 + 独立循环”。\n3. 每个队友都应该有自己的 `messages` 和自己的 inbox。\n4. subagent 和 teammate 的根本区别在生命周期，而不是名字。\n\n如果这 4 点已经稳了，说明你已经真正理解了“多 agent 团队”是怎么从单 agent 演化出来的。\n\n## 下一章学什么\n\n这一章解决的是：\n\n> 团队成员如何长期存在、互相发消息。\n\n下一章 `s16` 要解决的是：\n\n> 当消息不再只是自由聊天，而要变成可追踪、可批准、可拒绝的协作流程时，该怎么设计。\n\n也就是从“有团队”继续走向“团队协议”。\n"
  },
  {
    "version": "s16",
    "slug": "s16-team-protocols",
    "locale": "zh",
    "title": "s16: Team Protocols (团队协议)",
    "kind": "chapter",
    "filename": "s16-team-protocols.md",
    "content": "# s16: Team Protocols (团队协议)\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > [ s16 ] > s17 > s18 > s19`\n\n> *有了邮箱以后，团队已经能说话；有了协议以后，团队才开始会“按规矩协作”。*\n\n## 这一章要解决什么问题\n\n`s15` 已经让队友之间可以互相发消息。\n\n但如果所有事情都只靠自由文本，会有两个明显问题：\n\n- 某些动作必须明确批准或拒绝，不能只靠一句模糊回复\n- 一旦多个请求同时存在，系统很难知道“这条回复对应哪一件事”\n\n最典型的两个场景就是：\n\n1. 队友要不要优雅关机\n2. 某个高风险计划要不要先审批\n\n这两件事看起来不同，但结构其实一样：\n\n```text\n一方发请求\n另一方明确回复\n双方都能用同一个 request_id 对上号\n```\n\n所以这一章要加的，不是更多自由聊天，而是：\n\n**一层结构化协议。**\n\n## 建议联读\n\n- 如果你开始把普通消息和协议请求混掉，先回 [`glossary.md`](./glossary.md) 和 [`entity-map.md`](./entity-map.md)。\n- 如果你准备继续读 `s17` 和 `s18`，建议先看 [`team-task-lane-model.md`](./team-task-lane-model.md)，这样后面自治认领和 worktree 车道不会一下子缠在一起。\n- 如果你想重新确认协议请求最终怎样回流到主系统，可以配合看 [`s00b-one-request-lifecycle.md`](./s00b-one-request-lifecycle.md)。\n\n## 先把几个词讲明白\n\n### 什么是协议\n\n协议可以简单理解成：\n\n> 双方提前约定好“消息长什么样、收到以后怎么处理”。\n\n### 什么是 request_id\n\n`request_id` 就是请求编号。\n\n它的作用是：\n\n- 某个请求发出去以后有一个唯一身份\n- 之后的批准、拒绝、超时都能准确指向这一个请求\n\n### 什么是请求-响应模式\n\n这个词听起来像高级概念，其实很简单：\n\n```text\n请求方：我发起一件事\n响应方：我明确回答同意还是不同意\n```\n\n本章做的，就是把这种模式从“口头表达”升级成“结构化数据”。\n\n## 最小心智模型\n\n从教学角度，你可以先把协议看成两层：\n\n```text\n1. 协议消息\n2. 请求追踪表\n```\n\n### 协议消息\n\n```python\n{\n    \"type\": \"shutdown_request\",\n    \"from\": \"lead\",\n    \"to\": \"alice\",\n    \"request_id\": \"req_001\",\n    \"payload\": {},\n}\n```\n\n### 请求追踪表\n\n```python\nrequests = {\n    \"req_001\": {\n        \"kind\": \"shutdown\",\n        \"status\": \"pending\",\n    }\n}\n```\n\n只要这两层都存在，系统就能同时回答：\n\n- 现在发生了什么\n- 这件事目前走到哪一步\n\n## 关键数据结构\n\n### 1. ProtocolEnvelope\n\n```python\nmessage = {\n    \"type\": \"shutdown_request\",\n    \"from\": \"lead\",\n    \"to\": \"alice\",\n    \"request_id\": \"req_001\",\n    \"payload\": {},\n    \"timestamp\": 1710000000.0,\n}\n```\n\n它比普通消息多出来的关键字段就是：\n\n- `type`\n- `request_id`\n- `payload`\n\n### 2. RequestRecord\n\n```python\nrequest = {\n    \"request_id\": \"req_001\",\n    \"kind\": \"shutdown\",\n    \"from\": \"lead\",\n    \"to\": \"alice\",\n    \"status\": \"pending\",\n}\n```\n\n它负责记录：\n\n- 这是哪种请求\n- 谁发给谁\n- 当前状态是什么\n\n如果你想把教学版再往真实系统推进一步，建议不要只放在内存字典里，而是直接落盘：\n\n```text\n.team/requests/\n  req_001.json\n  req_002.json\n```\n\n这样系统就能做到：\n\n- 请求状态可恢复\n- 协议过程可检查\n- 即使主循环继续往前，请求记录也不会丢\n\n### 3. 状态机\n\n本章里的状态机非常简单：\n\n```text\npending -> approved\npending -> rejected\npending -> expired\n```\n\n这里再次提醒读者：\n\n`状态机` 的意思不是复杂理论，  \n只是“状态之间如何变化的一张规则表”。\n\n## 最小实现\n\n### 协议 1：优雅关机\n\n“优雅关机”的意思不是直接把线程硬砍掉。  \n而是：\n\n1. 先发关机请求\n2. 队友明确回复同意或拒绝\n3. 如果同意，先收尾，再退出\n\n发请求：\n\n```python\ndef request_shutdown(target: str):\n    request_id = new_id()\n    requests[request_id] = {\n        \"kind\": \"shutdown\",\n        \"target\": target,\n        \"status\": \"pending\",\n    }\n    bus.send(\n        \"lead\",\n        target,\n        msg_type=\"shutdown_request\",\n        extra={\"request_id\": request_id},\n        content=\"Please shut down gracefully.\",\n    )\n```\n\n收响应：\n\n```python\ndef handle_shutdown_response(request_id: str, approve: bool):\n    record = requests[request_id]\n    record[\"status\"] = \"approved\" if approve else \"rejected\"\n```\n\n### 协议 2：计划审批\n\n这其实还是同一个请求-响应模板。\n\n比如某个队友想做高风险改动，可以先提计划：\n\n```python\ndef submit_plan(name: str, plan_text: str):\n    request_id = new_id()\n    requests[request_id] = {\n        \"kind\": \"plan_approval\",\n        \"from\": name,\n        \"status\": \"pending\",\n        \"plan\": plan_text,\n    }\n    bus.send(\n        name,\n        \"lead\",\n        msg_type=\"plan_approval\",\n        extra={\"request_id\": request_id, \"plan\": plan_text},\n        content=\"Requesting review.\",\n    )\n```\n\n领导审批：\n\n```python\ndef review_plan(request_id: str, approve: bool, feedback: str = \"\"):\n    record = requests[request_id]\n    record[\"status\"] = \"approved\" if approve else \"rejected\"\n    bus.send(\n        \"lead\",\n        record[\"from\"],\n        msg_type=\"plan_approval_response\",\n        extra={\"request_id\": request_id, \"approve\": approve},\n        content=feedback,\n    )\n```\n\n看到这里，读者应该开始意识到：\n\n**本章最重要的不是“关机”或“计划”本身，而是同一个协议模板可以反复复用。**\n\n## 协议请求不是普通消息\n\n这一点一定要讲透。\n\n邮箱里虽然都叫“消息”，但 `s16` 以后其实已经分成两类：\n\n### 1. 普通消息\n\n适合：\n\n- 讨论\n- 提醒\n- 补充说明\n\n### 2. 协议消息\n\n适合：\n\n- 审批\n- 关机\n- 交接\n- 签收\n\n它至少要带：\n\n- `type`\n- `request_id`\n- `from`\n- `to`\n- `payload`\n\n最简单的记法是：\n\n- 普通消息解决“说了什么”\n- 协议消息解决“这件事走到哪一步了”\n\n## 如何接到团队系统里\n\n这章真正补上的，不只是两个新工具名，而是一条新的协作回路：\n\n```text\n某个队友 / lead 发起请求\n  ->\n写入 RequestRecord\n  ->\n把 ProtocolEnvelope 投递进对方 inbox\n  ->\n对方下一轮 drain inbox\n  ->\n按 request_id 更新请求状态\n  ->\n必要时再回一条 response\n  ->\n请求方根据 approved / rejected 继续后续动作\n```\n\n你可以把它理解成：\n\n- `s15` 给了团队“邮箱”\n- `s16` 现在给邮箱里的某些消息加上“编号 + 状态机 + 回执”\n\n如果少了这条结构化回路，团队虽然能沟通，但无法稳定协作。\n\n## MessageEnvelope、ProtocolEnvelope、RequestRecord、TaskRecord 的边界\n\n这 4 个对象很容易一起打结。最稳的记法是：\n\n| 对象 | 它回答什么问题 | 典型字段 |\n|---|---|---|\n| `MessageEnvelope` | 谁跟谁说了什么 | `from` / `to` / `content` |\n| `ProtocolEnvelope` | 这是不是一条结构化请求或响应 | `type` / `request_id` / `payload` |\n| `RequestRecord` | 这件协作流程现在走到哪一步 | `kind` / `status` / `from` / `to` |\n| `TaskRecord` | 真正的工作项是什么、谁在做、还卡着谁 | `subject` / `status` / `blockedBy` / `owner` |\n\n一定要牢牢记住：\n\n- 协议请求不是任务本身\n- 请求状态表也不是任务板\n- 协议只负责“协作流程”\n- 任务系统才负责“真正的工作推进”\n\n## 这一章的教学边界\n\n教学版先只讲 2 类协议就够了：\n\n- `shutdown`\n- `plan_approval`\n\n因为这两类已经足够把下面几件事讲清楚：\n\n- 什么是结构化消息\n- 什么是 request_id\n- 为什么要有请求状态表\n- 为什么协议不是自由文本\n\n等这套模板学稳以后，你完全可以再扩展：\n\n- 任务认领协议\n- 交接协议\n- 结果签收协议\n\n但这些都应该建立在本章的统一模板之上。\n\n## 初学者最容易犯的错\n\n### 1. 没有 `request_id`\n\n没有编号，多个请求同时存在时很快就会乱。\n\n### 2. 收到请求以后只回一句自然语言\n\n例如：\n\n```text\n好的，我知道了\n```\n\n人类可能看得懂，但系统很难稳定处理。\n\n### 3. 没有请求状态表\n\n如果系统不记录 `pending` / `approved` / `rejected`，协议其实就没有真正落地。\n\n### 4. 把协议消息和普通消息混成一种结构\n\n这样后面一多，处理逻辑会越来越混。\n\n## 学完这一章，你应该真正掌握什么\n\n学完以后，你应该能独立复述下面几件事：\n\n1. 团队协议的核心，是“请求-响应 + request_id + 状态表”。\n2. 协议消息和普通聊天消息不是一回事。\n3. 关机协议和计划审批虽然业务不同，但底层模板可以复用。\n4. 团队一旦进入结构化协作，就要靠协议，而不是只靠自然语言。\n\n如果这 4 点已经非常稳定，说明这一章真正学到了。\n\n## 下一章学什么\n\n这一章解决的是：\n\n> 团队如何按规则协作。\n\n下一章 `s17` 要解决的是：\n\n> 如果没有人每次都手动派活，队友能不能在空闲时自己找任务、自己恢复工作。\n\n也就是从“协议化协作”继续走向“自治行为”。\n"
  },
  {
    "version": "s17",
    "slug": "s17-autonomous-agents",
    "locale": "zh",
    "title": "s17: Autonomous Agents (自治智能体)",
    "kind": "chapter",
    "filename": "s17-autonomous-agents.md",
    "content": "# s17: Autonomous Agents (自治智能体)\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > [ s17 ] > s18 > s19`\n\n> *一个团队真正开始“自己运转”，不是因为 agent 数量变多，而是因为空闲的队友会自己去找下一份工作。*\n\n## 这一章要解决什么问题\n\n到了 `s16`，团队已经有：\n\n- 持久队友\n- 邮箱\n- 协议\n- 任务板\n\n但还有一个明显瓶颈：\n\n**很多事情仍然要靠 lead 手动分配。**\n\n例如任务板上已经有 10 条可做任务，如果还要 lead 一个个点名：\n\n- Alice 做 1\n- Bob 做 2\n- Charlie 做 3\n\n那团队规模一大，lead 就会变成瓶颈。\n\n所以这一章要解决的核心问题是：\n\n**让空闲队友自己扫描任务板，找到可做的任务并认领。**\n\n## 建议联读\n\n- 如果你开始把 teammate、task、runtime slot 三层一起讲糊，先回 [`team-task-lane-model.md`](./team-task-lane-model.md)。\n- 如果你读到“auto-claim”时开始疑惑“活着的执行槽位”到底放在哪，继续看 [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)。\n- 如果你开始忘记“长期队友”和“一次性 subagent”最根本的区别，回看 [`entity-map.md`](./entity-map.md)。\n\n## 先解释几个名词\n\n### 什么叫自治\n\n这里的自治，不是完全没人管。\n\n这里说的自治是：\n\n> 在提前给定规则的前提下，队友可以自己决定下一步接哪份工作。\n\n### 什么叫认领\n\n认领，就是把一条原本没人负责的任务，标记成“现在由我负责”。\n\n### 什么叫空闲阶段\n\n空闲阶段不是关机，也不是消失。\n\n它表示：\n\n> 这个队友当前手头没有活，但仍然活着，随时准备接新活。\n\n## 最小心智模型\n\n最清楚的理解方式，是把每个队友想成在两个阶段之间切换：\n\n```text\nWORK\n  |\n  | 当前轮工作做完，或者主动进入 idle\n  v\nIDLE\n  |\n  +-- 看邮箱，有新消息 -> 回到 WORK\n  |\n  +-- 看任务板，有 ready task -> 认领 -> 回到 WORK\n  |\n  +-- 长时间什么都没有 -> shutdown\n```\n\n这里的关键不是“让它永远不停想”，而是：\n\n**空闲时，按规则检查两类新输入：邮箱和任务板。**\n\n## 关键数据结构\n\n### 1. Claimable Predicate\n\n和 `s12` 一样，这里最重要的是：\n\n**什么任务算“当前这个队友可以安全认领”的任务。**\n\n在当前教学代码里，判定已经不是单纯看 `pending`，而是：\n\n```python\ndef is_claimable_task(task: dict, role: str | None = None) -> bool:\n    return (\n        task.get(\"status\") == \"pending\"\n        and not task.get(\"owner\")\n        and not task.get(\"blockedBy\")\n        and _task_allows_role(task, role)\n    )\n```\n\n这 4 个条件缺一不可：\n\n- 任务还没开始\n- 还没人认领\n- 没有前置阻塞\n- 当前队友角色满足认领策略\n\n最后一条很关键。\n\n因为现在任务可以带：\n\n- `claim_role`\n- `required_role`\n\n例如：\n\n```python\ntask = {\n    \"id\": 7,\n    \"subject\": \"Implement login page\",\n    \"status\": \"pending\",\n    \"owner\": \"\",\n    \"blockedBy\": [],\n    \"claim_role\": \"frontend\",\n}\n```\n\n这表示：\n\n> 这条任务不是“谁空着谁就拿”，而是要先过角色条件。\n\n### 2. 认领后的任务记录\n\n一旦认领成功，任务记录至少会发生这些变化：\n\n```python\n{\n    \"id\": 7,\n    \"owner\": \"alice\",\n    \"status\": \"in_progress\",\n    \"claimed_at\": 1710000000.0,\n    \"claim_source\": \"auto\",\n}\n```\n\n这里新增的两个字段很值得单独记住：\n\n- `claimed_at`：什么时候被认领\n- `claim_source`：这次认领是 `auto` 还是 `manual`\n\n因为到这一步，系统开始不只是知道“任务现在有人做了”，还开始知道：\n\n- 这是谁拿走的\n- 是主动扫描拿走，还是手动点名拿走\n\n### 3. Claim Event Log\n\n除了回写任务文件，这章还会把认领动作追加到：\n\n```text\n.tasks/claim_events.jsonl\n```\n\n每条事件大致长这样：\n\n```python\n{\n    \"event\": \"task.claimed\",\n    \"task_id\": 7,\n    \"owner\": \"alice\",\n    \"role\": \"frontend\",\n    \"source\": \"auto\",\n    \"ts\": 1710000000.0,\n}\n```\n\n为什么这层日志重要？\n\n因为它回答的是“自治系统刚刚做了什么”。\n\n只看最终任务文件，你知道的是：\n\n- 现在是谁 owner\n\n而看事件日志，你才能知道：\n\n- 它是什么时候被拿走的\n- 是谁拿走的\n- 是空闲时自动拿走，还是人工调用 `claim_task`\n\n### 4. Durable Request Record\n\n这章虽然重点是自治，但它**不能从 `s16` 退回到“协议请求只放内存里”**。\n\n所以当前代码里仍然保留了持久化请求记录：\n\n```text\n.team/requests/{request_id}.json\n```\n\n它保存的是：\n\n- shutdown request\n- plan approval request\n- 对应的状态更新\n\n这层边界很重要，因为自治队友并不是在“脱离协议系统另起炉灶”，而是：\n\n> 在已有团队协议之上，额外获得“空闲时自己找活”的能力。\n\n### 5. 身份块\n\n当上下文被压缩后，队友有时会“忘记自己是谁”。\n\n最小补法是重新注入一段身份提示：\n\n```python\nidentity = {\n    \"role\": \"user\",\n    \"content\": \"<identity>You are 'alice', role: frontend, team: default. Continue your work.</identity>\",\n}\n```\n\n当前实现里还会同时补一条很短的确认语：\n\n```python\n{\"role\": \"assistant\", \"content\": \"I am alice. Continuing.\"}\n```\n\n这样做的目的不是好看，而是为了让恢复后的下一轮继续知道：\n\n- 我是谁\n- 我的角色是什么\n- 我属于哪个团队\n\n## 最小实现\n\n### 第一步：让队友拥有 `WORK -> IDLE` 的循环\n\n```python\nwhile True:\n    run_work_phase(...)\n    should_resume = run_idle_phase(...)\n    if not should_resume:\n        break\n```\n\n### 第二步：在 IDLE 里先看邮箱\n\n```python\ndef idle_phase(name: str, messages: list) -> bool:\n    inbox = bus.read_inbox(name)\n    if inbox:\n        messages.append({\n            \"role\": \"user\",\n            \"content\": json.dumps(inbox),\n        })\n        return True\n```\n\n这一步的意思是：\n\n如果有人明确找我，那我优先处理“明确发给我的工作”。\n\n### 第三步：如果邮箱没消息，再按“当前角色”扫描可认领任务\n\n```python\n    unclaimed = scan_unclaimed_tasks(role)\n    if unclaimed:\n        task = unclaimed[0]\n        claim_result = claim_task(\n            task[\"id\"],\n            name,\n            role=role,\n            source=\"auto\",\n        )\n```\n\n这里当前代码有两个很关键的升级：\n\n- `scan_unclaimed_tasks(role)` 不是无差别扫任务，而是带着角色过滤\n- `claim_task(..., source=\"auto\")` 会把“这次是自治认领”显式写进任务与事件日志\n\n也就是说，自治不是“空闲了就乱抢一条”，而是：\n\n> 按当前队友的角色、任务状态和阻塞关系，挑出一条真正允许它接手的工作。\n\n### 第四步：认领后先补身份，再把任务提示塞回主循环\n\n```python\n        ensure_identity_context(messages, name, role, team_name)\n        messages.append({\n            \"role\": \"user\",\n            \"content\": f\"<auto-claimed>Task #{task['id']}: {task['subject']}</auto-claimed>\",\n        })\n        messages.append({\n            \"role\": \"assistant\",\n            \"content\": f\"{claim_result}. Working on it.\",\n        })\n        return True\n```\n\n这一步非常关键。\n\n因为“认领成功”本身还不等于“队友真的能顺利继续”。\n\n还必须把两件事接回上下文里：\n\n- 身份上下文\n- 新任务提示\n\n只有这样，下一轮 `WORK` 才不是无头苍蝇，而是：\n\n> 带着明确身份和明确任务恢复工作。\n\n### 第五步：长时间没事就退出\n\n```python\n    time.sleep(POLL_INTERVAL)\n    ...\n    return False\n```\n\n为什么需要这个退出路径？\n\n因为空闲队友不一定要永远占着资源。  \n教学版先做“空闲一段时间后关闭”就够了。\n\n## 为什么认领必须是原子动作\n\n“原子”这个词第一次看到可能不熟。\n\n这里它的意思是：\n\n> 认领这一步要么完整成功，要么不发生，不能一半成功一半失败。\n\n为什么？\n\n因为两个队友可能同时扫描到同一个可做任务。\n\n如果没有锁，就可能发生：\n\n- Alice 看见任务 3 没主人\n- Bob 也看见任务 3 没主人\n- 两人都把自己写成 owner\n\n所以最小教学版也应该加一个认领锁：\n\n```python\nwith claim_lock:\n    task = load(task_id)\n    if task[\"owner\"]:\n        return \"already claimed\"\n    task[\"owner\"] = name\n    task[\"status\"] = \"in_progress\"\n    save(task)\n```\n\n## 身份重注入为什么重要\n\n这是这章里一个很容易被忽视，但很关键的点。\n\n当上下文压缩发生以后，队友可能丢掉这些关键信息：\n\n- 我是谁\n- 我的角色是什么\n- 我属于哪个团队\n\n如果没有这些信息，队友后续行为很容易漂。\n\n所以一个很实用的做法是：\n\n如果发现 messages 的开头已经没有身份块，就把身份块重新插回去。\n\n这里你可以把它理解成一条恢复规则：\n\n> 任何一次从 idle 恢复、或任何一次压缩后恢复，只要身份上下文可能变薄，就先补身份，再继续工作。\n\n## 为什么 s17 不能从 s16 退回“内存协议”\n\n这是一个很容易被漏讲，但其实非常重要的点。\n\n很多人一看到“自治”，就容易只盯：\n\n- idle\n- auto-claim\n- 轮询\n\n然后忘了 `s16` 已经建立过的另一条主线：\n\n- 请求必须可追踪\n- 协议状态必须可恢复\n\n所以现在教学代码里，像：\n\n- shutdown request\n- plan approval\n\n仍然会写进：\n\n```text\n.team/requests/{request_id}.json\n```\n\n也就是说，`s17` 不是推翻 `s16`，而是在 `s16` 上继续加一条新能力：\n\n```text\n协议系统继续存在\n  +\n自治扫描与认领开始存在\n```\n\n这两条线一起存在，团队才会像一个真正的平台，而不是一堆各自乱跑的 worker。\n\n## 如何接到前面几章里\n\n这一章其实是前面几章第一次真正“串起来”的地方：\n\n- `s12` 提供任务板\n- `s15` 提供持久队友\n- `s16` 提供结构化协议\n- `s17` 则让队友在没有明确点名时，也能自己找活\n\n所以你可以把 `s17` 理解成：\n\n**从“被动协作”升级到“主动协作”。**\n\n## 自治的是“长期队友”，不是“一次性 subagent”\n\n这层边界如果不讲清，读者很容易把 `s04` 和 `s17` 混掉。\n\n`s17` 里的自治执行者，仍然是 `s15` 那种长期队友：\n\n- 有名字\n- 有角色\n- 有邮箱\n- 有 idle 阶段\n- 可以反复接活\n\n它不是那种：\n\n- 接一条子任务\n- 做完返回摘要\n- 然后立刻消失\n\n的一次性 subagent。\n\n同样地，这里认领的也是：\n\n- `s12` 里的工作图任务\n\n而不是：\n\n- `s13` 里的后台执行槽位\n\n所以这章其实是在两条已存在的主线上再往前推一步：\n\n- 长期队友\n- 工作图任务\n\n再把它们用“自治认领”连接起来。\n\n如果你开始把下面这些词混在一起：\n\n- teammate\n- protocol request\n- task\n- runtime task\n\n建议回看：\n\n- [`team-task-lane-model.md`](./team-task-lane-model.md)\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n\n## 初学者最容易犯的错\n\n### 1. 只看 `pending`，不看 `blockedBy`\n\n如果一个任务虽然是 `pending`，但前置任务还没完成，它就不应该被认领。\n\n### 2. 只看状态，不看 `claim_role` / `required_role`\n\n这会让错误的队友接走错误的任务。\n\n教学版虽然简单，但从这一章开始，已经应该明确告诉读者：\n\n- 并不是所有 ready task 都适合所有队友\n- 角色条件本身也是 claim policy 的一部分\n\n### 3. 没有认领锁\n\n这会直接导致重复抢同一条任务。\n\n### 4. 空闲阶段只轮询任务板，不看邮箱\n\n这样队友会错过别人明确发给它的消息。\n\n### 5. 认领了任务，但没有写 claim event\n\n这样最后你只能看到“任务现在被谁做”，却看不到：\n\n- 它是什么时候被拿走的\n- 是自动认领还是手动认领\n\n### 6. 队友永远不退出\n\n教学版里，长时间无事可做时退出是合理的。  \n否则读者会更难理解资源何时释放。\n\n### 7. 上下文压缩后不重注入身份\n\n这很容易让队友后面的行为越来越不像“它本来的角色”。\n\n## 教学边界\n\n这一章先只把自治主线讲清楚：\n\n**空闲检查 -> 安全认领 -> 恢复工作。**\n\n只要这条链路稳了，读者就已经真正理解了“自治”是什么。\n\n更细的 claim policy、公平调度、事件驱动唤醒、长期保活，都应该建立在这条最小自治链之后，而不是抢在前面。\n\n## 试一试\n\n```sh\ncd learn-claude-code\npython agents/s17_autonomous_agents.py\n```\n\n可以试试这些任务：\n\n1. 先建几条 ready task，再生成两个队友，观察它们是否会自动分工。\n2. 建几条被阻塞的任务，确认队友不会错误认领。\n3. 让某个队友进入 idle，再发一条消息给它，观察它是否会重新被唤醒。\n\n这一章要建立的核心心智是：\n\n**自治不是让 agent 乱跑，而是让它在清晰规则下自己接住下一份工作。**\n"
  },
  {
    "version": "s18",
    "slug": "s18-worktree-task-isolation",
    "locale": "zh",
    "title": "s18: Worktree + Task Isolation (Worktree 任务隔离)",
    "kind": "chapter",
    "filename": "s18-worktree-task-isolation.md",
    "content": "# s18: Worktree + Task Isolation (Worktree 任务隔离)\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > [ s18 ] > s19`\n\n> *任务板解决“做什么”，worktree 解决“在哪做而不互相踩到”。*\n\n## 这一章要解决什么问题\n\n到 `s17` 为止，系统已经可以：\n\n- 拆任务\n- 认领任务\n- 让多个 agent 并行推进不同工作\n\n但如果所有人都在同一个工作目录里改文件，很快就会出现这些问题：\n\n- 两个任务同时改同一个文件\n- 一个任务还没做完，另一个任务的修改已经把目录污染了\n- 想单独回看某个任务的改动范围时，很难分清\n\n也就是说，任务系统已经回答了“谁做什么”，却还没有回答：\n\n**每个任务应该在哪个独立工作空间里执行。**\n\n这就是 worktree 要解决的问题。\n\n## 建议联读\n\n- 如果你开始把 task、runtime slot、worktree lane 三层混成一个词，先看 [`team-task-lane-model.md`](./team-task-lane-model.md)。\n- 如果你想确认 worktree 记录和任务记录分别该保存哪些字段，回看 [`data-structures.md`](./data-structures.md)。\n- 如果你想从“参考仓库主干”角度确认这一章为什么必须晚于 tasks / teams，再看 [`s00e-reference-module-map.md`](./s00e-reference-module-map.md)。\n\n## 先解释几个名词\n\n### 什么是 worktree\n\n如果你熟悉 git，可以把 worktree 理解成：\n\n> 同一个仓库的另一个独立检出目录。\n\n如果你还不熟悉 git，也可以先把它理解成：\n\n> 一条属于某个任务的独立工作车道。\n\n### 什么叫隔离执行\n\n隔离执行就是：\n\n> 任务 A 在自己的目录里跑，任务 B 在自己的目录里跑，彼此默认不共享未提交改动。\n\n### 什么叫绑定\n\n绑定的意思是：\n\n> 把某个任务 ID 和某个 worktree 记录明确关联起来。\n\n## 最小心智模型\n\n最容易理解的方式，是把这一章拆成两张表：\n\n```text\n任务板\n  负责回答：做什么、谁在做、状态如何\n\nworktree 注册表\n  负责回答：在哪做、目录在哪、对应哪个任务\n```\n\n两者通过 `task_id` 连起来：\n\n```text\n.tasks/task_12.json\n  {\n    \"id\": 12,\n    \"subject\": \"Refactor auth flow\",\n    \"status\": \"in_progress\",\n    \"worktree\": \"auth-refactor\"\n  }\n\n.worktrees/index.json\n  {\n    \"worktrees\": [\n      {\n        \"name\": \"auth-refactor\",\n        \"path\": \".worktrees/auth-refactor\",\n        \"branch\": \"wt/auth-refactor\",\n        \"task_id\": 12,\n        \"status\": \"active\"\n      }\n    ]\n  }\n```\n\n看懂这两条记录，这一章的主线就已经抓住了：\n\n**任务记录工作目标，worktree 记录执行车道。**\n\n## 关键数据结构\n\n### 1. TaskRecord 不再只记录 `worktree`\n\n到当前教学代码这一步，任务记录里和车道相关的字段已经不只一个：\n\n```python\ntask = {\n    \"id\": 12,\n    \"subject\": \"Refactor auth flow\",\n    \"status\": \"in_progress\",\n    \"owner\": \"alice\",\n    \"worktree\": \"auth-refactor\",\n    \"worktree_state\": \"active\",\n    \"last_worktree\": \"auth-refactor\",\n    \"closeout\": None,\n}\n```\n\n这 4 个字段分别回答不同问题：\n\n- `worktree`：当前还绑定着哪条车道\n- `worktree_state`：这条绑定现在是 `active`、`kept`、`removed` 还是 `unbound`\n- `last_worktree`：最近一次用过哪条车道\n- `closeout`：最后一次收尾动作是什么\n\n为什么要拆这么细？\n\n因为到多 agent 并行阶段，系统已经不只需要知道“现在在哪做”，还需要知道：\n\n- 这条车道现在是不是还活着\n- 它最后是保留还是回收\n- 之后如果恢复或排查，应该看哪条历史车道\n\n### 2. WorktreeRecord 不只是路径映射\n\n```python\nworktree = {\n    \"name\": \"auth-refactor\",\n    \"path\": \".worktrees/auth-refactor\",\n    \"branch\": \"wt/auth-refactor\",\n    \"task_id\": 12,\n    \"status\": \"active\",\n    \"last_entered_at\": 1710000000.0,\n    \"last_command_at\": 1710000012.0,\n    \"last_command_preview\": \"pytest tests/auth -q\",\n    \"closeout\": None,\n}\n```\n\n这里也要特别注意：\n\nworktree 记录回答的不只是“目录在哪”，还开始回答：\n\n- 最近什么时候进入过\n- 最近跑过什么命令\n- 最后是怎么收尾的\n\n这就是为什么这章讲的是：\n\n**可观察的执行车道**\n\n而不只是“多开一个目录”。\n\n### 3. CloseoutRecord\n\n这一章在当前代码里，一个完整的收尾记录大致是：\n\n```python\ncloseout = {\n    \"action\": \"keep\",\n    \"reason\": \"Need follow-up review\",\n    \"at\": 1710000100.0,\n}\n```\n\n这层记录很重要，因为它把“结尾到底发生了什么”显式写出来，而不是靠人猜：\n\n- 是保留目录，方便继续追看\n- 还是回收目录，表示这条执行车道已经结束\n\n### 4. EventRecord\n\n```python\nevent = {\n    \"event\": \"worktree.closeout.keep\",\n    \"task_id\": 12,\n    \"worktree\": \"auth-refactor\",\n    \"reason\": \"Need follow-up review\",\n    \"ts\": 1710000100.0,\n}\n```\n\n为什么还要事件记录？\n\n因为 worktree 的生命周期经常跨很多步：\n\n- 创建\n- 进入\n- 运行命令\n- 保留\n- 删除\n- 删除失败\n\n有显式事件日志，会比只看当前状态更容易排查问题。\n\n## 最小实现\n\n### 第一步：先有任务，再有 worktree\n\n不要先开目录再回头补任务。\n\n更清楚的顺序是：\n\n1. 先创建任务\n2. 再为这个任务分配 worktree\n\n```python\ntask = tasks.create(\"Refactor auth flow\")\nworktrees.create(\"auth-refactor\", task_id=task[\"id\"])\n```\n\n### 第二步：创建 worktree 并写入注册表\n\n```python\ndef create(self, name: str, task_id: int):\n    path = self.root / \".worktrees\" / name\n    branch = f\"wt/{name}\"\n\n    run_git([\"worktree\", \"add\", \"-b\", branch, str(path), \"HEAD\"])\n\n    record = {\n        \"name\": name,\n        \"path\": str(path),\n        \"branch\": branch,\n        \"task_id\": task_id,\n        \"status\": \"active\",\n    }\n    self.index[\"worktrees\"].append(record)\n    self._save_index()\n```\n\n### 第三步：同时更新任务记录，不只是写一个 `worktree`\n\n```python\ndef bind_worktree(task_id: int, name: str):\n    task = tasks.load(task_id)\n    task[\"worktree\"] = name\n    task[\"last_worktree\"] = name\n    task[\"worktree_state\"] = \"active\"\n    if task[\"status\"] == \"pending\":\n        task[\"status\"] = \"in_progress\"\n    tasks.save(task)\n```\n\n为什么这一步很关键？\n\n因为如果只更新 worktree 注册表，不更新任务记录，系统就无法从任务板一眼看出“这个任务在哪个隔离目录里做”。\n\n### 第四步：显式进入车道，再在对应目录里执行命令\n\n当前代码里，进入和运行已经拆成两步：\n\n```python\nworktree_enter(\"auth-refactor\")\nworktree_run(\"auth-refactor\", \"pytest tests/auth -q\")\n```\n\n对应到底层，大致就是：\n\n```python\ndef enter(self, name: str):\n    self._update_entry(name, last_entered_at=time.time())\n    self.events.emit(\"worktree.enter\", ...)\n\ndef run(self, name: str, command: str):\n    subprocess.run(command, cwd=worktree_path, ...)\n```\n\n```python\nsubprocess.run(command, cwd=worktree_path, ...)\n```\n\n这一行看起来普通，但它正是隔离的核心：\n\n**同一个命令，在不同 `cwd` 里执行，影响范围就不一样。**\n\n为什么还要单独补一个 `worktree_enter`？\n\n因为教学上你要让读者看见：\n\n- “分配车道”是一回事\n- “真正进入并开始在这条车道里工作”是另一回事\n\n这层边界一清楚，后面的观察字段才有意义：\n\n- `last_entered_at`\n- `last_command_at`\n- `last_command_preview`\n\n### 第五步：收尾时显式走 `worktree_closeout`\n\n不要让收尾是隐式的。\n\n当前更清楚的教学接口不是“分散记两个命令”，而是统一成一个 closeout 动作：\n\n```python\nworktree_closeout(\n    name=\"auth-refactor\",\n    action=\"keep\",   # or \"remove\"\n    reason=\"Need follow-up review\",\n    complete_task=False,\n)\n```\n\n这样读者会更容易理解：\n\n- 收尾一定要选动作\n- 收尾可以带原因\n- 收尾会同时回写任务记录、车道记录和事件日志\n\n当然，底层仍然保留：\n\n- `worktree_keep(name)`\n- `worktree_remove(name, reason=..., complete_task=True)`\n\n但教学主线最好先把：\n\n> `keep` 和 `remove` 看成同一个 closeout 决策的两个分支\n\n这样读者心智会更顺。\n\n## 为什么 `worktree_state` 和 `status` 要分开\n\n这也是一个很容易被忽略的细点。\n\n很多初学者会想：\n\n> “任务有 `status` 了，为什么还要 `worktree_state`？”\n\n因为这两个状态根本不是一层东西：\n\n- 任务 `status` 回答：这件工作现在是 `pending`、`in_progress` 还是 `completed`\n- `worktree_state` 回答：这条执行车道现在是 `active`、`kept`、`removed` 还是 `unbound`\n\n举个最典型的例子：\n\n```text\n任务已经 completed\n  但 worktree 仍然 kept\n```\n\n这完全可能，而且很常见。  \n比如你已经做完了，但还想保留目录给 reviewer 看。\n\n所以：\n\n**任务状态和车道状态不能混成一个字段。**\n\n## 为什么 worktree 不是“只是一个 git 小技巧”\n\n很多初学者第一次看到这一章，会觉得：\n\n> “这不就是多开几个目录吗？”\n\n这句话只说对了一半。\n\n真正关键的不只是“多开目录”，而是：\n\n**把任务和执行目录做显式绑定，让并行工作有清楚的边界。**\n\n如果没有这层绑定，系统仍然不知道：\n\n- 哪个目录属于哪个任务\n- 收尾时该完成哪条任务\n- 崩溃后该恢复哪条关系\n\n## 如何接到前面章节里\n\n这章和前面几章是强耦合的：\n\n- `s12` 提供任务 ID\n- `s15-s17` 提供队友和认领机制\n- `s18` 则给这些任务提供独立执行车道\n\n把三者连起来看，会变成：\n\n```text\n任务被创建\n  ->\n队友认领任务\n  ->\n系统为任务分配 worktree\n  ->\n命令在对应目录里执行\n  ->\n任务完成时决定保留还是删除 worktree\n```\n\n这条链一旦建立，多 agent 并行工作就会清楚很多。\n\n## worktree 不是任务本身，而是任务的执行车道\n\n这句话值得单独再说一次。\n\n很多读者第一次学到这里时，会把这两个词混着用：\n\n- task\n- worktree\n\n但它们回答的其实不是同一个问题：\n\n- task：做什么\n- worktree：在哪做\n\n所以更完整、也更不容易混的表达方式是：\n\n- 工作图任务\n- worktree 执行车道\n\n如果你开始分不清：\n\n- 任务\n- 运行时任务\n- worktree\n\n建议回看：\n\n- [`team-task-lane-model.md`](./team-task-lane-model.md)\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n- [`entity-map.md`](./entity-map.md)\n\n## 初学者最容易犯的错\n\n### 1. 有 worktree 注册表，但任务记录里没有 `worktree`\n\n这样任务板就丢掉了最重要的一条执行信息。\n\n### 2. 有任务 ID，但命令仍然在主目录执行\n\n如果 `cwd` 没切过去，worktree 形同虚设。\n\n### 3. 只会 `worktree_remove`，不会解释 closeout 的含义\n\n这样读者最后只记住“删目录”这个动作，却不知道系统真正想表达的是：\n\n- 保留\n- 回收\n- 为什么这么做\n- 是否同时完结对应任务\n\n### 4. 删除 worktree 前不看未提交改动\n\n这是最危险的一类错误。\n\n教学版也应该至少先建立一个原则：\n\n**删除前先检查是否有脏改动。**\n\n### 5. 没有 `worktree_state` / `closeout` 这类显式收尾状态\n\n这样系统就会只剩下“现在目录还在不在”，而没有：\n\n- 这条车道最后怎么收尾\n- 是主动保留还是主动删除\n\n### 6. 把 worktree 当成长期垃圾堆\n\n如果从不清理，目录会越来越多，状态越来越乱。\n\n### 7. 没有事件日志\n\n一旦创建失败、删除失败或任务关系错乱，没有事件日志会很难排查。\n\n## 教学边界\n\n这章先要讲透的不是所有 worktree 运维细节，而是主干分工：\n\n- task 记录“做什么”\n- worktree 记录“在哪做”\n- enter / execute / closeout 串起这条隔离执行车道\n\n只要这条主干清楚，教学目标就已经达成。\n\n崩溃恢复、删除安全检查、全局缓存区、非 git 回退这些，都应该放在这条主干之后。\n\n## 试一试\n\n```sh\ncd learn-claude-code\npython agents/s18_worktree_task_isolation.py\n```\n\n可以试试这些任务：\n\n1. 为两个不同任务各建一个 worktree，观察任务板和注册表的对应关系。\n2. 分别在两个 worktree 里运行 `git status`，感受目录隔离。\n3. 删除一个 worktree，并确认对应任务是否被正确收尾。\n\n读完这一章，你应该能自己说清楚这句话：\n\n**任务系统管“做什么”，worktree 系统管“在哪做且互不干扰”。**\n"
  },
  {
    "version": "s19",
    "slug": "s19-mcp-plugin",
    "locale": "zh",
    "title": "s19: MCP & Plugin System (MCP 与插件系统)",
    "kind": "chapter",
    "filename": "s19-mcp-plugin.md",
    "content": "# s19: MCP & Plugin System (MCP 与插件系统)\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > [ s19 ]`\n\n> *工具不必都写死在主程序里。外部进程也可以把能力接进你的 agent。*\n\n## 这一章到底在讲什么\n\n前面所有章节里，工具基本都写在你自己的 Python 代码里。\n\n这当然是最适合教学的起点。\n\n但真实系统走到一定阶段以后，会很自然地遇到这个需求：\n\n> “能不能让外部程序也把工具接进来，而不用每次都改主程序？”\n\n这就是 MCP 要解决的问题。\n\n## 先用最简单的话解释 MCP\n\n你可以先把 MCP 理解成：\n\n**一套让 agent 和外部工具程序对话的统一协议。**\n\n在教学版里，不必一开始就背很多协议细节。  \n你只要先抓住这条主线：\n\n1. 启动一个外部工具服务进程\n2. 问它“你有哪些工具”\n3. 当模型要用它的工具时，把请求转发给它\n4. 再把结果带回 agent 主循环\n\n这已经够理解 80% 的核心机制了。\n\n## 为什么这一章放在最后\n\n因为 MCP 不是主循环的起点，而是主循环稳定之后的扩展层。\n\n如果你还没真正理解：\n\n- agent loop\n- tool call\n- permission\n- task\n- worktree\n\n那 MCP 只会看起来像又一套复杂接口。\n\n但当你已经有了前面的心智，再看 MCP，你会发现它本质上只是：\n\n**把“工具来源”从“本地硬编码”升级成“外部可插拔”。**\n\n## 建议联读\n\n- 如果你只把 MCP 理解成“远程 tools”，先看 [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)，把 tools、resources、prompts、plugin 中介层一起放回平台边界里。\n- 如果你想确认外部能力为什么仍然要回到同一条执行面，回看 [`s02b-tool-execution-runtime.md`](./s02b-tool-execution-runtime.md)。\n- 如果你开始把“query 控制平面”和“外部能力路由”完全分开理解，建议配合看 [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)。\n\n## 最小心智模型\n\n```text\nLLM\n  |\n  | asks to call a tool\n  v\nAgent tool router\n  |\n  +-- native tool  -> 本地 Python handler\n  |\n  +-- MCP tool     -> 外部 MCP server\n                        |\n                        v\n                    return result\n```\n\n## 最小系统里最重要的三件事\n\n### 1. 有一个 MCP client\n\n它负责：\n\n- 启动外部进程\n- 发送请求\n- 接收响应\n\n### 2. 有一个工具名前缀规则\n\n这是为了避免命名冲突。\n\n最常见的做法是：\n\n```text\nmcp__{server}__{tool}\n```\n\n比如：\n\n```text\nmcp__postgres__query\nmcp__browser__open_tab\n```\n\n这样一眼就知道：\n\n- 这是 MCP 工具\n- 它来自哪个 server\n- 它原始工具名是什么\n\n### 3. 有一个统一路由器\n\n路由器只做一件事：\n\n- 如果是本地工具，就交给本地 handler\n- 如果是 MCP 工具，就交给 MCP client\n\n## Plugin 又是什么\n\n如果 MCP 解决的是“外部工具怎么通信”，  \n那 plugin 解决的是“这些外部工具配置怎么被发现”。\n\n最小 plugin 可以非常简单：\n\n```text\n.claude-plugin/\n  plugin.json\n```\n\n里面写：\n\n- 插件名\n- 版本\n- 它提供哪些 MCP server\n- 每个 server 的启动命令是什么\n\n## 最小配置长什么样\n\n```json\n{\n  \"name\": \"my-db-tools\",\n  \"version\": \"1.0.0\",\n  \"mcpServers\": {\n    \"postgres\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-postgres\"]\n    }\n  }\n}\n```\n\n这个配置并不复杂。\n\n它本质上只是在告诉主程序：\n\n> “如果你想接这个 server，就用这条命令把它拉起来。”\n\n## 最小实现步骤\n\n### 第一步：写一个 `MCPClient`\n\n它至少要有三个能力：\n\n- `connect()`\n- `list_tools()`\n- `call_tool()`\n\n### 第二步：把外部工具标准化成 agent 能看懂的工具定义\n\n也就是说，把 MCP server 暴露的工具，转成 agent 工具池里的统一格式。\n\n### 第三步：加前缀\n\n这样主程序就能区分：\n\n- 本地工具\n- 外部工具\n\n### 第四步：写一个 router\n\n```python\nif tool_name.startswith(\"mcp__\"):\n    return mcp_router.call(tool_name, arguments)\nelse:\n    return native_handler(arguments)\n```\n\n### 第五步：仍然走同一条权限管道\n\n这是非常关键的一点：\n\n**MCP 工具虽然来自外部，但不能绕开 permission。**\n\n不然你等于在系统边上开了个安全后门。\n\n如果你想把这一层再收得更稳，最好再把结果也标准化回同一条总线：\n\n```python\n{\n    \"source\": \"mcp\",\n    \"server\": \"figma\",\n    \"tool\": \"inspect\",\n    \"status\": \"ok\",\n    \"preview\": \"...\",\n}\n```\n\n这表示：\n\n- 路由前要过共享权限闸门\n- 路由后不论本地还是远程，结果都要转成主循环看得懂的统一格式\n\n## 如何接到整个系统里\n\n如果你读到这里还觉得 MCP 像“外挂”，通常是因为没有把它放回整条主回路里。\n\n更完整的接法应该看成：\n\n```text\n启动时\n  ->\nPluginLoader 找到 manifest\n  ->\n得到 server 配置\n  ->\nMCP client 连接 server\n  ->\nlist_tools 并标准化名字\n  ->\n和 native tools 一起合并进同一个工具池\n\n运行时\n  ->\nLLM 产出 tool_use\n  ->\n统一权限闸门\n  ->\nnative route 或 mcp route\n  ->\n结果标准化\n  ->\ntool_result 回到同一个主循环\n```\n\n这段流程里最关键的不是“外部”两个字，而是：\n\n**进入方式不同，但进入后必须回到同一条控制面和执行面。**\n\n## Plugin、MCP Server、MCP Tool 不要混成一层\n\n这是初学者最容易在本章里打结的地方。\n\n可以直接按下面三层记：\n\n| 层级 | 它是什么 | 它负责什么 |\n|---|---|---|\n| plugin manifest | 一份配置声明 | 告诉系统要发现和启动哪些 server |\n| MCP server | 一个外部进程 / 连接对象 | 对外暴露一组能力 |\n| MCP tool | server 暴露的一项具体调用能力 | 真正被模型点名调用 |\n\n换成一句最短的话说：\n\n- plugin 负责“发现”\n- server 负责“连接”\n- tool 负责“调用”\n\n只要这三层还分得清，MCP 这章的主体心智就不会乱。\n\n## 这一章最关键的数据结构\n\n### 1. server 配置\n\n```python\n{\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"...\"],\n    \"env\": {}\n}\n```\n\n### 2. 标准化后的工具定义\n\n```python\n{\n    \"name\": \"mcp__postgres__query\",\n    \"description\": \"Run a SQL query\",\n    \"input_schema\": {...}\n}\n```\n\n### 3. client 注册表\n\n```python\nclients = {\n    \"postgres\": mcp_client_instance\n}\n```\n\n## 初学者最容易被带偏的地方\n\n### 1. 一上来讲太多协议细节\n\n这章最容易失控。\n\n因为一旦开始讲完整协议生态，很快会出现：\n\n- transports\n- auth\n- resources\n- prompts\n- streaming\n- connection recovery\n\n这些都存在，但不该挡住主线。\n\n主线只有一句话：\n\n**外部工具也能像本地工具一样接进 agent。**\n\n### 2. 把 MCP 当成一套完全不同的工具系统\n\n不是。\n\n它最终仍然应该汇入你原来的工具体系：\n\n- 一样要注册\n- 一样要出现在工具池里\n- 一样要过权限\n- 一样要返回 `tool_result`\n\n### 3. 忽略命名与路由\n\n如果没有统一前缀和统一路由，系统会很快乱掉。\n\n## 教学边界\n\n这一章正文先停在 `tools-first` 是对的。\n\n因为教学主线最需要先讲清的是：\n\n- 外部能力怎样被发现\n- 怎样被统一命名和路由\n- 怎样继续经过同一条权限与 `tool_result` 回流\n\n只要这一层已经成立，读者就已经真正理解了：\n\n**MCP / plugin 不是外挂，而是接回同一控制面的外部能力入口。**\n\ntransport、认证、resources、prompts、插件生命周期这些更大范围的内容，应该放到平台桥接资料里继续展开。\n\n## 正文先停在 tools-first，平台层再看桥接文档\n\n这一章的正文故意停在“外部工具如何接进 agent”这一层。  \n这是教学上的刻意取舍，不是缺失。\n\n如果你准备继续补平台边界，再去看：\n\n- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)\n\n那篇会把 MCP 再往上补成一张平台地图，包括：\n\n- server 配置作用域\n- transport 类型\n- 连接状态：`connected / pending / needs-auth / failed / disabled`\n- tools 之外的 `resources / prompts / elicitation`\n- auth 该放在哪一层理解\n\n这样安排的好处是：\n\n- 正文不失焦\n- 读者又不会误以为 MCP 只有一个 `list_tools + call_tool`\n\n## 这一章和全仓库的关系\n\n如果说前 18 章都在教你把系统内部搭起来，  \n那 `s19` 在教你：\n\n**如何把系统向外打开。**\n\n从这里开始，工具不再只来自你手写的 Python 文件，  \n还可以来自别的进程、别的系统、别的服务。\n\n这就是为什么它适合作为最后一章。\n\n## 学完这章后，你应该能回答\n\n- MCP 的核心到底是什么？\n- 为什么它应该放在整个学习路径的最后？\n- 为什么 MCP 工具也必须走同一条权限与路由逻辑？\n- plugin 和 MCP 分别解决什么问题？\n\n---\n\n**一句话记住：MCP 的本质，不是协议名词堆砌，而是把外部工具安全、统一地接进你的 agent。**\n"
  },
  {
    "version": null,
    "slug": "s19a-mcp-capability-layers",
    "locale": "zh",
    "title": "s19a: MCP Capability Layers (MCP 能力层地图)",
    "kind": "bridge",
    "filename": "s19a-mcp-capability-layers.md",
    "content": "# s19a: MCP Capability Layers (MCP 能力层地图)\n\n> `s19` 的主线仍然应该坚持“先做 tools-first”。  \n> 这篇桥接文档负责补上另一层心智：\n>\n> **MCP 不只是外部工具接入，它是一组能力层。**\n\n## 建议怎么联读\n\n如果你希望 MCP 这块既不学偏，也不学浅，推荐这样看：\n\n- 先看 [`s19-mcp-plugin.md`](./s19-mcp-plugin.md)，先把 tools-first 主线走通。\n- 再看 [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)，确认外部能力最后怎样接回统一工具总线。\n- 如果状态结构开始混，再对照 [`data-structures.md`](./data-structures.md)。\n- 如果概念边界开始混，再回 [`glossary.md`](./glossary.md) 和 [`entity-map.md`](./entity-map.md)。\n\n## 为什么要单独补这一篇\n\n如果你是为了教学，从 0 到 1 手搓一个类似系统，那么 `s19` 主线先只讲外部工具，这是对的。\n\n因为最容易理解的入口就是：\n\n- 连接一个外部 server\n- 拿到工具列表\n- 调用工具\n- 把结果带回 agent\n\n但如果你想把系统做到接近 95%-99% 的还原度，你迟早会遇到这些问题：\n\n- server 是用 stdio、http、sse 还是 ws 连接？\n- 为什么有些 server 是 connected，有些是 pending，有些是 needs-auth？\n- tools 之外，resources 和 prompts 是什么位置？\n- elicitation 为什么会变成一类特殊交互？\n- OAuth / XAA 这种认证流程该放在哪一层理解？\n\n这时候如果没有一张“能力层地图”，MCP 就会越学越散。\n\n## 先解释几个名词\n\n### 什么是能力层\n\n能力层，就是把一个复杂系统拆成几层职责清楚的面。\n\n这里的意思是：\n\n> 不要把所有 MCP 细节混成一团，而要知道每一层到底解决什么问题。\n\n### 什么是 transport\n\n`transport` 可以理解成“连接通道”。\n\n比如：\n\n- stdio\n- http\n- sse\n- websocket\n\n### 什么是 elicitation\n\n这个词比较生。\n\n你可以先把它理解成：\n\n> 外部 MCP server 反过来向用户请求额外输入的一种交互。\n\n也就是说，不再只是 agent 主动调工具，而是 server 也能说：\n\n“我还需要你给我一点信息，我才能继续。”\n\n## 最小心智模型\n\n先把 MCP 画成 6 层：\n\n```text\n1. Config Layer\n   server 配置长什么样\n\n2. Transport Layer\n   用什么通道连 server\n\n3. Connection State Layer\n   现在是 connected / pending / failed / needs-auth\n\n4. Capability Layer\n   tools / resources / prompts / elicitation\n\n5. Auth Layer\n   是否需要认证，认证状态如何\n\n6. Router Integration Layer\n   如何接回 tool router / permission / notifications\n```\n\n最重要的一点是：\n\n**tools 只是其中一层，不是全部。**\n\n## 为什么正文仍然应该坚持 tools-first\n\n这点非常重要。\n\n虽然 MCP 平台本身有多层能力，但正文主线仍然应该这样安排：\n\n### 第一步：先教外部 tools\n\n因为它和前面的主线最自然衔接：\n\n- 本地工具\n- 外部工具\n- 同一条 router\n\n### 第二步：再告诉读者还有其他能力层\n\n例如：\n\n- resources\n- prompts\n- elicitation\n- auth\n\n### 第三步：再决定是否继续实现\n\n这才符合你的教学目标：\n\n**先做出类似系统，再补平台层高级能力。**\n\n## 关键数据结构\n\n### 1. ScopedMcpServerConfig\n\n最小教学版建议至少让读者看到这个概念：\n\n```python\nconfig = {\n    \"name\": \"postgres\",\n    \"type\": \"stdio\",\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"...\"],\n    \"scope\": \"project\",\n}\n```\n\n这里的 `scope` 很重要。\n\n因为 server 配置不一定都来自同一个地方。\n\n### 2. MCP Connection State\n\n```python\nserver_state = {\n    \"name\": \"postgres\",\n    \"status\": \"connected\",   # pending / failed / needs-auth / disabled\n    \"config\": {...},\n}\n```\n\n### 3. MCPToolSpec\n\n```python\ntool = {\n    \"name\": \"mcp__postgres__query\",\n    \"description\": \"...\",\n    \"input_schema\": {...},\n}\n```\n\n### 4. ElicitationRequest\n\n```python\nrequest = {\n    \"server_name\": \"some-server\",\n    \"message\": \"Please provide additional input\",\n    \"requested_schema\": {...},\n}\n```\n\n这一步不是要求你主线立刻实现它，而是要让读者知道：\n\n**MCP 不一定永远只是“模型调工具”。**\n\n## 一张更完整但仍然清楚的图\n\n```text\nMCP Config\n  |\n  v\nTransport\n  |\n  v\nConnection State\n  |\n  +-- connected\n  +-- pending\n  +-- needs-auth\n  +-- failed\n  |\n  v\nCapabilities\n  +-- tools\n  +-- resources\n  +-- prompts\n  +-- elicitation\n  |\n  v\nRouter / Permission / Notification Integration\n```\n\n## Auth 为什么不要在主线里讲太多\n\n这也是教学取舍里很重要的一点。\n\n认证是真实系统里确实存在的能力层。  \n但如果正文一开始就掉进 OAuth/XAA 流程，初学者会立刻丢主线。\n\n所以更好的讲法是：\n\n- 先告诉读者：有 auth layer\n- 再告诉读者：connected / needs-auth 是不同连接状态\n- 只有做平台层进阶时，再详细展开认证流程\n\n这就既没有幻觉，也没有把人带偏。\n\n## 它和 `s19`、`s02a` 的关系\n\n- `s19` 正文继续负责 tools-first 教学\n- 这篇负责补清平台层地图\n- `s02a` 的 Tool Control Plane 则解释 MCP 最终怎么接回统一工具总线\n\n三者合在一起，读者才会真正知道：\n\n**MCP 是外部能力平台，而 tools 只是它最先进入主线的那个切面。**\n\n## 初学者最容易犯的错\n\n### 1. 把 MCP 只理解成“外部工具目录”\n\n这会让后面遇到 auth / resources / prompts / elicitation 时很困惑。\n\n### 2. 一上来就沉迷 transport 和 OAuth 细节\n\n这样会直接打断主线。\n\n### 3. 让 MCP 工具绕过 permission\n\n这会在系统边上开一个很危险的后门。\n\n### 4. 不区分 server 配置、连接状态、能力暴露\n\n这三层一混，平台层就会越学越乱。\n\n## 教学边界\n\n这篇最重要的，不是把 MCP 所有外设细节都讲完，而是先守住四层边界：\n\n- server 配置\n- 连接状态\n- capability 暴露\n- permission / routing 接入点\n\n只要这四层不混，你就已经能自己手搓一个接近真实系统主脉络的外部能力入口。  \n认证状态机、resource/prompt 接入、server 回问和重连策略，都属于后续平台扩展。\n\n## 一句话记住\n\n**`s19` 主线应该先教“外部工具接入”，而平台层还需要额外理解 MCP 的能力层地图。**\n"
  },
  {
    "version": null,
    "slug": "teaching-scope",
    "locale": "zh",
    "title": "Teaching Scope (教学范围说明)",
    "kind": "bridge",
    "filename": "teaching-scope.md",
    "content": "# Teaching Scope (教学范围说明)\n\n> 这份文档不是讲某一章，而是说明整个教学仓库到底要教什么、不教什么，以及每一章应该怎么写才不会把读者带偏。\n\n## 这份仓库的目标\n\n这不是一份“逐行对照某份源码”的注释仓库。\n\n这份仓库真正的目标是：\n\n**教开发者从 0 到 1 手搓一个结构完整、高保真的 coding agent harness。**\n\n这里强调 3 件事：\n\n1. 读者真的能自己实现出来。\n2. 读者能抓住系统主脉络，而不是淹没在边角细节里。\n3. 读者对关键机制的理解足够高保真，不会学到不存在的机制。\n\n## 什么必须讲清楚\n\n主线章节必须优先讲清下面这些内容：\n\n- 整个系统有哪些核心模块\n- 模块之间如何协作\n- 每个模块解决什么问题\n- 关键状态保存在哪里\n- 关键数据结构长什么样\n- 主循环如何把这些机制接进来\n\n如果一个章节讲完以后，读者还不知道“这个机制到底放在系统哪一层、保存了哪些状态、什么时候被调用”，那这章就还没讲透。\n\n## 什么不要占主线篇幅\n\n下面这些内容，不是完全不能提，而是**不应该占用主线正文的大量篇幅**：\n\n- 打包、编译、发布流程\n- 跨平台兼容胶水\n- 遥测、企业策略、账号体系\n- 与教学主线无关的历史兼容分支\n- 只对特定产品环境有意义的接线细节\n- 某份上游源码里的函数名、文件名、行号级对照\n\n这些内容最多作为：\n\n- 维护者备注\n- 附录\n- 桥接资料里的平台扩展说明\n\n而不应该成为初学者第一次学习时的主线。\n\n## 真正的“高保真”是什么意思\n\n教学仓库追求的高保真，不是所有边角细节都 1:1。\n\n这里的高保真，是指这些东西要尽量贴近真实系统主干：\n\n- 核心运行模式\n- 主要模块边界\n- 关键数据结构\n- 模块之间的协作方式\n- 关键状态转换\n\n换句话说：\n\n**主干尽量高保真，外围细节可以做教学取舍。**\n\n## 面向谁来写\n\n本仓库默认读者不是“已经做过复杂 agent 平台的人”。\n\n更合理的默认读者应该是：\n\n- 会一点编程\n- 能读懂基本 Python\n- 但没有系统实现过 agent\n\n所以写作时要假设：\n\n- 很多术语是第一次见\n- 很多系统设计名词不能直接甩出来不解释\n- 同一个概念不能分散在五个地方才拼得完整\n\n## 每一章的推荐结构\n\n主线章节尽量遵守这条顺序：\n\n1. `这一章要解决什么问题`\n2. `先解释几个名词`\n3. `最小心智模型`\n4. `关键数据结构`\n5. `最小实现`\n6. `如何接到主循环里`\n7. `初学者最容易犯的错`\n8. `教学边界`\n\n这条顺序的价值在于：\n\n- 先让读者知道为什么需要这个机制\n- 再让读者知道这个机制到底是什么\n- 然后马上看到它怎么落地\n\n这里把最后一节写成 `教学边界`，而不是“继续补一大串外围复杂度清单”，是因为教学仓库更应该先帮读者守住：\n\n- 这一章先学到哪里就够了\n- 哪些复杂度现在不要一起拖进来\n- 读者真正该自己手搓出来的最小正确版本是什么\n\n## 术语使用规则\n\n只要出现这些类型的词，就应该解释：\n\n- 软件设计模式\n- 数据结构名词\n- 并发与进程相关名词\n- 协议与网络相关名词\n- 初学者不熟悉的工程术语\n\n例如：\n\n- 状态机\n- 调度器\n- 队列\n- worktree\n- DAG\n- 协议 envelope\n\n不要只给名字，不给解释。\n\n## “最小正确版本”原则\n\n很多真实机制都很复杂。\n\n但教学版不应该一开始就把所有分支一起讲。\n\n更好的顺序是：\n\n1. 先给出一个最小但正确的版本\n2. 解释它已经解决了哪部分核心问题\n3. 再讲如果继续迭代应该补什么\n\n例如：\n\n- 权限系统先做 `deny -> mode -> allow -> ask`\n- 错误恢复先做 3 条主恢复路径\n- 任务系统先做任务记录、依赖、解锁\n- 团队协议先做 request/response + request_id\n\n## 文档和代码要一起维护，而不是各讲各的\n\n如果正文和本地 `agents/*.py` 没有对齐，读者一打开代码就会重新混乱。\n\n所以维护者重写章节时，应该同步检查三件事：\n\n1. 这章正文里的关键状态，代码里是否真有对应结构\n2. 这章正文里的主回路，代码里是否真有对应入口函数\n3. 这章正文里强调的“教学边界”，代码里是否也没有提前塞进过多外层复杂度\n\n最稳的做法是让每章都能对应到：\n\n- 1 个主文件\n- 1 组关键状态结构\n- 1 条最值得先看的执行路径\n\n如果维护者需要一份“按章节读本仓库代码”的地图，建议配合看：\n\n- [`s00f-code-reading-order.md`](./s00f-code-reading-order.md)\n\n## 维护者重写时的检查清单\n\n如果你在重写某一章，可以用下面这份清单自检：\n\n- 这章第一屏有没有明确说明“为什么需要它”\n- 是否先解释了新名词，再使用新名词\n- 是否给出了最小心智模型图或流程\n- 是否明确列出关键数据结构\n- 是否说明了它如何接进主循环\n- 是否区分了“核心机制”和“产品化外围细节”\n- 是否列出了初学者最容易混淆的点\n- 是否避免制造源码里并不存在的幻觉机制\n\n## 维护者如何使用“逆向源码”\n\n逆向得到的源码，在这套仓库里应当只扮演一个角色：\n\n**维护者的校准参考。**\n\n它的用途是：\n\n- 校验主干机制有没有讲错\n- 校验关键状态和模块边界有没有遗漏\n- 校验教学实现有没有偏离到错误方向\n\n它不应该成为读者理解正文的前提。\n\n正文应该做到：\n\n> 即使读者完全不看那份源码，也能把核心系统自己做出来。\n\n## 这份教学仓库应该追求什么分数\n\n如果满分是 150 分，一个接近满分的教学仓库应同时做到：\n\n- 主线清楚\n- 章节顺序合理\n- 新名词解释完整\n- 数据结构清晰\n- 机制边界准确\n- 例子可运行\n- 升级路径自然\n\n真正决定分数高低的，不是“提到了多少细节”，而是：\n\n**提到的关键细节是否真的讲透，没提的非关键细节是否真的可以安全省略。**\n"
  },
  {
    "version": null,
    "slug": "team-task-lane-model",
    "locale": "zh",
    "title": "Team Task Lane Model (队友-任务-车道模型)",
    "kind": "bridge",
    "filename": "team-task-lane-model.md",
    "content": "# Team Task Lane Model (队友-任务-车道模型)\n\n> 到了 `s15-s18`，读者最容易混掉的，不是某个函数名，而是：\n>\n> **系统里到底是谁在工作、谁在协调、谁在记录目标、谁在提供执行目录。**\n\n## 这篇桥接文档解决什么问题\n\n如果你一路从 `s15` 看到 `s18`，脑子里很容易把下面这些词混在一起：\n\n- teammate\n- protocol request\n- task\n- runtime task\n- worktree\n\n它们都和“工作推进”有关。  \n但它们不是同一层。\n\n如果这层边界不单独讲清，后面读者会经常出现这些困惑：\n\n- 队友是不是任务本身？\n- `request_id` 和 `task_id` 有什么区别？\n- worktree 是不是后台任务的一种？\n- 一个任务完成了，为什么 worktree 还能保留？\n\n这篇就是专门用来把这几层拆开的。\n\n## 建议怎么联读\n\n最推荐的读法是：\n\n1. 先看 [`s15-agent-teams.md`](./s15-agent-teams.md)，确认长期队友在讲什么。\n2. 再看 [`s16-team-protocols.md`](./s16-team-protocols.md)，确认请求-响应协议在讲什么。\n3. 再看 [`s17-autonomous-agents.md`](./s17-autonomous-agents.md)，确认自治认领在讲什么。\n4. 最后看 [`s18-worktree-task-isolation.md`](./s18-worktree-task-isolation.md)，确认隔离执行车道在讲什么。\n\n如果你开始混：\n\n- 回 [`entity-map.md`](./entity-map.md) 看模块边界。\n- 回 [`data-structures.md`](./data-structures.md) 看记录结构。\n- 回 [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) 看“目标任务”和“运行时执行槽位”的差别。\n\n## 先给结论\n\n先记住这一组最重要的区分：\n\n```text\nteammate\n  = 谁在长期参与协作\n\nprotocol request\n  = 团队内部一次需要被追踪的协调请求\n\ntask\n  = 要做什么\n\nruntime task / execution slot\n  = 现在有什么执行单元正在跑\n\nworktree\n  = 在哪做，而且不和别人互相踩目录\n```\n\n这五层里，最容易混的是最后三层：\n\n- `task`\n- `runtime task`\n- `worktree`\n\n所以你必须反复问自己：\n\n- 这是“目标”吗？\n- 这是“执行中的东西”吗？\n- 这是“执行目录”吗？\n\n## 一张最小清晰图\n\n```text\nTeam Layer\n  teammate: alice (frontend)\n  teammate: bob (backend)\n\nProtocol Layer\n  request_id=req_01\n  kind=plan_approval\n  status=pending\n\nWork Graph Layer\n  task_id=12\n  subject=\"Implement login page\"\n  owner=\"alice\"\n  status=\"in_progress\"\n\nRuntime Layer\n  runtime_id=rt_01\n  type=in_process_teammate\n  status=running\n\nExecution Lane Layer\n  worktree=login-page\n  path=.worktrees/login-page\n  status=active\n```\n\n你可以看到：\n\n- `alice` 不是任务\n- `request_id` 不是任务\n- `runtime_id` 也不是任务\n- `worktree` 更不是任务\n\n真正表达“这件工作本身”的，只有 `task_id=12` 那层。\n\n## 1. Teammate：谁在长期协作\n\n这是 `s15` 开始建立的层。\n\n它回答的是：\n\n- 这个长期 worker 叫什么\n- 它是什么角色\n- 它当前是 working、idle 还是 shutdown\n- 它有没有独立 inbox\n\n最小例子：\n\n```python\nmember = {\n    \"name\": \"alice\",\n    \"role\": \"frontend\",\n    \"status\": \"idle\",\n}\n```\n\n这层的核心不是“又多开一个 agent”。\n\n而是：\n\n> 系统开始有长期存在、可重复接活、可被点名协作的身份。\n\n## 2. Protocol Request：谁在协调什么\n\n这是 `s16` 建立的层。\n\n它回答的是：\n\n- 有谁向谁发起了一个需要追踪的请求\n- 这条请求是什么类型\n- 它现在是 pending、approved 还是 rejected\n\n最小例子：\n\n```python\nrequest = {\n    \"request_id\": \"a1b2c3d4\",\n    \"kind\": \"plan_approval\",\n    \"from\": \"alice\",\n    \"to\": \"lead\",\n    \"status\": \"pending\",\n}\n```\n\n这一层不要和普通聊天混。\n\n因为它不是“发一条消息就算完”，而是：\n\n> 一条可以被继续更新、继续审核、继续恢复的协调记录。\n\n## 3. Task：要做什么\n\n这是 `s12` 的工作图任务，也是 `s17` 自治认领的对象。\n\n它回答的是：\n\n- 目标是什么\n- 谁负责\n- 是否有阻塞\n- 当前进度如何\n\n最小例子：\n\n```python\ntask = {\n    \"id\": 12,\n    \"subject\": \"Implement login page\",\n    \"status\": \"in_progress\",\n    \"owner\": \"alice\",\n    \"blockedBy\": [],\n}\n```\n\n这层的关键词是：\n\n**目标**\n\n不是目录，不是协议，不是进程。\n\n## 4. Runtime Task / Execution Slot：现在有什么执行单元在跑\n\n这一层在 `s13` 的桥接文档里已经单独解释过，但到了 `s15-s18` 必须再提醒一次。\n\n比如：\n\n- 一个后台 shell 正在跑\n- 一个长期 teammate 正在工作\n- 一个 monitor 正在观察外部状态\n\n这些都更像：\n\n> 正在运行的执行槽位\n\n而不是“任务目标本身”。\n\n最小例子：\n\n```python\nruntime = {\n    \"id\": \"rt_01\",\n    \"type\": \"in_process_teammate\",\n    \"status\": \"running\",\n    \"work_graph_task_id\": 12,\n}\n```\n\n这里最重要的边界是：\n\n- 一个任务可以派生多个 runtime task\n- 一个 runtime task 通常只是“如何执行”的一个实例\n\n## 5. Worktree：在哪做\n\n这是 `s18` 建立的执行车道层。\n\n它回答的是：\n\n- 这份工作在哪个独立目录里做\n- 这条目录车道对应哪个任务\n- 这条车道现在是 active、kept 还是 removed\n\n最小例子：\n\n```python\nworktree = {\n    \"name\": \"login-page\",\n    \"path\": \".worktrees/login-page\",\n    \"task_id\": 12,\n    \"status\": \"active\",\n}\n```\n\n这层的关键词是：\n\n**执行边界**\n\n它不是工作目标本身，而是：\n\n> 让这份工作在独立目录里推进的执行车道。\n\n## 这五层怎么连起来\n\n你可以把后段章节连成下面这条链：\n\n```text\nteammate\n  通过 protocol request 协调\n  认领 task\n  作为一个 runtime execution slot 持续运行\n  在某条 worktree lane 里改代码\n```\n\n如果写得更具体一点，会变成：\n\n```text\nalice (teammate)\n  ->\n收到或发起一个 request_id\n  ->\n认领 task #12\n  ->\n开始作为执行单元推进工作\n  ->\n进入 worktree \"login-page\"\n  ->\n在 .worktrees/login-page 里运行命令和改文件\n```\n\n## 一个最典型的混淆例子\n\n很多读者会把这句话说成：\n\n> “alice 就是在做 login-page 这个 worktree 任务。”\n\n这句话把三层东西混成了一句：\n\n- `alice`：队友\n- `login-page`：worktree\n- “任务”：工作图任务\n\n更准确的说法应该是：\n\n> `alice` 认领了 `task #12`，并在 `login-page` 这条 worktree 车道里推进它。\n\n一旦你能稳定地这样表述，后面几章就不容易乱。\n\n## 初学者最容易犯的错\n\n### 1. 把 teammate 和 task 混成一个对象\n\n队友是执行者，任务是目标。\n\n### 2. 把 `request_id` 和 `task_id` 混成一个 ID\n\n一个负责协调，一个负责工作目标，不是同一层。\n\n### 3. 把 runtime slot 当成 durable task\n\n运行时执行单元会结束，但 durable task 还可能继续存在。\n\n### 4. 把 worktree 当成任务本身\n\nworktree 只是执行目录边界，不是任务目标。\n\n### 5. 只会讲“系统能并行”，却说不清每层对象各自负责什么\n\n这是最常见也最危险的模糊表达。\n\n真正清楚的教学，不是说“这里好多 agent 很厉害”，而是能把下面这句话讲稳：\n\n> 队友负责长期协作，请求负责协调流程，任务负责表达目标，运行时槽位负责承载执行，worktree 负责隔离执行目录。\n\n## 读完这篇你应该能自己说清楚\n\n至少能完整说出下面这两句话：\n\n1. `s17` 的自治认领，认领的是 `s12` 的工作图任务，不是 `s13` 的运行时槽位。\n2. `s18` 的 worktree，绑定的是任务的执行车道，而不是把任务本身变成目录。\n\n如果这两句你已经能稳定说清，`s15-s18` 这一大段主线就基本不会再拧巴了。\n"
  },
  {
    "version": null,
    "slug": "data-structures",
    "locale": "ja",
    "title": "Core Data Structures (主要データ構造マップ)",
    "kind": "bridge",
    "filename": "data-structures.md",
    "content": "# Core Data Structures (主要データ構造マップ)\n\n> agent 学習でいちばん迷いやすいのは、機能の多さそのものではなく、  \n> **「今の状態がどの record に入っているのか」が見えなくなること**です。  \n> この文書は、主線章と bridge doc に繰り返し出てくる record をひとつの地図として並べ直し、  \n> 読者が system 全体を「機能一覧」ではなく「状態の配置図」として理解できるようにするための資料です。\n\n## どう使うか\n\nこの資料は辞書というより、`state map` として使ってください。\n\n- 単語の意味が怪しくなったら [`glossary.md`](./glossary.md) へ戻る\n- object 同士の境界が混ざったら [`entity-map.md`](./entity-map.md) を開く\n- `TaskRecord` と `RuntimeTaskState` が混ざったら [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) を読む\n- MCP で tools 以外の layer が混ざったら [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md) を併読する\n\n## 最初にこの 2 本だけは覚える\n\n### 原則 1: 内容状態と制御状態を分ける\n\n内容状態とは、system が「何を扱っているか」を表す状態です。\n\n例:\n\n- `messages`\n- `tool_result`\n- memory の本文\n- task の title や description\n\n制御状態とは、system が「次にどう進むか」を表す状態です。\n\n例:\n\n- `turn_count`\n- `transition`\n- `has_attempted_compact`\n- `max_output_tokens_override`\n- `pending_classifier_check`\n\nこの 2 つを混ぜると、読者はすぐに次の疑問で詰まります。\n\n- なぜ `messages` だけでは足りないのか\n- なぜ control plane が必要なのか\n- なぜ recovery や compact が別 state を持つのか\n\n### 原則 2: durable state と runtime state を分ける\n\n`durable state` は、session をまたいでも残す価値がある状態です。\n\n例:\n\n- task\n- memory\n- schedule\n- team roster\n\n`runtime state` は、system が動いている間だけ意味を持つ状態です。\n\n例:\n\n- 現在の permission decision\n- 今走っている runtime task\n- active MCP connection\n- 今回の query の continuation reason\n\nこの区別が曖昧だと、task・runtime slot・notification・schedule・worktree が全部同じ層に見えてしまいます。\n\n## 1. Query と会話制御の状態\n\nこの層の核心は:\n\n> 会話内容を持つ record と、query の進行理由を持つ record は別物である\n\nです。\n\n### `Message`\n\n役割:\n\n- user と assistant の会話履歴を持つ\n- tool 呼び出し前後の往復も保存する\n\n最小形:\n\n```python\nmessage = {\n    \"role\": \"user\" | \"assistant\",\n    \"content\": \"...\",\n}\n```\n\nagent が tool を使い始めると、`content` は単なる文字列では足りなくなり、次のような block list になることがあります。\n\n- text block\n- `tool_use`\n- `tool_result`\n\nこの record の本質は、**会話内容の記録**です。  \n「なぜ次ターンへ進んだか」は `Message` の責務ではありません。\n\n関連章:\n\n- `s01`\n- `s02`\n- `s06`\n- `s10`\n\n### `NormalizedMessage`\n\n役割:\n\n- さまざまな内部 message を、model API に渡せる統一形式へ揃える\n\n最小形:\n\n```python\nmessage = {\n    \"role\": \"user\" | \"assistant\",\n    \"content\": [\n        {\"type\": \"text\", \"text\": \"...\"},\n    ],\n}\n```\n\n`Message` と `NormalizedMessage` の違い:\n\n- `Message`: system 内部の履歴 record に近い\n- `NormalizedMessage`: model 呼び出し直前の入力形式に近い\n\nつまり、前者は「何を覚えているか」、後者は「何を送るか」です。\n\n関連章:\n\n- `s10`\n- [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md)\n\n### `CompactSummary`\n\n役割:\n\n- context が長くなり過ぎたとき、古い会話を要約へ置き換える\n\n最小形:\n\n```python\nsummary = {\n    \"task_overview\": \"...\",\n    \"current_state\": \"...\",\n    \"key_decisions\": [\"...\"],\n    \"next_steps\": [\"...\"],\n}\n```\n\n重要なのは、compact が「ログ削除」ではないことです。  \ncompact summary は次の query 継続に必要な最小構造を残す record です。\n\n最低でも次の 4 つは落とさないようにします。\n\n- task の大枠\n- ここまで終わったこと\n- 重要な判断\n- 次にやるべきこと\n\n関連章:\n\n- `s06`\n- `s11`\n\n### `SystemPromptBlock`\n\n役割:\n\n- system prompt を section 単位で管理する\n\n最小形:\n\n```python\nblock = {\n    \"text\": \"...\",\n    \"cache_scope\": None,\n}\n```\n\nこの record を持つ意味:\n\n- prompt を一枚岩の巨大文字列にしない\n- どの section が何の役割か説明できる\n- 後から block 単位で差し替えや検査ができる\n\n`cache_scope` は最初は不要でも構いません。  \nただ、「この block は比較的安定」「この block は毎ターン変わる」という発想は早めに持っておくと、system prompt の理解が崩れにくくなります。\n\n関連章:\n\n- `s10`\n- [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md)\n\n### `PromptParts`\n\n役割:\n\n- system prompt を最終連結する前に、構成 source ごとに分けて持つ\n\n最小形:\n\n```python\nparts = {\n    \"core\": \"...\",\n    \"tools\": \"...\",\n    \"skills\": \"...\",\n    \"memory\": \"...\",\n    \"dynamic\": \"...\",\n}\n```\n\nこの record は、読者に次のことを教えます。\n\n- prompt は「書かれている」のではなく「組み立てられている」\n- stable policy と volatile runtime data は同じ section ではない\n- input source ごとに責務を分けた方が debug しやすい\n\n関連章:\n\n- `s10`\n\n### `QueryParams`\n\n役割:\n\n- query 開始時点で外部から受け取る入口入力\n\n最小形:\n\n```python\nparams = {\n    \"messages\": [...],\n    \"system_prompt\": \"...\",\n    \"user_context\": {...},\n    \"system_context\": {...},\n    \"tool_use_context\": {...},\n    \"fallback_model\": None,\n    \"max_output_tokens_override\": None,\n    \"max_turns\": None,\n}\n```\n\nここで大切なのは:\n\n- これは query の**入口入力**である\n- query の途中でどんどん変わる内部状態とは別である\n\nつまり `QueryParams` は「入る前に決まっているもの」、`QueryState` は「入ってから変わるもの」です。\n\n関連章:\n\n- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)\n\n### `QueryState`\n\n役割:\n\n- 1 本の query が複数ターンにわたって進む間の制御状態を持つ\n\n最小形:\n\n```python\nstate = {\n    \"messages\": [...],\n    \"tool_use_context\": {...},\n    \"turn_count\": 1,\n    \"max_output_tokens_recovery_count\": 0,\n    \"has_attempted_reactive_compact\": False,\n    \"max_output_tokens_override\": None,\n    \"pending_tool_use_summary\": None,\n    \"stop_hook_active\": False,\n    \"transition\": None,\n}\n```\n\nこの record に入るものの共通点:\n\n- 対話内容そのものではない\n- 「次をどう続けるか」を決める情報である\n\n初心者がよく詰まる点:\n\n- `messages` が入っているので「全部 conversation state に見える」\n- しかし `turn_count` や `transition` は会話ではなく control state\n\nこの record を理解できると、\n\n- recovery\n- compact\n- hook continuation\n- token budget continuation\n\nがすべて「同じ query を継続する理由の差分」として読めるようになります。\n\n関連章:\n\n- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)\n- `s11`\n\n### `TransitionReason`\n\n役割:\n\n- 前ターンが終わらず、次ターンへ続いた理由を明示する\n\n最小形:\n\n```python\ntransition = {\n    \"reason\": \"next_turn\",\n}\n```\n\nより実用的には次のような値が入ります。\n\n- `next_turn`\n- `tool_result_continuation`\n- `reactive_compact_retry`\n- `max_output_tokens_recovery`\n- `stop_hook_continuation`\n\nこれを別 record として持つ利点:\n\n- log が読みやすい\n- test が書きやすい\n- recovery の分岐理由を説明しやすい\n\nつまりこれは「高度な最適化」ではなく、  \n**継続理由を見える状態へ変えるための最小構造**です。\n\n関連章:\n\n- [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)\n- `s11`\n\n## 2. Tool 実行・権限・hook の状態\n\nこの層の核心は:\n\n> tool は `name -> handler` だけで完結せず、その前後に permission / runtime / hook の状態が存在する\n\nです。\n\n### `ToolSpec`\n\n役割:\n\n- model に「どんな tool があり、どんな入力を受け取るか」を見せる\n\n最小形:\n\n```python\ntool = {\n    \"name\": \"read_file\",\n    \"description\": \"Read file contents.\",\n    \"input_schema\": {...},\n}\n```\n\nこれは execution 実装そのものではありません。  \nあくまで **model に見せる contract** です。\n\n関連章:\n\n- `s02`\n- `s19`\n\n### `ToolDispatchMap`\n\n役割:\n\n- tool 名を実際の handler 関数へ引く\n\n最小形:\n\n```python\ndispatch = {\n    \"read_file\": run_read_file,\n    \"write_file\": run_write_file,\n}\n```\n\nこの record の仕事は単純です。\n\n- 正しい handler を見つける\n\nただし実システムではこれだけで足りません。  \n本当に難しいのは:\n\n- いつ実行するか\n- 並列にしてよいか\n- permission を通すか\n- 結果をどう loop へ戻すか\n\nです。\n\n関連章:\n\n- `s02`\n- [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)\n\n### `ToolUseContext`\n\n役割:\n\n- tool が共有状態へ触るための窓口を持つ\n\n最小形:\n\n```python\ncontext = {\n    \"workspace\": \"...\",\n    \"permission_system\": perms,\n    \"notifications\": queue,\n    \"memory_store\": memory,\n}\n```\n\nこの record がないと、各 tool が勝手に global state を触り始め、system 全体の境界が崩れます。\n\nつまり `ToolUseContext` は、\n\n> tool が system とどこで接続するか\n\nを見える形にするための record です。\n\n関連章:\n\n- `s02`\n- `s07`\n- `s09`\n- `s13`\n\n### `ToolResultEnvelope`\n\n役割:\n\n- tool 実行結果を loop が扱える統一形式で包む\n\n最小形:\n\n```python\nresult = {\n    \"tool_use_id\": \"toolu_123\",\n    \"content\": \"...\",\n}\n```\n\n大切なのは、tool 結果が「ただの文字列」ではないことです。  \n最低でも:\n\n- どの tool call に対する結果か\n- loop にどう書き戻すか\n\nを持たせる必要があります。\n\n関連章:\n\n- `s02`\n\n### `PermissionRule`\n\n役割:\n\n- 特定 tool / path / content に対する allow / deny / ask 条件を表す\n\n最小形:\n\n```python\nrule = {\n    \"tool\": \"bash\",\n    \"behavior\": \"deny\",\n    \"path\": None,\n    \"content\": \"sudo *\",\n}\n```\n\nこの record があることで、permission system は次を言えるようになります。\n\n- どの tool に対する rule か\n- 何にマッチしたら発火するか\n- 発火後に何を返すか\n\n関連章:\n\n- `s07`\n\n### `PermissionDecision`\n\n役割:\n\n- 今回の tool 実行に対する permission 結果を表す\n\n最小形:\n\n```python\ndecision = {\n    \"behavior\": \"allow\" | \"deny\" | \"ask\",\n    \"reason\": \"...\",\n}\n```\n\nこれを独立 record にする意味:\n\n- deny 理由を model が見える\n- ask を loop に戻して次アクションを組み立てられる\n- log や UI にも同じ object を流せる\n\n関連章:\n\n- `s07`\n\n### `HookEvent`\n\n役割:\n\n- pre_tool / post_tool / on_error などの lifecycle event を統一形で渡す\n\n最小形:\n\n```python\nevent = {\n    \"kind\": \"post_tool\",\n    \"tool_name\": \"edit_file\",\n    \"input\": {...},\n    \"result\": \"...\",\n    \"error\": None,\n    \"duration_ms\": 42,\n}\n```\n\nhook が安定して増やせるかどうかは、この record の形が揃っているかに大きく依存します。\n\nもし毎回適当な文字列だけを hook に渡すと:\n\n- audit hook\n- metrics hook\n- policy hook\n\nのたびに payload 形式がばらけます。\n\n関連章:\n\n- `s08`\n\n### `ToolExecutionBatch`\n\n役割:\n\n- 同じ execution lane でまとめて調度してよい tool block の束を表す\n\n最小形:\n\n```python\nbatch = {\n    \"is_concurrency_safe\": True,\n    \"blocks\": [tool_use_1, tool_use_2],\n}\n```\n\nこの record を導入すると、読者は:\n\n- tool を常に 1 個ずつ実行する必要はない\n- ただし何でも並列にしてよいわけでもない\n\nという 2 本の境界を同時に理解しやすくなります。\n\n関連章:\n\n- [`s02b-tool-execution-runtime.md`](./s02b-tool-execution-runtime.md)\n\n### `TrackedTool`\n\n役割:\n\n- 各 tool の lifecycle を個別に追う\n\n最小形:\n\n```python\ntracked = {\n    \"id\": \"toolu_01\",\n    \"name\": \"read_file\",\n    \"status\": \"queued\",\n    \"is_concurrency_safe\": True,\n    \"pending_progress\": [],\n    \"results\": [],\n    \"context_modifiers\": [],\n}\n```\n\nこれがあると runtime は次のことを説明できます。\n\n- 何が待機中か\n- 何が実行中か\n- 何が progress を出したか\n- 何が完了したか\n\n関連章:\n\n- [`s02b-tool-execution-runtime.md`](./s02b-tool-execution-runtime.md)\n\n### `queued_context_modifiers`\n\n役割:\n\n- 並列 tool が生んだ共有 state 変更を、先に queue し、後で安定順に merge する\n\n最小形:\n\n```python\nqueued = {\n    \"toolu_01\": [modifier_a],\n    \"toolu_02\": [modifier_b],\n}\n```\n\nここで守りたい境界:\n\n- 並列実行してよい\n- しかし共有 state を完了順でそのまま書き換えてよいとは限らない\n\nこの record は、parallel execution と stable merge を切り分けるための最小構造です。\n\n関連章:\n\n- [`s02b-tool-execution-runtime.md`](./s02b-tool-execution-runtime.md)\n\n## 3. Skill・memory・prompt source の状態\n\nこの層の核心は:\n\n> model input の材料は、その場でひとつの文字列に溶けているのではなく、複数の source record として存在する\n\nです。\n\n### `SkillRegistry`\n\n役割:\n\n- 利用可能な skill の索引を持つ\n\n最小形:\n\n```python\nregistry = [\n    {\"name\": \"agent-browser\", \"path\": \"...\", \"description\": \"...\"},\n]\n```\n\nこれは「何があるか」を示す record であり、skill 本文そのものではありません。\n\n関連章:\n\n- `s05`\n\n### `SkillContent`\n\n役割:\n\n- 実際に読み込んだ skill の本文や補助資料を持つ\n\n最小形:\n\n```python\nskill = {\n    \"name\": \"agent-browser\",\n    \"body\": \"...markdown...\",\n}\n```\n\n`SkillRegistry` と `SkillContent` を分ける理由:\n\n- registry は discovery 用\n- content は injection 用\n\nつまり「見つける record」と「使う record」を分けるためです。\n\n関連章:\n\n- `s05`\n\n### `MemoryEntry`\n\n役割:\n\n- 長期に残すべき事実を 1 件ずつ持つ\n\n最小形:\n\n```python\nentry = {\n    \"key\": \"package_manager_preference\",\n    \"value\": \"pnpm\",\n    \"scope\": \"user\",\n    \"reason\": \"user explicit preference\",\n}\n```\n\nmemory の重要境界:\n\n- 会話全文を残す record ではない\n- durable fact を残す record である\n\n関連章:\n\n- `s09`\n\n### `MemoryWriteCandidate`\n\n役割:\n\n- 今回のターンから「long-term memory に昇格させる候補」を一時的に保持する\n\n最小形:\n\n```python\ncandidate = {\n    \"fact\": \"Use pnpm by default\",\n    \"scope\": \"user\",\n    \"confidence\": \"high\",\n}\n```\n\n教学 repo では必須ではありません。  \nただし reader が「memory はいつ書くのか」で混乱しやすい場合、この record を挟むと\n\n- その場の conversation detail\n- durable fact candidate\n- 実際に保存された memory\n\nの 3 層を分けやすくなります。\n\n関連章:\n\n- `s09`\n\n## 4. Todo・task・runtime・team の状態\n\nこの層が一番混ざりやすいです。  \n理由は、全部が「仕事っぽい object」に見えるからです。\n\n### `TodoItem`\n\n役割:\n\n- 今の session 内での短期的な進行メモ\n\n最小形:\n\n```python\ntodo = {\n    \"content\": \"Inspect auth tests\",\n    \"status\": \"pending\",\n}\n```\n\nこれは durable work graph ではありません。  \n今ターンの認知負荷を軽くするための session-local 補助構造です。\n\n関連章:\n\n- `s03`\n\n### `PlanState`\n\n役割:\n\n- 複数の `TodoItem` と current focus をまとめる\n\n最小形:\n\n```python\nplan = {\n    \"todos\": [...],\n    \"current_focus\": \"Inspect auth tests\",\n}\n```\n\nこれも基本は session-local です。  \n`TaskRecord` と違って、再起動しても必ず復元したい durable board とは限りません。\n\n関連章:\n\n- `s03`\n\n### `TaskRecord`\n\n役割:\n\n- durable work goal を表す\n\n最小形:\n\n```python\ntask = {\n    \"id\": \"task-auth-migrate\",\n    \"title\": \"Migrate auth layer\",\n    \"status\": \"pending\",\n    \"dependencies\": [],\n}\n```\n\nこの record が持つべき心智:\n\n- 何を達成したいか\n- 依存関係は何か\n- 今どの状態か\n\nここで大切なのは、**task は goal node であって、今まさに走っている process ではない**ことです。\n\n関連章:\n\n- `s12`\n\n### `RuntimeTaskState`\n\n役割:\n\n- いま動いている 1 回の execution slot を表す\n\n最小形:\n\n```python\nruntime_task = {\n    \"id\": \"rt_42\",\n    \"task_id\": \"task-auth-migrate\",\n    \"status\": \"running\",\n    \"preview\": \"...\",\n    \"output_file\": \".runtime-tasks/rt_42.log\",\n}\n```\n\n`TaskRecord` との違い:\n\n- `TaskRecord`: 何を達成するか\n- `RuntimeTaskState`: その goal に向かう今回の実行は今どうなっているか\n\n関連章:\n\n- `s13`\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n\n### `NotificationRecord`\n\n役割:\n\n- background 実行や外部 capability から main loop へ戻る preview を持つ\n\n最小形:\n\n```python\nnote = {\n    \"source\": \"runtime_task\",\n    \"task_id\": \"rt_42\",\n    \"preview\": \"3 tests failing...\",\n}\n```\n\nこの record は全文ログの保存先ではありません。  \n役割は:\n\n- main loop に「戻ってきた事実」を知らせる\n- prompt space を全文ログで埋めない\n\nことです。\n\n関連章:\n\n- `s13`\n\n### `ScheduleRecord`\n\n役割:\n\n- いつ何を trigger するかを表す\n\n最小形:\n\n```python\nschedule = {\n    \"name\": \"nightly-health-check\",\n    \"cron\": \"0 2 * * *\",\n    \"task_template\": \"repo_health_check\",\n}\n```\n\n重要な境界:\n\n- `ScheduleRecord` は時間規則\n- `TaskRecord` は work goal\n- `RuntimeTaskState` は live execution\n\nこの 3 つを一緒にしないことが `s14` の核心です。\n\n関連章:\n\n- `s14`\n\n### `TeamMember`\n\n役割:\n\n- 長期に存在する teammate の身元を表す\n\n最小形:\n\n```python\nmember = {\n    \"name\": \"alice\",\n    \"role\": \"test-specialist\",\n    \"status\": \"working\",\n}\n```\n\n`TeamMember` は task ではありません。  \n「誰が長く system 内に存在しているか」を表す actor record です。\n\n関連章:\n\n- `s15`\n\n### `TeamConfig`\n\n役割:\n\n- team roster 全体をまとめる\n\n最小形:\n\n```python\nconfig = {\n    \"team_name\": \"default\",\n    \"members\": [member1, member2],\n}\n```\n\nこの record を durable に持つことで、\n\n- team に誰がいるか\n- 役割が何か\n- 次回起動時に何を復元するか\n\nが見えるようになります。\n\n関連章:\n\n- `s15`\n\n### `MessageEnvelope`\n\n役割:\n\n- teammate 間の message を、本文とメタ情報込みで包む\n\n最小形:\n\n```python\nenvelope = {\n    \"type\": \"message\",\n    \"from\": \"lead\",\n    \"to\": \"alice\",\n    \"content\": \"Review retry tests\",\n    \"timestamp\": 1710000000.0,\n}\n```\n\n`envelope` を使う理由:\n\n- 誰から誰へ送ったか分かる\n- 普通の会話と protocol request を区別しやすい\n- mailbox を durable channel として扱える\n\n関連章:\n\n- `s15`\n- `s16`\n\n### `RequestRecord`\n\n役割:\n\n- approval や shutdown のような構造化 protocol state を持つ\n\n最小形:\n\n```python\nrequest = {\n    \"request_id\": \"req_91\",\n    \"kind\": \"plan_approval\",\n    \"status\": \"pending\",\n    \"payload\": {...},\n}\n```\n\nこれを別 record にすることで、\n\n- ただの chat message\n- 追跡可能な coordination request\n\nを明確に分けられます。\n\n関連章:\n\n- `s16`\n\n### `ClaimPolicy`\n\n役割:\n\n- autonomous worker が何を self-claim してよいかを表す\n\n最小形:\n\n```python\npolicy = {\n    \"role\": \"test-specialist\",\n    \"may_claim\": [\"retry-related\"],\n}\n```\n\nこの record がないと autonomy は「空いている worker が勝手に全部取りに行く」設計になりやすく、  \nrace condition と重複実行を呼び込みます。\n\n関連章:\n\n- `s17`\n\n### `WorktreeRecord`\n\n役割:\n\n- isolated execution lane を表す\n\n最小形:\n\n```python\nworktree = {\n    \"path\": \".worktrees/wt-auth-migrate\",\n    \"task_id\": \"task-auth-migrate\",\n    \"status\": \"active\",\n}\n```\n\nこの record の核心:\n\n- task は goal\n- runtime slot は live execution\n- worktree は「どこで走るか」の lane\n\n関連章:\n\n- `s18`\n\n## 5. MCP・plugin・外部 capability の状態\n\nこの層の核心は:\n\n> 外部 capability も「ただの tool list」ではなく、接続状態と routing を持つ platform object である\n\nです。\n\n### `MCPServerConfig`\n\n役割:\n\n- 外部 server の設定を表す\n\n最小形:\n\n```python\nconfig = {\n    \"name\": \"figma\",\n    \"transport\": \"stdio\",\n    \"command\": \"...\",\n}\n```\n\nこれは capability そのものではなく、接続の入口設定です。\n\n関連章:\n\n- `s19`\n\n### `ConnectionState`\n\n役割:\n\n- remote capability の現在状態を表す\n\n最小形:\n\n```python\nstate = {\n    \"status\": \"connected\",\n    \"needs_auth\": False,\n    \"last_error\": None,\n}\n```\n\nこの record が必要な理由:\n\n- 外部 capability は常に使えるとは限らない\n- 問題が tool schema なのか connection なのか区別する必要がある\n\n関連章:\n\n- `s19`\n- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md)\n\n### `CapabilityRoute`\n\n役割:\n\n- native tool / plugin / MCP server のどこへ解決されたかを表す\n\n最小形:\n\n```python\nroute = {\n    \"source\": \"mcp\",\n    \"target\": \"figma.inspect\",\n}\n```\n\nこの record があると、\n\n- 発見\n- routing\n- permission\n- 実行\n- result normalization\n\nが同じ capability bus 上で説明できます。\n\n関連章:\n\n- `s19`\n\n## 最後に、特に混同しやすい組み合わせ\n\n### `TodoItem` vs `TaskRecord`\n\n- `TodoItem`: 今 session で何を見るか\n- `TaskRecord`: durable work goal と dependency をどう持つか\n\n### `TaskRecord` vs `RuntimeTaskState`\n\n- `TaskRecord`: 何を達成したいか\n- `RuntimeTaskState`: 今回の実行は今どう進んでいるか\n\n### `RuntimeTaskState` vs `ScheduleRecord`\n\n- `RuntimeTaskState`: live execution\n- `ScheduleRecord`: いつ trigger するか\n\n### `SubagentContext` vs `TeamMember`\n\n- `SubagentContext`: 一回きりの delegation branch\n- `TeamMember`: 長期に残る actor identity\n\n### `TeamMember` vs `RequestRecord`\n\n- `TeamMember`: 誰が存在するか\n- `RequestRecord`: どんな coordination request が進行中か\n\n### `TaskRecord` vs `WorktreeRecord`\n\n- `TaskRecord`: 何をやるか\n- `WorktreeRecord`: どこでやるか\n\n### `ToolSpec` vs `CapabilityRoute`\n\n- `ToolSpec`: model に見せる contract\n- `CapabilityRoute`: 実際にどこへ routing するか\n\n## 読み終えたら言えるべきこと\n\n少なくとも次の 3 文を、自分の言葉で説明できる状態を目指してください。\n\n1. `messages` は内容状態であり、`transition` は制御状態である。\n2. `TaskRecord` は goal node であり、`RuntimeTaskState` は live execution slot である。\n3. `TeamMember`、`RequestRecord`、`WorktreeRecord` は全部「仕事っぽい」が、それぞれ actor、protocol、lane という別層の object である。\n\n## 一文で覚える\n\n**どの record が内容を持ち、どの record が流れを持ち、どれが durable でどれが runtime かを分けられれば、agent system の複雑さは急に読める形になります。**\n"
  },
  {
    "version": null,
    "slug": "entity-map",
    "locale": "ja",
    "title": "エンティティ地図",
    "kind": "bridge",
    "filename": "entity-map.md",
    "content": "# エンティティ地図\n\n> この文書は「単語が似て見えるが、同じものではない」という混乱をほどくための地図です。\n\n## 何を分けるための文書か\n\n- [`glossary.md`](./glossary.md) は「この言葉は何か」を説明します\n- [`data-structures.md`](./data-structures.md) は「コードではどんな形か」を説明します\n- この文書は「どの層に属するか」を分けます\n\n## まず層を見る\n\n```text\nconversation layer\n  - message\n  - prompt block\n  - reminder\n\naction layer\n  - tool call\n  - tool result\n  - hook event\n\nwork layer\n  - work-graph task\n  - runtime task\n  - protocol request\n\nexecution layer\n  - subagent\n  - teammate\n  - worktree lane\n\nplatform layer\n  - MCP server\n  - memory record\n  - capability router\n```\n\n## 混同しやすい組\n\n### `Message` vs `PromptBlock`\n\n| エンティティ | 何か | 何ではないか |\n|---|---|---|\n| `Message` | 会話履歴の内容 | 安定した system rule ではない |\n| `PromptBlock` | system instruction の断片 | 直近の会話イベントではない |\n\n### `Todo / Plan` vs `Task`\n\n| エンティティ | 何か | 何ではないか |\n|---|---|---|\n| `todo / plan` | セッション内の進行ガイド | durable work graph ではない |\n| `task` | durable な work node | その場の思いつきではない |\n\n### `Work-Graph Task` vs `RuntimeTaskState`\n\n| エンティティ | 何か | 何ではないか |\n|---|---|---|\n| work-graph task | 仕事目標と依存関係の node | 今動いている executor ではない |\n| runtime task | live execution slot | durable dependency node ではない |\n\n### `Subagent` vs `Teammate`\n\n| エンティティ | 何か | 何ではないか |\n|---|---|---|\n| subagent | 一回きりの委譲 worker | 長期に存在する team member ではない |\n| teammate | identity を持つ persistent collaborator | 使い捨て summary worker ではない |\n\n### `ProtocolRequest` vs normal message\n\n| エンティティ | 何か | 何ではないか |\n|---|---|---|\n| normal message | 自由文のやり取り | 追跡可能な approval workflow ではない |\n| protocol request | `request_id` を持つ構造化要求 | 雑談テキストではない |\n\n### `Task` vs `Worktree`\n\n| エンティティ | 何か | 何ではないか |\n|---|---|---|\n| task | 何をするか | ディレクトリではない |\n| worktree | どこで分離実行するか | 仕事目標そのものではない |\n\n### `Memory` vs `CLAUDE.md`\n\n| エンティティ | 何か | 何ではないか |\n|---|---|---|\n| memory | 後の session でも価値がある事実 | project rule file ではない |\n| `CLAUDE.md` | 安定した local rule / instruction surface | user 固有の long-term fact store ではない |\n\n### `MCPServer` vs `MCPTool`\n\n| エンティティ | 何か | 何ではないか |\n|---|---|---|\n| MCP server | 外部 capability provider | 1 個の tool 定義ではない |\n| MCP tool | server が公開する 1 つの capability | 接続面全体ではない |\n\n## 速見表\n\n| エンティティ | 主な役割 | 典型的な置き場 |\n|---|---|---|\n| `Message` | 会話履歴 | `messages[]` |\n| `PromptParts` | 入力 assembly の断片 | prompt builder |\n| `PermissionRule` | 実行可否の判断 | settings / session state |\n| `HookEvent` | lifecycle extension point | hook layer |\n| `MemoryEntry` | durable fact | memory store |\n| `TaskRecord` | durable work goal | task board |\n| `RuntimeTaskState` | live execution slot | runtime manager |\n| `TeamMember` | persistent actor | team config |\n| `MessageEnvelope` | teammate 間の構造化 message | inbox |\n| `RequestRecord` | protocol workflow state | request tracker |\n| `WorktreeRecord` | isolated execution lane | worktree index |\n| `MCPServerConfig` | 外部 capability provider 設定 | plugin / settings |\n\n## 一文で覚える\n\n**システムが複雑になるほど、単語を増やすことよりも、境界を混ぜないことの方が重要です。**\n"
  },
  {
    "version": null,
    "slug": "glossary",
    "locale": "ja",
    "title": "用語集",
    "kind": "bridge",
    "filename": "glossary.md",
    "content": "# 用語集\n\n> この用語集は、教材主線で特に重要で、初学者が混ぜやすい言葉だけを集めたものです。  \n> 何となく見覚えはあるのに、「結局これは何を指すのか」が言えなくなったら、まずここへ戻ってください。\n\n## いっしょに見ると整理しやすい文書\n\n- [`entity-map.md`](./entity-map.md): それぞれの言葉がどの層に属するかを見る\n- [`data-structures.md`](./data-structures.md): 実際にどんな record 形へ落ちるかを見る\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md): `task` という語が 2 種類に分かれ始めたときに戻る\n- [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md): MCP が tool list だけに見えなくなったときに戻る\n\n## Agent\n\nこの教材での `agent` は、\n\n> 入力を読み、判断し、必要なら tool を呼び出して仕事を進める model\n\nを指します。\n\n簡単に言えば、\n\n- model が考える\n- harness が作業環境を与える\n\nという分担の、考える側です。\n\n## Harness\n\n`harness` は agent の周囲に置く作業環境です。\n\nたとえば次を含みます。\n\n- tools\n- filesystem\n- permission system\n- prompt assembly\n- memory\n- task runtime\n\nmodel そのものは harness ではありません。  \nharness そのものも model ではありません。\n\n## Agent Loop\n\n`agent loop` は agent system の主循環です。\n\n最小形は次の 5 手順です。\n\n1. 現在の context を model に渡す\n2. response が普通の返答か tool_use かを見る\n3. tool を実行する\n4. result を context に戻す\n5. 次の turn へ続くか止まるかを決める\n\nこの loop がなければ、system は単発の chat で終わります。\n\n## Message / `messages[]`\n\n`message` は 1 件の message、`messages[]` はその一覧です。\n\n多くの章では次を含みます。\n\n- user message\n- assistant message\n- tool_result\n\nこれは agent の main working memory にあたります。  \nただし permanent memory ではありません。\n\n## Tool\n\n`tool` は model が要求できる動作です。\n\nたとえば、\n\n- file を読む\n- file を書く\n- shell command を走らせる\n- text を検索する\n\nなどです。\n\n重要なのは、\n\n> model が直接 OS command を叩くのではなく、tool 名と引数を宣言し、実際の実行は harness 側の code が行う\n\nという点です。\n\n## Tool Schema\n\n`tool schema` は tool の使い方を model に説明する構造です。\n\n普通は次を含みます。\n\n- tool 名\n- 何をするか\n- 必要な parameter\n- parameter の型\n\n初心者向けに言えば、tool の説明書です。\n\n## Dispatch Map\n\n`dispatch map` は、\n\n> tool 名から実際の handler 関数へつなぐ対応表\n\nです。\n\nたとえば次のような形です。\n\n```python\n{\n    \"read_file\": read_file_handler,\n    \"write_file\": write_file_handler,\n    \"bash\": bash_handler,\n}\n```\n\n## Stop Reason\n\n`stop_reason` は、model のこの turn がなぜ止まったかを示す理由です。\n\n代表例:\n\n- `end_turn`: 返答を終えた\n- `tool_use`: tool を要求した\n- `max_tokens`: 出力が token 上限で切れた\n\nmain loop はこの値を見て次の動きを決めます。\n\n## Context\n\n`context` は model が今見えている情報全体です。\n\nふつうは次を含みます。\n\n- `messages`\n- system prompt\n- dynamic reminder\n- tool_result\n\ncontext は permanent storage ではなく、\n\n> 今この turn の机の上に出ている情報\n\nと考えると分かりやすいです。\n\n## Compact / Compaction\n\n`compact` は active context を縮めることです。\n\n狙いは、\n\n- 本当に必要な流れを残す\n- 重複や雑音を削る\n- 後続 turn のための space を作る\n\nことです。\n\n大事なのは「削ること」そのものではなく、\n\n**次の turn に必要な構造を保ったまま薄くすること**\n\nです。\n\n## Subagent\n\n`subagent` は親 agent から切り出された、一回限りの delegated worker です。\n\n価値は次です。\n\n- 親 context を汚さずに subtask を処理できる\n- 結果だけを summary として返せる\n\n`teammate` とは違い、長く system に残る actor ではありません。\n\n## Fork\n\nこの教材での `fork` は、\n\n> 子 agent を空白から始めるのではなく、親の context を引き継いで始める方式\n\nを指します。\n\nsubtask が親の議論背景を理解している必要があるときに使います。\n\n## Permission\n\n`permission` は、\n\n> model が要求した操作を実行してよいか判定する層\n\nです。\n\n良い permission system は少なくとも次を分けます。\n\n- すぐ拒否すべきもの\n- 自動許可してよいもの\n- user に確認すべきもの\n\n## Permission Mode\n\n`permission mode` は permission system の動作方針です。\n\n例:\n\n- `default`\n- `plan`\n- `auto`\n\nつまり個々の request の判定規則ではなく、\n\n> 判定の全体方針\n\nです。\n\n## Hook\n\n`hook` は主 loop を書き換えずに、特定の timing で追加動作を差し込む拡張点です。\n\nたとえば、\n\n- tool 実行前に検査する\n- tool 実行後に監査 log を書く\n\nのようなことを行えます。\n\n## Memory\n\n`memory` は session をまたいで残す価値のある情報です。\n\n向いているもの:\n\n- user の長期的 preference\n- 何度も再登場する重要事実\n- 将来の session でも役に立つ feedback\n\n向いていないもの:\n\n- その場限りの冗長な chat 履歴\n- すぐ再導出できる一時情報\n\n## System Prompt\n\n`system prompt` は system-level の instruction surface です。\n\nここでは model に対して、\n\n- あなたは何者か\n- 何を守るべきか\n- どのように協力すべきか\n\nを与えます。\n\n普通の user message より安定して効く層です。\n\n## System Reminder\n\n`system reminder` は毎 turn 動的に差し込まれる短い補助情報です。\n\nたとえば、\n\n- current working directory\n- 現在日付\n- この turn だけ必要な補足\n\nなどです。\n\nstable な system prompt とは役割が違います。\n\n## Query\n\nこの教材での `query` は、\n\n> 1 つの user request を完了させるまで続く多 turn の処理全体\n\nを指します。\n\n単発の 1 回応答ではなく、\n\n- model 呼び出し\n- tool 実行\n- continuation\n- recovery\n\nを含んだまとまりです。\n\n## Transition Reason\n\n`transition reason` は、\n\n> なぜこの system が次の turn へ続いたのか\n\nを説明する理由です。\n\nこれが見えるようになると、\n\n- 普通の tool continuation\n- retry\n- compact 後の再開\n- recovery path\n\nを混ぜずに見られるようになります。\n\n## Task\n\n`task` は durable work graph の中にある仕事目標です。\n\nふつう次を持ちます。\n\n- subject\n- status\n- owner\n- dependency\n\nここでの task は「いま実行中の command」ではなく、\n\n> system が長く持ち続ける work goal\n\nです。\n\n## Dependency Graph\n\n`dependency graph` は task 間の依存関係です。\n\nたとえば、\n\n- A が終わってから B\n- C と D は並行可\n- E は C と D の両方待ち\n\nのような関係を表します。\n\nこれにより system は、\n\n- 今できる task\n- まだ blocked な task\n- 並行可能な task\n\nを判断できます。\n\n## Runtime Task / Runtime Slot\n\n`runtime task` または `runtime slot` は、\n\n> いま実行中、待機中、または直前まで動いていた live execution unit\n\nを指します。\n\n例:\n\n- background の `pytest`\n- 走っている teammate\n- monitor process\n\n`task` との違いはここです。\n\n- `task`: goal\n- `runtime slot`: live execution\n\n## Teammate\n\n`teammate` は multi-agent system 内で長く存在する collaborator です。\n\n`subagent` との違い:\n\n- `subagent`: 一回限りの委譲 worker\n- `teammate`: 長く残り、繰り返し仕事を受ける actor\n\n## Protocol\n\n`protocol` は、事前に決めた協調ルールです。\n\n答える内容は次です。\n\n- message はどんな shape か\n- response はどう返すか\n- approve / reject / expire をどう記録するか\n\nteam 章では多くの場合、\n\n```text\nrequest -> response -> status update\n```\n\nという骨格で現れます。\n\n## Envelope\n\n`envelope` は、\n\n> 本文に加えてメタデータも一緒に包んだ構造化 record\n\nです。\n\nたとえば message 本文に加えて、\n\n- `from`\n- `to`\n- `request_id`\n- `timestamp`\n\nを一緒に持つものです。\n\n## State Machine\n\n`state machine` は難しい理論名に見えますが、ここでは\n\n> 状態がどう変化してよいかを書いた規則表\n\nです。\n\nたとえば、\n\n```text\npending -> approved\npending -> rejected\npending -> expired\n```\n\nだけでも最小の state machine です。\n\n## Router\n\n`router` は分配器です。\n\n役割は、\n\n- request がどの種類かを見る\n- 正しい処理経路へ送る\n\nことです。\n\ntool system では、\n\n- local handler\n- MCP client\n- plugin bridge\n\nのどこへ送るかを決める層として現れます。\n\n## Control Plane\n\n`control plane` は、\n\n> 自分で本仕事をするというより、誰がどう実行するかを調整する層\n\nです。\n\nたとえば、\n\n- permission 判定\n- prompt assembly\n- continuation 理由\n- lane 選択\n\nなどがここに寄ります。\n\n初見では怖く見えるかもしれませんが、この教材ではまず\n\n> 実作業そのものではなく、作業の進め方を調整する層\n\nと覚えれば十分です。\n\n## Capability\n\n`capability` は能力項目です。\n\nMCP の文脈では、capability は tool だけではありません。\n\nたとえば、\n\n- tools\n- resources\n- prompts\n- elicitation\n\nのように複数層があります。\n\n## Worktree\n\n`worktree` は同じ repository の別 working copy です。\n\nこの教材では、\n\n> task ごとに割り当てる isolated execution directory\n\nとして使います。\n\n価値は次です。\n\n- 並行作業が互いの未コミット変更を汚染しない\n- task と execution lane の対応が見える\n- review や closeout がしやすい\n\n## MCP\n\n`MCP` は Model Context Protocol です。\n\nこの教材では単なる remote tool list より広く、\n\n> 外部 capability を統一的に接続する surface\n\nとして扱います。\n\nつまり「外部 tool を呼べる」だけではなく、\n\n- connection\n- auth\n- resources\n- prompts\n- capability routing\n\nまで含む層です。\n"
  },
  {
    "version": null,
    "slug": "s00-architecture-overview",
    "locale": "ja",
    "title": "s00: アーキテクチャ全体図",
    "kind": "bridge",
    "filename": "s00-architecture-overview.md",
    "content": "# s00: アーキテクチャ全体図\n\n> この章は教材全体の地図です。  \n> 「結局この repository は何を教えようとしていて、なぜこの順番で章が並んでいるのか」を先に掴みたいなら、まずここから読むのがいちばん安全です。\n\n## 先に結論\n\nこの教材の章順は妥当です。\n\n大事なのは章数の多さではありません。  \n大事なのは、初学者が無理なく積み上がる順番で system を育てていることです。\n\n全体は次の 4 段階に分かれています。\n\n1. まず本当に動く単一 agent を作る\n2. その上に安全性、拡張点、memory、prompt、recovery を足す\n3. 会話中の一時的 progress を durable work system へ押し上げる\n4. 最後に teams、protocols、autonomy、worktree、MCP / plugin へ広げる\n\nこの順番が自然なのは、学習者が最初に固めるべき主線がたった 1 本だからです。\n\n```text\nuser input\n  ->\nmodel reasoning\n  ->\ntool execution\n  ->\nresult write-back\n  ->\nnext turn or finish\n```\n\nこの主線がまだ曖昧なまま後段の mechanism を積むと、\n\n- permission\n- hook\n- memory\n- MCP\n- worktree\n\nのような言葉が全部ばらばらの trivia に見えてしまいます。\n\n## この教材が再構成したいもの\n\nこの教材の目標は、どこかの production code を逐行でなぞることではありません。\n\n本当に再構成したいのは次の部分です。\n\n- 主要 module は何か\n- module 同士がどう協調するか\n- 各 module の責務は何か\n- 重要 state がどこに住むか\n- 1 つの request が system の中をどう流れるか\n\nつまり狙っているのは、\n\n**設計主脈への高い忠実度であって、周辺実装の 1:1 再現ではありません。**\n\nこれはとても重要です。\n\nもしあなたが本当に知りたいのが、\n\n> 0 から自分で高完成度の coding agent harness を作れるようになること\n\nなら、優先して掴むべきなのは次です。\n\n- agent loop\n- tools\n- planning\n- context management\n- permissions\n- hooks\n- memory\n- prompt assembly\n- tasks\n- teams\n- isolated execution lanes\n- external capability routing\n\n逆に、最初の主線に持ち込まなくてよいものもあります。\n\n- packaging / release\n- cross-platform compatibility の細かな枝\n- enterprise wiring\n- telemetry\n- 歴史的 compatibility layer\n- product 固有の naming accident\n\nこれらが存在しうること自体は否定しません。  \nただし 0-to-1 教学の中心に置くべきではありません。\n\n## 読むときの 3 つの原則\n\n### 1. まず最小で正しい版を学ぶ\n\nたとえば subagent なら、最初に必要なのはこれだけです。\n\n- 親 agent が subtask を切る\n- 子 agent が自分の `messages` を持つ\n- 子 agent が summary を返す\n\nこれだけで、\n\n**親 context を汚さずに探索作業を切り出せる**\n\nという核心は学べます。\n\nそのあとでようやく、\n\n- 親 context を引き継ぐ fork\n- 独立 permission\n- background 実行\n- worktree 隔離\n\nを足せばよいです。\n\n### 2. 新しい語は使う前に意味を固める\n\nこの教材では次のような語が頻繁に出ます。\n\n- state machine\n- dispatch map\n- dependency graph\n- worktree\n- protocol envelope\n- capability\n- control plane\n\n意味が曖昧なまま先へ進むと、後ろの章で一気に詰まります。\n\nそのときは無理に本文を読み切ろうとせず、次の文書へ戻ってください。\n\n- [`glossary.md`](./glossary.md)\n- [`entity-map.md`](./entity-map.md)\n- [`data-structures.md`](./data-structures.md)\n\n### 3. 周辺の複雑さを主線へ持ち込みすぎない\n\n良い教材は「全部話す教材」ではありません。\n\n良い教材は、\n\n- 核心は完全に話す\n- 周辺で重く複雑なものは後ろへ回す\n\nという構造を持っています。\n\nだからこの repository では、あえて主線の外に置いている内容があります。\n\n- packaging / release\n- enterprise policy glue\n- telemetry\n- client integration の細部\n- 逐行の逆向き比較 trivia\n\n## 先に開いておくと楽な補助文書\n\n主線 chapter と一緒に、次の文書を補助地図として持っておくと理解が安定します。\n\n| 文書 | 用途 |\n|---|---|\n| [`teaching-scope.md`](./teaching-scope.md) | 何を教え、何を意図的に省くかを見る |\n| [`data-structures.md`](./data-structures.md) | system 全体の重要 record を一か所で見る |\n| [`s00f-code-reading-order.md`](./s00f-code-reading-order.md) | chapter order と local code reading order をそろえる |\n\nさらに、後半で mechanism 間のつながりが曖昧になったら、次の bridge docs が効きます。\n\n| 文書 | 補うもの |\n|---|---|\n| [`s00d-chapter-order-rationale.md`](./s00d-chapter-order-rationale.md) | なぜ今の順番で学ぶのか |\n| [`s00e-reference-module-map.md`](./s00e-reference-module-map.md) | 参照 repository の高信号 module 群と教材章の対応 |\n| [`s00a-query-control-plane.md`](./s00a-query-control-plane.md) | 高完成度 system に loop 以外の control plane が必要になる理由 |\n| [`s00b-one-request-lifecycle.md`](./s00b-one-request-lifecycle.md) | 1 request が system 全体をどう流れるか |\n| [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) | tool layer が単なる `tool_name -> handler` で終わらない理由 |\n| [`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md) | message / prompt / memory がどこで合流するか |\n| [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) | durable task と live runtime slot の違い |\n| [`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md) | MCP を capability bus として見るための地図 |\n| [`entity-map.md`](./entity-map.md) | entity の境界を徹底的に分ける |\n\n## 4 段階の学習パス\n\n### Stage 1: Core Single-Agent (`s01-s06`)\n\nここでの目標は、\n\n**まず本当に役に立つ単一 agent を作ること**\n\nです。\n\n| 章 | 学ぶもの | 解く問題 |\n|---|---|---|\n| `s01` | Agent Loop | loop がなければ agent にならない |\n| `s02` | Tool Use | model を「話すだけ」から「実際に動く」へ変える |\n| `s03` | Todo / Planning | multi-step work が漂わないようにする |\n| `s04` | Subagent | 探索作業で親 context を汚さない |\n| `s05` | Skills | 必要な知識だけ後から載せる |\n| `s06` | Context Compact | 会話が長くなっても主線を保つ |\n\n### Stage 2: Hardening (`s07-s11`)\n\nここでの目標は、\n\n**動くだけの agent を、安全で拡張可能な agent へ押し上げること**\n\nです。\n\n| 章 | 学ぶもの | 解く問題 |\n|---|---|---|\n| `s07` | Permission System | 危険な操作を gate の後ろへ置く |\n| `s08` | Hook System | loop 本体を書き換えず周辺拡張する |\n| `s09` | Memory System | 本当に価値ある情報だけを跨 session で残す |\n| `s10` | System Prompt | stable rule と runtime input を組み立てる |\n| `s11` | Error Recovery | 失敗後も stop 一択にしない |\n\n### Stage 3: Runtime Work (`s12-s14`)\n\nここでの目標は、\n\n**session 中の計画を durable work graph と runtime execution に分けること**\n\nです。\n\n| 章 | 学ぶもの | 解く問題 |\n|---|---|---|\n| `s12` | Task System | work goal を disk 上に持つ |\n| `s13` | Background Tasks | 遅い command が前景思考を止めないようにする |\n| `s14` | Cron Scheduler | 時間そのものを trigger にする |\n\n### Stage 4: Platform (`s15-s19`)\n\nここでの目標は、\n\n**single-agent harness を協調 platform へ広げること**\n\nです。\n\n| 章 | 学ぶもの | 解く問題 |\n|---|---|---|\n| `s15` | Agent Teams | persistent teammate を持つ |\n| `s16` | Team Protocols | 協調を自由文から structured flow へ上げる |\n| `s17` | Autonomous Agents | idle teammate が自分で次の work を取れるようにする |\n| `s18` | Worktree Isolation | 並行 task が同じ directory を踏み荒らさないようにする |\n| `s19` | MCP & Plugin | 外部 capability を統一 surface で扱う |\n\n## 各章が system に足す中核構造\n\n読者が中盤で混乱しやすいのは、\n\n- 今の章は何を増やしているのか\n- その state は system のどこに属するのか\n\nが曖昧になるからです。\n\nそこで各章を「新しく足す構造」で見直すとこうなります。\n\n| 章 | 中核構造 | 学習後に言えるべきこと |\n|---|---|---|\n| `s01` | `LoopState` | 最小の agent loop を自分で書ける |\n| `s02` | `ToolSpec` / dispatch map | model の意図を安定して実行へ落とせる |\n| `s03` | `TodoItem` / `PlanState` | 現在の progress を外部 state として持てる |\n| `s04` | `SubagentContext` | 親 context を汚さず委譲できる |\n| `s05` | `SkillRegistry` | 必要な knowledge を必要な時だけ注入できる |\n| `s06` | compaction records | 長い対話でも主線を保てる |\n| `s07` | `PermissionDecision` | 実行を gate の後ろへ置ける |\n| `s08` | hook events | loop を壊さず extension を追加できる |\n| `s09` | memory records | 跨 session で残すべき情報を選別できる |\n| `s10` | prompt parts | 入力を section 単位で組み立てられる |\n| `s11` | recovery state / transition reason | なぜ続行するのかを state として説明できる |\n| `s12` | `TaskRecord` | durable work graph を作れる |\n| `s13` | `RuntimeTaskState` | live execution と work goal を分けて見られる |\n| `s14` | `ScheduleRecord` | time-based trigger を足せる |\n| `s15` | `TeamMember` | persistent actor を持てる |\n| `s16` | `ProtocolEnvelope` / `RequestRecord` | structured coordination を作れる |\n| `s17` | `ClaimPolicy` / autonomy state | 自治的な claim / resume を説明できる |\n| `s18` | `WorktreeRecord` / `TaskBinding` | 並行 execution lane を分離できる |\n| `s19` | `MCPServerConfig` / capability route | native / plugin / MCP を同じ外側境界で見られる |\n\n## system 全体を 3 層で見る\n\n全体を最も簡単に捉えるなら、次の 3 層に分けてください。\n\n```text\n1. Main Loop\n   user input を受け、model を呼び、結果に応じて続く\n\n2. Control / Context Layer\n   permission、hook、memory、prompt、recovery が loop を支える\n\n3. Work / Platform Layer\n   tasks、teams、runtime slots、worktrees、MCP が大きな作業面を作る\n```\n\n図で見るとこうです。\n\n```text\nUser\n  |\n  v\nmessages[]\n  |\n  v\n+-------------------------+\n| Agent Loop (s01)        |\n| 1. 入力を組み立てる      |\n| 2. model を呼ぶ         |\n| 3. stop_reason を見る   |\n| 4. tool を実行する      |\n| 5. result を write-back |\n| 6. 次 turn を決める     |\n+-------------------------+\n  |\n  +------------------------------+\n  |                              |\n  v                              v\nTool / Control Plane         Context / State Layer\n(s02, s07, s08, s19)         (s03, s06, s09, s10, s11)\n  |                              |\n  v                              v\nTasks / Teams / Worktree / Runtime (s12-s18)\n```\n\nここで大切なのは、system 全体を 1 本の巨大な file や 1 つの class として捉えないことです。\n\n**chapter order とは、system をどの層の順で理解すると最も心智負荷が低いかを表したもの**\n\nです。\n\n## この章を読み終えたら何が言えるべきか\n\nこの章のゴールは、個々の API を覚えることではありません。\n\n読み終えた時点で、少なくとも次の 3 文を自分の言葉で言える状態を目指してください。\n\n1. この教材は production implementation の周辺 detail ではなく、agent harness の主設計を教えている\n2. chapter order は `single agent -> hardening -> runtime work -> platform` の 4 段階で意味がある\n3. 後ろの章の mechanism は前の章の上に自然に積み上がるので、順番を大きく崩すと学習心智が乱れる\n\n## 一文で覚える\n\n**良い章順とは、機能一覧ではなく、前の層から次の層が自然に育つ学習経路です。**\n"
  },
  {
    "version": null,
    "slug": "s00a-query-control-plane",
    "locale": "ja",
    "title": "s00a: Query Control Plane",
    "kind": "bridge",
    "filename": "s00a-query-control-plane.md",
    "content": "# s00a: Query Control Plane\n\n> これは主線章ではなく橋渡し文書です。  \n> ここで答えたいのは次の問いです。\n>\n> **なぜ高完成度の agent は `messages[]` と `while True` だけでは足りないのか。**\n\n## なぜこの文書が必要か\n\n`s01` では最小の loop を学びます。\n\n```text\nユーザー入力\n  ->\nモデル応答\n  ->\ntool_use があれば実行\n  ->\ntool_result を戻す\n  ->\n次ターン\n```\n\nこれは正しい出発点です。\n\nただし実システムが成長すると、支えるのは loop 本体だけではなく:\n\n- 今どの turn か\n- なぜ続行したのか\n- compact を試したか\n- token recovery 中か\n- hook が終了条件に影響しているか\n\nといった **query 制御状態** です。\n\nこの層を明示しないと、動く demo は作れても、高完成度 harness へ育てにくくなります。\n\n## まず用語を分ける\n\n### Query\n\nここでの `query` は database query ではありません。\n\n意味は:\n\n> 1つのユーザー要求を完了するまで続く、多ターンの処理全体\n\nです。\n\n### Control Plane\n\n`control plane` は:\n\n> 実際の業務動作をする層ではなく、流れをどう進めるかを管理する層\n\nです。\n\nここでは:\n\n- model 応答や tool result は内容\n- 「次に続けるか」「なぜ続けるか」は control plane\n\nと考えると分かりやすいです。\n\n### Transition Reason\n\n`transition reason` は:\n\n> 前のターンが終わらず、次ターンへ進んだ理由\n\nです。\n\nたとえば:\n\n- tool が終わった\n- 出力が切れて続きを書く必要がある\n- compact 後に再実行する\n- hook が続行を要求した\n\nなどがあります。\n\n## 最小の心智モデル\n\n```text\n1. 入力層\n   - messages\n   - system prompt\n   - runtime context\n\n2. 制御層\n   - query state\n   - turn count\n   - transition reason\n   - compact / recovery flags\n\n3. 実行層\n   - model call\n   - tool execution\n   - write-back\n```\n\nこの層は loop を置き換えるためではありません。\n\n**小さな loop を、分岐と状態を扱える system に育てるため**にあります。\n\n## なぜ `messages[]` だけでは足りないか\n\n最小 demo では、多くのことを `messages[]` に押し込めても動きます。\n\nしかし次の情報は会話内容ではなく制御状態です。\n\n- reactive compact を既に試したか\n- 出力続行を何回したか\n- 今回の続行が tool によるものか recovery によるものか\n- 今だけ output budget を変えているか\n\nこれらを全部 `messages[]` に混ぜると、状態の境界が崩れます。\n\n## 主要なデータ構造\n\n### `QueryParams`\n\nquery に入るときの外部入力です。\n\n```python\nparams = {\n    \"messages\": [...],\n    \"system_prompt\": \"...\",\n    \"user_context\": {...},\n    \"system_context\": {...},\n    \"tool_use_context\": {...},\n    \"max_output_tokens_override\": None,\n    \"max_turns\": None,\n}\n```\n\nこれは「入口で既に分かっているもの」です。\n\n### `QueryState`\n\nquery の途中で変わり続ける制御状態です。\n\n```python\nstate = {\n    \"messages\": [...],\n    \"tool_use_context\": {...},\n    \"turn_count\": 1,\n    \"continuation_count\": 0,\n    \"has_attempted_compact\": False,\n    \"max_output_tokens_override\": None,\n    \"stop_hook_active\": False,\n    \"transition\": None,\n}\n```\n\n重要なのは:\n\n- 内容状態と制御状態を分ける\n- どの continue site も同じ state を更新する\n\nことです。\n\n### `TransitionReason`\n\n続行理由は文字列でも enum でもよいですが、明示する方がよいです。\n\n```python\nTRANSITIONS = (\n    \"tool_result_continuation\",\n    \"max_tokens_recovery\",\n    \"compact_retry\",\n    \"stop_hook_continuation\",\n)\n```\n\nこれで:\n\n- log\n- test\n- debug\n- 教材説明\n\nがずっと分かりやすくなります。\n\n## 最小実装の流れ\n\n### 1. 外部入力と内部状態を分ける\n\n```python\ndef query(params):\n    state = {\n        \"messages\": params[\"messages\"],\n        \"tool_use_context\": params[\"tool_use_context\"],\n        \"turn_count\": 1,\n        \"continuation_count\": 0,\n        \"has_attempted_compact\": False,\n        \"transition\": None,\n    }\n```\n\n### 2. 各ターンで state を読んで実行する\n\n```python\nwhile True:\n    response = call_model(...)\n```\n\n### 3. 続行時は必ず state に理由を書き戻す\n\n```python\nif response.stop_reason == \"tool_use\":\n    state[\"messages\"] = append_tool_results(...)\n    state[\"transition\"] = \"tool_result_continuation\"\n    state[\"turn_count\"] += 1\n    continue\n```\n\n大事なのは:\n\n**ただ `continue` するのではなく、なぜ `continue` したかを状態に残すこと**\n\nです。\n\n## 初学者が混ぜやすいもの\n\n### 1. 会話内容と制御状態\n\n- `messages` は内容\n- `turn_count` や `transition` は制御\n\n### 2. Loop と Control Plane\n\n- loop は反復の骨格\n- control plane はその反復を管理する層\n\n### 3. Prompt assembly と query state\n\n- prompt assembly は「このターンに model へ何を渡すか」\n- query state は「この query が今どういう状態か」\n\n## 一文で覚える\n\n**高完成度の agent では、会話内容を持つ層と、続行理由を持つ層を分けた瞬間に system の見通しが良くなります。**\n"
  },
  {
    "version": null,
    "slug": "s00b-one-request-lifecycle",
    "locale": "ja",
    "title": "s00b: 1 リクエストのライフサイクル",
    "kind": "bridge",
    "filename": "s00b-one-request-lifecycle.md",
    "content": "# s00b: 1 リクエストのライフサイクル\n\n> これは橋渡し文書です。  \n> 章ごとの説明を、1本の実行の流れとしてつなぎ直します。\n>\n> 問いたいのは次です。\n>\n> **ユーザーの一言が system に入ってから、どう流れ、どこで状態が変わり、どう loop に戻るのか。**\n\n## なぜ必要か\n\n章を順に読むと、個別の仕組みは理解できます。\n\n- `s01`: loop\n- `s02`: tools\n- `s07`: permissions\n- `s09`: memory\n- `s12-s19`: tasks / teams / worktree / MCP\n\nしかし実装段階では、次の疑問で詰まりやすいです。\n\n- 先に走るのは prompt か memory か\n- tool 実行前に permissions と hooks はどこへ入るのか\n- task、runtime task、teammate、worktree はどの段で関わるのか\n\nこの文書はその縦の流れをまとめます。\n\n## まず全体図\n\n```text\nユーザー要求\n  |\n  v\nQuery State 初期化\n  |\n  v\nsystem prompt / messages / reminders を組み立てる\n  |\n  v\nモデル呼び出し\n  |\n  +-- 普通の応答 --------------------------> 今回の request は終了\n  |\n  +-- tool_use\n        |\n        v\n    Tool Router\n        |\n        +-- permission gate\n        +-- hook interception\n        +-- native tool / task / teammate / MCP\n        |\n        v\n    実行結果\n        |\n        +-- task / runtime / memory / worktree 状態を書き換える場合がある\n        |\n        v\n    tool_result を messages へ write-back\n        |\n        v\n    Query State 更新\n        |\n        v\n    次ターン\n```\n\n## 第 1 段: Query State を作る\n\nユーザーが:\n\n```text\ntests/test_auth.py の失敗を直して、原因も説明して\n```\n\nと言ったとき、最初に起きるのは shell 実行ではありません。\n\nまず「今回の request の状態」が作られます。\n\n```python\nquery_state = {\n    \"messages\": [{\"role\": \"user\", \"content\": user_text}],\n    \"turn_count\": 1,\n    \"transition\": None,\n    \"tool_use_context\": {...},\n}\n```\n\nポイントは:\n\n**1 リクエスト = 1 API call ではなく、複数ターンにまたがる処理**\n\nということです。\n\n## 第 2 段: モデル入力を組み立てる\n\n実システムは、生の `messages` だけをそのまま送らないことが多いです。\n\n組み立てる対象はたとえば:\n\n- system prompt blocks\n- normalized messages\n- memory section\n- reminders\n- tool list\n\nつまりモデルが実際に見るのは:\n\n```text\nsystem prompt\n+ normalized messages\n+ optional memory / reminders / attachments\n+ tools\n```\n\nここで大事なのは:\n\n**system prompt は入力全体ではなく、その一部**\n\nだということです。\n\n## 第 3 段: モデルは 2 種類の出力を返す\n\n### 1. 普通の回答\n\n結論や説明だけを返し、今回の request が終わる場合です。\n\n### 2. 動作意図\n\ntool call です。\n\n例:\n\n```text\nread_file(...)\nbash(...)\ntodo_write(...)\nagent(...)\nmcp__server__tool(...)\n```\n\nここで system が受け取るのは単なる文章ではなく:\n\n> モデルが「現実の動作を起こしたい」という意図\n\nです。\n\n## 第 4 段: Tool Router が受け取る\n\n`tool_use` が出たら、次は tool control plane の責任です。\n\n最低でも次を決めます。\n\n1. これはどの tool か\n2. どの handler / capability へ送るか\n3. 実行前に permission が必要か\n4. hook が割り込むか\n5. どの共有状態へアクセスするか\n\n## 第 5 段: Permission が gate をかける\n\n危険な動作は、そのまま実行されるべきではありません。\n\nたとえば:\n\n- file write\n- bash\n- 外部 service 呼び出し\n- worktree の削除\n\nここで system は:\n\n```text\ndeny\n  -> mode\n  -> allow\n  -> ask\n```\n\nのような判断経路を持ちます。\n\npermission が扱うのは:\n\n> この動作を起こしてよいか\n\nです。\n\n## 第 6 段: Hook が周辺ロジックを足す\n\nhook は permission とは別です。\n\nhook は:\n\n- 実行前の補助チェック\n- 実行後の記録\n- 補助メッセージの注入\n\nなど、loop の周辺で side effect を足します。\n\nつまり:\n\n- permission は gate\n- hook は extension\n\nです。\n\n## 第 7 段: 実行結果が状態を変える\n\ntool は text だけを返すとは限りません。\n\n実行によって:\n\n- task board が更新される\n- runtime task が生成される\n- memory 候補が増える\n- worktree lane が作られる\n- teammate へ request が飛ぶ\n- MCP resource / tool result が返る\n\nといった状態変化が起きます。\n\nここでの大原則は:\n\n**tool result は内容を返すだけでなく、system state を進める**\n\nということです。\n\n## 第 8 段: tool_result を loop へ戻す\n\n最後に system は結果を `messages` へ戻します。\n\n```python\nmessages.append({\n    \"role\": \"user\",\n    \"content\": [\n        {\"type\": \"tool_result\", ...}\n    ],\n})\n```\n\nそして query state を更新し:\n\n- `turn_count`\n- `transition`\n- compact / recovery flags\n\nなどを整えて、次ターンへ進みます。\n\n## 後半章はどこで関わるか\n\n| 仕組み | 1 request の中での役割 |\n|---|---|\n| `s09` memory | 入力 assembly の一部になる |\n| `s10` prompt pipeline | 各 source を 1 つの model input へ組む |\n| `s12` task | durable work goal を持つ |\n| `s13` runtime task | 今動いている execution slot を持つ |\n| `s15-s17` teammate / protocol / autonomy | request を actor 間で回す |\n| `s18` worktree | 実行ディレクトリを分離する |\n| `s19` MCP | 外部 capability provider と接続する |\n\n## 一文で覚える\n\n**1 request の本体は「モデルを 1 回呼ぶこと」ではなく、「入力を組み、動作を実行し、結果を state に戻し、必要なら次ターンへ続けること」です。**\n"
  },
  {
    "version": null,
    "slug": "s00c-query-transition-model",
    "locale": "ja",
    "title": "s00c: Query Transition Model",
    "kind": "bridge",
    "filename": "s00c-query-transition-model.md",
    "content": "# s00c: Query Transition Model\n\n> この bridge doc は次の一点を解くためのものです。\n>\n> **高完成度の agent では、なぜ query が次の turn へ続くのかを明示しなければならないのか。**\n\n## なぜこの資料が必要か\n\n主線では次を順に学びます。\n\n- `s01`: 最小 loop\n- `s06`: context compact\n- `s11`: error recovery\n\n流れ自体は正しいです。\n\nただし、章ごとに別々に読むと多くの読者は次のように理解しがちです。\n\n> 「とにかく `continue` したから次へ進む」\n\nこれは toy demo なら動きます。\n\nしかし高完成度システムではすぐに破綻します。\n\nなぜなら query が継続する理由は複数あり、それぞれ本質が違うからです。\n\n- tool が終わり、その結果を model に戻す\n- 出力が token 上限で切れて続きが必要\n- compact 後に再試行する\n- transport error の後で backoff して再試行する\n- stop hook がまだ終わるなと指示する\n- budget policy がまだ継続を許している\n\nこれら全部を曖昧な `continue` に潰すと、すぐに次が悪化します。\n\n- log が読みにくくなる\n- test が書きにくくなる\n- 学習者の心智モデルが濁る\n\n## まず用語\n\n### transition とは\n\nここでの `transition` は:\n\n> 前の turn が次の turn へ移った理由\n\nを指します。\n\nmessage 内容そのものではなく、制御上の原因です。\n\n### continuation とは\n\ncontinuation は:\n\n> この query がまだ終わっておらず、先へ進むべき状態\n\nのことです。\n\nただし continuation は一種類ではありません。\n\n### query boundary とは\n\nquery boundary は turn と次の turn の境目です。\n\nこの境界を越えるたびに、システムは次を知っているべきです。\n\n- なぜ続くのか\n- 続く前にどの state を変えたのか\n- 次の turn がその変更をどう解釈するのか\n\n## 最小の心智モデル\n\nquery を一本の直線だと思わないでください。\n\nより実像に近い理解は次です。\n\n```text\n1 本の query\n  = 明示された continuation reason を持つ\n    state transition の連鎖\n```\n\n例えば:\n\n```text\nuser input\n  ->\nmodel emits tool_use\n  ->\ntool finishes\n  ->\ntool_result_continuation\n  ->\nmodel output is truncated\n  ->\nmax_tokens_recovery\n  ->\ncompact_retry\n  ->\nfinal completion\n```\n\n重要なのは:\n\n> システムは while loop を漫然と回しているのではなく、\n> 明示された transition reason の列で進んでいる\n\nということです。\n\n## 主要 record\n\n### 1. query state の `transition`\n\n教材版でも次のような field は明示しておくべきです。\n\n```python\nstate = {\n    \"messages\": [...],\n    \"turn_count\": 3,\n    \"continuation_count\": 1,\n    \"has_attempted_compact\": False,\n    \"transition\": None,\n}\n```\n\nこの field は飾りではありません。\n\nこれによって:\n\n- この turn がなぜ存在するか\n- log がどう説明すべきか\n- test がどの path を assert すべきか\n\nが明確になります。\n\n### 2. `TransitionReason`\n\n教材版の最小集合は次の程度で十分です。\n\n```python\nTRANSITIONS = (\n    \"tool_result_continuation\",\n    \"max_tokens_recovery\",\n    \"compact_retry\",\n    \"transport_retry\",\n    \"stop_hook_continuation\",\n    \"budget_continuation\",\n)\n```\n\nこれらは同じではありません。\n\n- `tool_result_continuation`\n  は通常の主線継続\n- `max_tokens_recovery`\n  は切れた出力の回復継続\n- `compact_retry`\n  は context 再構成後の継続\n- `transport_retry`\n  は基盤失敗後の再試行継続\n- `stop_hook_continuation`\n  は外部制御による継続\n- `budget_continuation`\n  は budget policy による継続\n\n### 3. continuation budget\n\n高完成度システムは単に続行するだけではなく、続行回数を制御します。\n\n```python\nstate = {\n    \"max_output_tokens_recovery_count\": 2,\n    \"has_attempted_reactive_compact\": True,\n}\n```\n\n本質は:\n\n> continuation は無限の抜け道ではなく、制御された資源\n\nという点です。\n\n## 最小実装の進め方\n\n### Step 1: continue site を明示する\n\n初心者の loop はよくこうなります。\n\n```python\ncontinue\n```\n\n教材版は一歩進めます。\n\n```python\nstate[\"transition\"] = \"tool_result_continuation\"\ncontinue\n```\n\n### Step 2: continuation と state patch を対にする\n\n```python\nif response.stop_reason == \"tool_use\":\n    state[\"messages\"] = append_tool_results(...)\n    state[\"turn_count\"] += 1\n    state[\"transition\"] = \"tool_result_continuation\"\n    continue\n\nif response.stop_reason == \"max_tokens\":\n    state[\"messages\"].append({\n        \"role\": \"user\",\n        \"content\": CONTINUE_MESSAGE,\n    })\n    state[\"max_output_tokens_recovery_count\"] += 1\n    state[\"transition\"] = \"max_tokens_recovery\"\n    continue\n```\n\n大事なのは「1 行増えた」ことではありません。\n\n大事なのは:\n\n> 続行する前に、理由と state mutation を必ず知っている\n\nことです。\n\n### Step 3: 通常継続と recovery 継続を分ける\n\n```python\nif should_retry_transport(error):\n    time.sleep(backoff(...))\n    state[\"transition\"] = \"transport_retry\"\n    continue\n\nif should_recompact(error):\n    state[\"messages\"] = compact_messages(state[\"messages\"])\n    state[\"transition\"] = \"compact_retry\"\n    continue\n```\n\nここまで来ると `continue` は曖昧な動作ではなく、型付きの control transition になります。\n\n## 何を test すべきか\n\n教材 repo では少なくとも次を test しやすくしておくべきです。\n\n- tool result が `tool_result_continuation` を書く\n- truncated output が `max_tokens_recovery` を書く\n- compact retry が古い reason を黙って使い回さない\n- transport retry が通常 turn に見えない\n\nこれが test しづらいなら、まだ model が暗黙的すぎます。\n\n## 何を教えすぎないか\n\nvendor 固有の transport detail や細かすぎる enum を全部教える必要はありません。\n\n教材 repo で本当に必要なのは次です。\n\n> 1 本の query は明示された transition の連鎖であり、\n> 各 transition は reason・state patch・budget rule を持つ\n\nここが分かれば、開発者は高完成度 agent を 0 から組み直せます。\n"
  },
  {
    "version": null,
    "slug": "s00d-chapter-order-rationale",
    "locale": "ja",
    "title": "s00d: Chapter Order Rationale",
    "kind": "bridge",
    "filename": "s00d-chapter-order-rationale.md",
    "content": "# s00d: Chapter Order Rationale\n\n> この資料は 1 つの仕組みを説明するためのものではありません。  \n> もっと基礎的な問いに答えるための資料です:\n>\n> **なぜこの教材は今の順序で教えるのか。なぜ source file の並びや機能の派手さ、実装難度の順ではないのか。**\n\n## 先に結論\n\n現在の `s01 -> s19` の順序は妥当です。\n\nこの順序の価値は、単に章数が多いことではなく、学習者が理解すべき依存順でシステムを育てていることです。\n\n1. 最小の agent loop を作る\n2. その loop の周囲に control plane と hardening を足す\n3. session 内 planning を durable work と runtime state へ広げる\n4. その後で teammate、isolation lane、external capability へ広げる\n\nつまりこの教材は:\n\n**mechanism の依存順**\n\nで構成されています。\n\n## 4 本の依存線\n\nこの教材は大きく 4 本の依存線で並んでいます。\n\n1. `core loop dependency`\n2. `control-plane dependency`\n3. `work-state dependency`\n4. `platform-boundary dependency`\n\n雑に言うと:\n\n```text\nまず agent を動かす\n  -> 次に安全に動かす\n  -> 次に長く動かす\n  -> 最後に platform として動かす\n```\n\nこれが今の順序の核心です。\n\n## 全体の並び\n\n```text\ns01-s06\n  単一 agent の最小主線を作る\n\ns07-s11\n  control plane と hardening を足す\n\ns12-s14\n  durable work と runtime を作る\n\ns15-s19\n  teammate・protocol・autonomy・worktree・external capability を足す\n```\n\n各段の終わりで、学習者は次のように言えるべきです。\n\n- `s06` の後: 「動く単一 agent harness を自力で作れる」\n- `s11` の後: 「それをより安全に、安定して、拡張しやすくできる」\n- `s14` の後: 「durable task、background runtime、time trigger を整理して説明できる」\n- `s19` の後: 「高完成度 agent platform の外周境界が見えている」\n\n## なぜ前半は今の順序で固定すべきか\n\n### `s01` は必ず最初\n\nここで定義されるのは:\n\n- 最小の入口\n- turn ごとの進み方\n- tool result がなぜ次の model call に戻るのか\n\nこれがないと、後ろの章はすべて空中に浮いた feature 説明になります。\n\n### `s02` は `s01` の直後でよい\n\ntool がない agent は、まだ「話しているだけ」で「作業している」状態ではありません。\n\n`s02` で初めて:\n\n- model が `tool_use` を出す\n- system が handler を選ぶ\n- tool が実行される\n- `tool_result` が loop に戻る\n\nという、harness の実在感が出ます。\n\n### `s03` は `s04` より前であるべき\n\n教育上ここは重要です。\n\n先に教えるべきなのは:\n\n- 現在の agent が自分の仕事をどう整理するか\n\nその後に教えるべきなのが:\n\n- どの仕事を subagent へ切り出すべきか\n\n`s04` を早くしすぎると、subagent が isolation mechanism ではなく逃げ道に見えてしまいます。\n\n### `s05` は `s06` の前で正しい\n\nこの 2 章は同じ問題の前半と後半です。\n\n- `s05`: そもそも不要な知識を context へ入れすぎない\n- `s06`: それでも残る context をどう compact するか\n\n先に膨張を減らし、その後で必要なものだけ compact する。  \nこの順序はとても自然です。\n\n## なぜ `s07-s11` は 1 つの hardening block なのか\n\nこの 5 章は別々に見えて、実は同じ問いに答えています:\n\n**loop はもう動く。では、それをどう安定した本当の system にするか。**\n\n### `s07` は `s08` より前で正しい\n\n先に必要なのは:\n\n- その action を実行してよいか\n- deny するか\n- user に ask するか\n\nという gate の考え方です。\n\nその後で:\n\n- loop の周囲に何を hook するか\n\nを教える方が自然です。\n\nつまり:\n\n**gate が先、extend が後**\n\nです。\n\n### `s09` は `s10` より前で正しい\n\n`s09` は:\n\n- durable information が何か\n- 何を long-term に残すべきか\n\nを教えます。\n\n`s10` は:\n\n- 複数の入力源をどう model input に組み立てるか\n\nを教えます。\n\nつまり:\n\n- memory は content source を定義する\n- prompt assembly は source たちの組み立て順を定義する\n\n逆にすると、prompt pipeline が不自然で謎の文字列操作に見えやすくなります。\n\n### `s11` はこの block の締めとして適切\n\nerror recovery は独立した機能ではありません。\n\nここで system は初めて:\n\n- なぜ continue するのか\n- なぜ retry するのか\n- なぜ stop するのか\n\nを明示する必要があります。\n\nそのためには、input path、tool path、state path、control path が先に見えている必要があります。\n\n## なぜ `s12-s14` は goal -> runtime -> schedule の順なのか\n\nここは順番を崩すと一気に混乱します。\n\n### `s12` は `s13` より先\n\n`s12` は:\n\n- 仕事そのものが何か\n- dependency がどう張られるか\n- downstream work がいつ unlock されるか\n\nを教えます。\n\n`s13` は:\n\n- 今まさに何が live execution として動いているか\n- background result がどこへ戻るか\n- runtime state がどう write-back されるか\n\nを教えます。\n\nつまり:\n\n- `task` は durable goal\n- `runtime task` は live execution slot\n\nです。\n\nここを逆にすると、この 2 つが一語の task に潰れてしまいます。\n\n### `s14` は `s13` の後であるべき\n\ncron は別種の task を増やす章ではありません。\n\n追加するのは:\n\n**time という start condition**\n\nです。\n\nだから自然な順序は:\n\n`durable task graph -> runtime slot -> schedule trigger`\n\nになります。\n\n## なぜ `s15-s19` は team -> protocol -> autonomy -> worktree -> capability bus なのか\n\n### `s15` で system 内に誰が持続するかを定義する\n\nprotocol や autonomy より前に必要なのは durable actor です。\n\n- teammate は誰か\n- どんな identity を持つか\n- どう持続するか\n\n### `s16` で actor 間の coordination rule を定義する\n\nprotocol は actor より先には来ません。\n\nprotocol は次を構造化するために存在します。\n\n- 誰が request するか\n- 誰が approve するか\n- 誰が respond するか\n- どう trace するか\n\n### `s17` はその後で初めて明確になる\n\nautonomy は曖昧に説明しやすい概念です。\n\nしかし本当に必要なのは:\n\n- persistent teammate がすでに存在する\n- structured coordination がすでに存在する\n\nという前提です。\n\nそうでないと autonomous claim は魔法っぽく見えてしまいます。\n\n### `s18` は `s19` より前がよい\n\nworktree isolation は local execution boundary の問題です。\n\n- 並列作業がどこで走るか\n- lane 同士をどう隔離するか\n\nこれを先に見せてから:\n\n- plugin\n- MCP server\n- external capability route\n\nへ進む方が、自作実装の足場が崩れません。\n\n### `s19` は最後で正しい\n\nここは platform の最外周です。\n\nlocal の:\n\n- actor\n- lane\n- durable task\n- runtime execution\n\nが見えた後で、ようやく:\n\n- external capability provider\n\nがきれいに入ってきます。\n\n## コースを悪くする 5 つの誤った並べ替え\n\n1. `s04` を `s03` より前に動かす  \n   local planning より先に delegation を教えてしまう。\n\n2. `s10` を `s09` より前に動かす  \n   input source の理解なしに prompt assembly を教えることになる。\n\n3. `s13` を `s12` より前に動かす  \n   durable goal と live runtime slot が混ざる。\n\n4. `s17` を `s15` や `s16` より前に動かす  \n   autonomy が曖昧な polling magic に見える。\n\n5. `s19` を `s18` より前に動かす  \n   local platform boundary より external capability が目立ってしまう。\n\n## Maintainer が順序変更前に確認すべきこと\n\n章を動かす前に次を確認するとよいです。\n\n1. 前提概念はすでに前で説明されているか\n2. この変更で別の層の概念同士が混ざらないか\n3. この章が主に追加するのは goal か、runtime state か、actor か、capability boundary か\n4. これを早めても、学習者は最小正解版をまだ自力で作れるか\n5. これは開発者理解のための変更か、それとも source file の順を真似ているだけか\n\n5 番目が後者なら、たいてい変更しない方がよいです。\n\n## 一文で残すなら\n\n**良い章順とは、mechanism の一覧ではなく、各章が前章から自然に伸びた次の層として見える並びです。**\n"
  },
  {
    "version": null,
    "slug": "s00e-reference-module-map",
    "locale": "ja",
    "title": "s00e: 参照リポジトリのモジュール対応表",
    "kind": "bridge",
    "filename": "s00e-reference-module-map.md",
    "content": "# s00e: 参照リポジトリのモジュール対応表\n\n> これは保守者と本気で学ぶ読者向けの校正文書です。  \n> 逆向きソースを逐行で読ませるための資料ではありません。\n>\n> ここで答えたいのは、次の一点です。\n>\n> **参照リポジトリの高信号なモジュール群と現在の教材の章順を突き合わせると、今のカリキュラム順は本当に妥当なのか。**\n\n## 結論\n\n妥当です。\n\n現在の `s01 -> s19` の順序は大筋で正しく、単純に「ソースツリーの並び順」に合わせるより、実際の設計主幹に近いです。\n\n理由は単純です。\n\n- 参照リポジトリには表層のディレクトリがたくさんある\n- しかし本当に設計の重みを持つのは、制御・状態・タスク・チーム・worktree・外部 capability に関する一部のクラスタ\n- それらは現在の 4 段階の教材構成ときれいに対応している\n\nしたがって、すべきことは「教材をソース木順へ潰す」ことではありません。\n\nすべきことは:\n\n- 今の依存関係ベースの順序を維持する\n- 参照リポジトリとの対応を明文化する\n- 主線に不要な製品周辺の細部を入れ過ぎない\n\n## この比較で見た高信号クラスタ\n\n主に次のようなモジュール群を見ています。\n\n- `Tool.ts`\n- `state/AppStateStore.ts`\n- `coordinator/coordinatorMode.ts`\n- `memdir/*`\n- `services/SessionMemory/*`\n- `services/toolUseSummary/*`\n- `constants/prompts.ts`\n- `tasks/*`\n- `tools/TodoWriteTool/*`\n- `tools/AgentTool/*`\n- `tools/ScheduleCronTool/*`\n- `tools/EnterWorktreeTool/*`\n- `tools/ExitWorktreeTool/*`\n- `tools/MCPTool/*`\n- `services/mcp/*`\n- `plugins/*`\n- `hooks/toolPermission/*`\n\nこれだけで、設計主脈絡の整合性は十分に判断できます。\n\n## 対応関係\n\n| 参照リポジトリのクラスタ | 典型例 | 対応する教材章 | この配置が妥当な理由 |\n|---|---|---|---|\n| Query ループと制御状態 | `Tool.ts`、`AppStateStore.ts`、query / coordinator 状態 | `s00`、`s00a`、`s00b`、`s01`、`s11` | 実システムは `messages[] + while True` だけではない。教材が最小ループから始め、後で control plane を補う流れは正しい。 |\n| Tool routing と実行面 | `Tool.ts`、native tools、tool context、実行 helper | `s02`、`s02a`、`s02b` | 参照実装は tools を共有 execution plane として扱っている。教材の分け方は妥当。 |\n| セッション計画 | `TodoWriteTool` | `s03` | セッション内の進行整理は小さいが重要な層で、持続タスクより先に学ぶべき。 |\n| 一回きりの委譲 | `AgentTool` の最小部分 | `s04` | 参照実装の agent machinery は大きいが、教材がまず「新しい文脈 + サブタスク + 要約返却」を教えるのは正しい。 |\n| Skill の発見と読み込み | `DiscoverSkillsTool`、`skills/*`、関連 prompt | `s05` | skills は飾りではなく知識注入層なので、prompt の複雑化より前に置くのが自然。 |\n| Context 圧縮と collapse | `services/toolUseSummary/*`、`services/contextCollapse/*` | `s06` | 参照実装に明示的な compact 層がある以上、これを早めに学ぶ構成は正しい。 |\n| Permission gate | `types/permissions.ts`、`hooks/toolPermission/*` | `s07` | 実行可否は独立した gate であり、単なる hook ではない。 |\n| Hooks と周辺拡張 | `types/hooks.ts`、hook runner | `s08` | 参照実装でも gate と extend は分かれている。順序は現状のままでよい。 |\n| Durable memory | `memdir/*`、`services/SessionMemory/*` | `s09` | memory は「何でも残すノート」ではなく、選択的な跨セッション層として扱われている。 |\n| Prompt 組み立て | `constants/prompts.ts`、prompt sections | `s10`、`s10a` | 入力は複数 source の合成物であり、教材が pipeline として説明するのは正しい。 |\n| Recovery / continuation | query transition、retry、compact retry、token recovery | `s11`、`s00c` | 続行理由は実システムで明示的に存在するため、前段の層を理解した後に学ぶのが自然。 |\n| Durable work graph | task record、dependency unlock | `s12` | 会話内の plan と durable work graph を分けている点が妥当。 |\n| Live runtime task | `tasks/types.ts`、`LocalShellTask`、`LocalAgentTask`、`RemoteAgentTask` | `s13`、`s13a` | 参照実装の runtime task union は、`TaskRecord` と `RuntimeTaskState` を分けるべき強い根拠になる。 |\n| Scheduled trigger | `ScheduleCronTool/*`、`useScheduledTasks` | `s14` | scheduling は runtime work の上に乗る開始条件なので、この順序でよい。 |\n| Persistent teammate | `InProcessTeammateTask`、team tools、agent registry | `s15` | 一回限りの subagent から durable actor へ広がる流れが参照実装にある。 |\n| Structured protocol | send-message、request tracking、coordinator mode | `s16` | protocol は actor が先に存在して初めて意味を持つ。 |\n| Autonomous claim / resume | task claiming、async worker lifecycle、resume logic | `s17` | autonomy は actor と task と protocol の上に成り立つ。 |\n| Worktree lane | `EnterWorktreeTool`、`ExitWorktreeTool`、worktree helper | `s18` | worktree は単なる git 小技ではなく、実行レーンと closeout 状態の仕組み。 |\n| External capability bus | `MCPTool`、`services/mcp/*`、`plugins/*` | `s19`、`s19a` | 参照実装でも MCP / plugin は外側の platform boundary にある。最後に置くのが正しい。 |\n\n## 特に強く裏付けられた 5 点\n\n### 1. `s03` は `s12` より前でよい\n\n参照実装には:\n\n- セッション内の小さな計画\n- 持続する task / runtime machinery\n\nの両方があります。\n\nこれは同じものではありません。\n\n### 2. `s09` は `s10` より前でよい\n\nprompt assembly は memory を含む複数 source を組み立てます。\n\nしたがって:\n\n- 先に memory という source を理解する\n- その後で prompt pipeline を理解する\n\nの順が自然です。\n\n### 3. `s12` は `s13` より前でなければならない\n\n`tasks/types.ts` に見える runtime task union は非常に重要です。\n\nこれは:\n\n- durable な仕事目標\n- 今まさに動いている実行スロット\n\nが別物であることをはっきり示しています。\n\n### 4. `s15 -> s16 -> s17` の順は妥当\n\n参照実装でも:\n\n- actor\n- protocol\n- autonomy\n\nの順で積み上がっています。\n\n### 5. `s18` は `s19` より前でよい\n\nworktree はまずローカルな実行境界として理解されるべきです。\n\nそのあとで:\n\n- plugin\n- MCP server\n- 外部 capability provider\n\nへ広げる方が、心智がねじれません。\n\n## 教材主線に入れ過ぎない方がよいもの\n\n参照リポジトリに実在していても、主線へ入れ過ぎるべきではないものがあります。\n\n- CLI command 面の広がり\n- UI rendering の細部\n- telemetry / analytics 分岐\n- remote / enterprise の配線\n- compatibility layer\n- ファイル名や行番号レベルの trivia\n\nこれらは本番では意味があります。\n\nただし 0 から 1 の教材主線の中心ではありません。\n\n## 教材側が特に注意すべき点\n\n### 1. Subagent と Teammate を混ぜない\n\n参照実装の `AgentTool` は:\n\n- 一回きりの委譲\n- background worker\n- persistent teammate\n- worktree-isolated worker\n\nをまたいでいます。\n\nだからこそ教材では:\n\n- `s04`\n- `s15`\n- `s17`\n- `s18`\n\nに分けて段階的に教える方がよいです。\n\n### 2. Worktree を「git の小技」へ縮めない\n\n参照実装には keep / remove、resume、cleanup、dirty check があります。\n\n`s18` は今後も:\n\n- lane identity\n- task binding\n- closeout\n- cleanup\n\nを教える章として保つべきです。\n\n### 3. MCP を「外部 tool 一覧」へ縮めない\n\n参照実装には tools 以外にも:\n\n- resources\n- prompts\n- elicitation / connection state\n- plugin mediation\n\nがあります。\n\nしたがって `s19` は tools-first で入ってよいですが、capability bus という外側の境界も説明すべきです。\n\n## 最終判断\n\n参照リポジトリの高信号クラスタと照らす限り、現在の章順は妥当です。\n\n今後の大きな加点ポイントは、さらに大規模な並べ替えではなく:\n\n- bridge docs の充実\n- エンティティ境界の明確化\n- 多言語の整合\n- web 側での学習導線の明快さ\n\nにあります。\n\n## 一文で覚える\n\n**よい教材順は、ファイルが並んでいる順ではなく、学習者が依存関係に沿って実装を再構成できる順です。**\n"
  },
  {
    "version": null,
    "slug": "s00f-code-reading-order",
    "locale": "ja",
    "title": "s00f: このリポジトリのコード読解順",
    "kind": "bridge",
    "filename": "s00f-code-reading-order.md",
    "content": "# s00f: このリポジトリのコード読解順\n\n> このページは「もっと多くコードを読め」という話ではありません。  \n> もっと狭い問題を解決します。\n>\n> **章順が安定したあと、このリポジトリのコードをどんな順で読めば心智モデルを崩さずに理解できるのか。**\n\n## 先に結論\n\n次の読み方は避けます。\n\n- いちばん長いファイルから読む\n- いちばん高度そうな章へ飛ぶ\n- 先に `web/` を開いて主線を逆算する\n- `agents/*.py` 全体を 1 つの平坦なソース群として眺める\n\n安定したルールは 1 つです。\n\n**コードもカリキュラムと同じ順番で読む。**\n\n各章ファイルの中では、毎回同じ順で読みます。\n\n1. 状態構造\n2. tool 定義や registry\n3. 1 ターンを進める関数\n4. CLI 入口は最後\n\n## なぜこのページが必要か\n\n読者が詰まるのは文章だけではありません。実際にコードを開いた瞬間に、間違った場所から読み始めてまた混ざることが多いからです。\n\n## どの agent ファイルでも同じテンプレートで読む\n\n### 1. まずファイル先頭\n\n最初に答えること:\n\n- この章は何を教えているか\n- まだ何を故意に教えていないか\n\n### 2. 状態構造や manager class\n\n優先して探すもの:\n\n- `LoopState`\n- `PlanningState`\n- `CompactState`\n- `TaskManager`\n- `BackgroundManager`\n- `TeammateManager`\n- `WorktreeManager`\n\n### 3. tool 一覧や registry\n\n優先して見る入口:\n\n- `TOOLS`\n- `TOOL_HANDLERS`\n- `build_tool_pool()`\n- 主要な `run_*`\n\n### 4. ターンを進める関数\n\nたとえば:\n\n- `run_one_turn(...)`\n- `agent_loop(...)`\n- 章固有の `handle_*`\n\n### 5. CLI 入口は最後\n\n`if __name__ == \"__main__\"` は大事ですが、最初に見る場所ではありません。\n\n## Stage 1: `s01-s06`\n\nこの段階は single-agent の背骨です。\n\n| 章 | ファイル | 先に見るもの | 次に見るもの | 次へ進む前に確認すること |\n|---|---|---|---|---|\n| `s01` | `agents/s01_agent_loop.py` | `LoopState` | `TOOLS` -> `run_one_turn()` -> `agent_loop()` | `messages -> model -> tool_result -> next turn` を追える |\n| `s02` | `agents/s02_tool_use.py` | `safe_path()` | handler 群 -> `TOOL_HANDLERS` -> `agent_loop()` | ループを変えずに tool が増える形が分かる |\n| `s03` | `agents/s03_todo_write.py` | planning state | todo 更新経路 -> `agent_loop()` | 会話内 plan の外化が分かる |\n| `s04` | `agents/s04_subagent.py` | `AgentTemplate` | `run_subagent()` -> 親 `agent_loop()` | 文脈隔離としての subagent が分かる |\n| `s05` | `agents/s05_skill_loading.py` | skill registry | registry 周り -> `agent_loop()` | discover light / load deep が分かる |\n| `s06` | `agents/s06_context_compact.py` | `CompactState` | compact 周辺 -> `agent_loop()` | compact の本質が分かる |\n\n## Stage 2: `s07-s11`\n\nここは control plane を固める段階です。\n\n| 章 | ファイル | 先に見るもの | 次に見るもの | 次へ進む前に確認すること |\n|---|---|---|---|---|\n| `s07` | `agents/s07_permission_system.py` | validator / manager | permission path -> `agent_loop()` | gate before execute |\n| `s08` | `agents/s08_hook_system.py` | `HookManager` | hook dispatch -> `agent_loop()` | 固定拡張点としての hook |\n| `s09` | `agents/s09_memory_system.py` | memory manager | save / prompt build -> `agent_loop()` | 長期情報層としての memory |\n| `s10` | `agents/s10_system_prompt.py` | `SystemPromptBuilder` | input build -> `agent_loop()` | pipeline としての prompt |\n| `s11` | `agents/s11_error_recovery.py` | compact / backoff helper | recovery 分岐 -> `agent_loop()` | 失敗後の続行 |\n\n## Stage 3: `s12-s14`\n\nここから harness は work runtime へ広がります。\n\n| 章 | ファイル | 先に見るもの | 次に見るもの | 次へ進む前に確認すること |\n|---|---|---|---|---|\n| `s12` | `agents/s12_task_system.py` | `TaskManager` | task create / unlock -> `agent_loop()` | durable goal |\n| `s13` | `agents/s13_background_tasks.py` | `NotificationQueue` / `BackgroundManager` | background registration -> `agent_loop()` | runtime slot |\n| `s14` | `agents/s14_cron_scheduler.py` | `CronLock` / `CronScheduler` | trigger path -> `agent_loop()` | 未来の開始条件 |\n\n## Stage 4: `s15-s19`\n\nここは platform 境界を作る段階です。\n\n| 章 | ファイル | 先に見るもの | 次に見るもの | 次へ進む前に確認すること |\n|---|---|---|---|---|\n| `s15` | `agents/s15_agent_teams.py` | `MessageBus` / `TeammateManager` | roster / inbox / loop -> `agent_loop()` | persistent teammate |\n| `s16` | `agents/s16_team_protocols.py` | `RequestStore` | request handler -> `agent_loop()` | request-response + `request_id` |\n| `s17` | `agents/s17_autonomous_agents.py` | claim helper / identity helper | claim -> resume -> `agent_loop()` | idle check -> safe claim -> resume |\n| `s18` | `agents/s18_worktree_task_isolation.py` | manager 群 | worktree lifecycle -> `agent_loop()` | goal と execution lane の分離 |\n| `s19` | `agents/s19_mcp_plugin.py` | capability 周辺 class | route / normalize -> `agent_loop()` | external capability が同じ control plane に戻ること |\n\n## 最良の「文書 + コード」学習ループ\n\n各章で次を繰り返します。\n\n1. 章本文を読む\n2. bridge doc を読む\n3. 対応する `agents/sXX_*.py` を開く\n4. 状態 -> tools -> turn driver -> CLI 入口 の順で読む\n5. demo を 1 回動かす\n6. 最小版を自分で書き直す\n\n## 一言で言うと\n\n**コード読解順も教学順に従うべきです。まず境界、その次に状態、最後に主ループをどう進めるかを見ます。**\n"
  },
  {
    "version": "s01",
    "slug": "s01-the-agent-loop",
    "locale": "ja",
    "title": "s01: The Agent Loop",
    "kind": "chapter",
    "filename": "s01-the-agent-loop.md",
    "content": "# s01: The Agent Loop\n\n`s00 > [ s01 ] > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *loop がなければ agent は生まれません。*  \n> この章では、最小だけれど正しい loop を先に作り、そのあとで「なぜ後ろの章で control plane が必要になるのか」を理解できる土台を作ります。\n\n## この章が解く問題\n\n言語 model 自体は「次にどんな文字列を出すか」を予測する存在です。\n\nそれだけでは自分で次のことはできません。\n\n- file を開く\n- command を実行する\n- error を観察する\n- その観察結果を次の判断へつなぐ\n\nもし system 側に次の流れを繰り返す code がなければ、\n\n```text\nmodel に聞く\n  ->\ntool を使いたいと言う\n  ->\n本当に実行する\n  ->\n結果を model へ戻す\n  ->\n次の一手を考えさせる\n```\n\nmodel は「会話できる program」に留まり、「仕事を進める agent」にはなりません。\n\nだからこの章の目標は 1 つです。\n\n**model と tool を閉ループに接続し、仕事を継続的に前へ進める最小 agent を作ること**\n\nです。\n\n## 先に言葉をそろえる\n\n### loop とは何か\n\nここでの `loop` は「無意味な無限ループ」ではありません。\n\n意味は、\n\n> 仕事がまだ終わっていない限り、同じ処理手順を繰り返す主循環\n\nです。\n\n### turn とは何か\n\n`turn` は 1 ラウンドです。\n\n最小版では 1 turn にだいたい次が入ります。\n\n1. 現在の messages を model に送る\n2. model response を受け取る\n3. tool_use があれば tool を実行する\n4. tool_result を messages に戻す\n\nそのあとで次の turn へ進むか、終了するかが決まります。\n\n### tool_result とは何か\n\n`tool_result` は terminal 上の一時ログではありません。\n\n正しくは、\n\n> model が次の turn で読めるよう、message history へ書き戻される結果 block\n\nです。\n\n### state とは何か\n\n`state` は、その loop が前へ進むために持ち続ける情報です。\n\nこの章の最小 state は次です。\n\n- `messages`\n- `turn_count`\n- 次 turn に続く理由\n\n## 最小心智モデル\n\nまず agent 全体を次の回路として見てください。\n\n```text\nuser message\n   |\n   v\nLLM\n   |\n   +-- 普通の返答 ----------> 終了\n   |\n   +-- tool_use ----------> tool 実行\n                              |\n                              v\n                         tool_result\n                              |\n                              v\n                         messages へ write-back\n                              |\n                              v\n                         次の turn\n```\n\nこの図の中で一番重要なのは `while True` という文法ではありません。\n\n最も重要なのは次の 1 文です。\n\n**tool の結果は message history に戻され、次の推論入力になる**\n\nここが欠けると、model は現実の観察を踏まえて次の一手を考えられません。\n\n## この章の核になるデータ構造\n\n### 1. Message\n\n最小教材版では、message はまず次の形で十分です。\n\n```python\n{\"role\": \"user\", \"content\": \"...\"}\n{\"role\": \"assistant\", \"content\": [...]}\n```\n\nここで忘れてはいけないのは、\n\n**message history は UI 表示用の chat transcript ではなく、次 turn の作業 context**\n\nだということです。\n\n### 2. Tool Result Block\n\ntool 実行後は、その出力を対応する block として messages へ戻します。\n\n```python\n{\n    \"type\": \"tool_result\",\n    \"tool_use_id\": \"...\",\n    \"content\": \"...\",\n}\n```\n\n`tool_use_id` は単純に、\n\n> どの tool 呼び出しに対応する結果か\n\nを model に示すための ID です。\n\n### 3. LoopState\n\nこの章では散らばった local variable だけで済ませるより、\n\n> loop が持つ state を 1 か所へ寄せて見る\n\n癖を作る方が後で効きます。\n\n最小形は次で十分です。\n\n```python\nstate = {\n    \"messages\": [...],\n    \"turn_count\": 1,\n    \"transition_reason\": None,\n}\n```\n\nここでの `transition_reason` はまず、\n\n> なぜこの turn のあとにさらに続くのか\n\nを示す field とだけ理解してください。\n\nこの章の最小版では、理由は 1 種類でも十分です。\n\n```python\n\"tool_result\"\n```\n\nつまり、\n\n> tool を実行したので、その結果を踏まえてもう一度 model を呼ぶ\n\nという continuation です。\n\n## 最小実装を段階で追う\n\n### 第 1 段階: 初期 message を作る\n\nまず user request を history に入れます。\n\n```python\nmessages = [{\"role\": \"user\", \"content\": query}]\n```\n\n### 第 2 段階: model を呼ぶ\n\nmessages、system prompt、tools をまとめて model に送ります。\n\n```python\nresponse = client.messages.create(\n    model=MODEL,\n    system=SYSTEM,\n    messages=messages,\n    tools=TOOLS,\n    max_tokens=8000,\n)\n```\n\n### 第 3 段階: assistant response 自体も history へ戻す\n\n```python\nmessages.append({\n    \"role\": \"assistant\",\n    \"content\": response.content,\n})\n```\n\nここは初心者がとても落としやすい点です。\n\n「最終答えだけ取れればいい」と思って assistant response を保存しないと、次 turn の context が切れます。\n\n### 第 4 段階: tool_use があればจริง行する\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この段階で初めて、model の意図が real execution へ落ちます。\n\n### 第 5 段階: tool_result を user-side message として write-back する\n\n```python\nmessages.append({\n    \"role\": \"user\",\n    \"content\": results,\n})\n```\n\nこれで次 turn の model は、\n\n- さっき自分が何を要求したか\n- その結果が何だったか\n\nを両方読めます。\n\n### 全体を 1 つの loop にまとめる\n\n```python\ndef agent_loop(state):\n    while True:\n        response = client.messages.create(\n            model=MODEL,\n            system=SYSTEM,\n            messages=state[\"messages\"],\n            tools=TOOLS,\n            max_tokens=8000,\n        )\n\n        state[\"messages\"].append({\n            \"role\": \"assistant\",\n            \"content\": response.content,\n        })\n\n        if response.stop_reason != \"tool_use\":\n            state[\"transition_reason\"] = None\n            return\n\n        results = []\n        for block in response.content:\n            if block.type == \"tool_use\":\n                output = run_tool(block)\n                results.append({\n                    \"type\": \"tool_result\",\n                    \"tool_use_id\": block.id,\n                    \"content\": output,\n                })\n\n        state[\"messages\"].append({\n            \"role\": \"user\",\n            \"content\": results,\n        })\n        state[\"turn_count\"] += 1\n        state[\"transition_reason\"] = \"tool_result\"\n```\n\nこれがこの course 全体の核です。\n\n後ろの章で何が増えても、\n\n**model を呼び、tool を実行し、result を戻して、必要なら続く**\n\nという骨格自体は残ります。\n\n## この章でわざと単純化していること\n\nこの章では最初から複雑な control plane を教えません。\n\nまだ出していないもの:\n\n- permission gate\n- hook\n- memory\n- prompt assembly pipeline\n- recovery branch\n- compact 後の continuation\n\nなぜなら初学者が最初に理解すべきなのは、\n\n**agent の最小閉ループ**\n\nだからです。\n\nもし最初から複数の continuation reason や recovery branch を混ぜると、\n読者は「loop そのもの」が見えなくなります。\n\n## 高完成度 system ではどう広がるか\n\n教材版は最も重要な骨格だけを教えます。\n\n高完成度 system では、その同じ loop の外側に次の層が足されます。\n\n| 観点 | この章の最小版 | 高完成度 system |\n|---|---|---|\n| loop 形状 | 単純な `while True` | event-driven / streaming continuation |\n| 継続理由 | `tool_result` が中心 | retry、compact resume、recovery など複数 |\n| tool execution | response 全体を見てから実行 | 並列実行や先行起動を含む runtime |\n| state | `messages` 中心 | turn、budget、transition、recovery を explicit に持つ |\n| error handling | ほぼなし | truncation、transport error、retry branch |\n| observability | 最小 | progress event、structured logs、UI stream |\n\nここで覚えるべき本質は細かな branch 名ではありません。\n\n本質は次の 1 文です。\n\n**agent は最後まで「結果を model に戻し続ける loop」であり、周囲に state 管理と continuation の理由が増えていく**\n\nということです。\n\n## この章を読み終えたら何が言えるべきか\n\n1. model だけでは agent にならず、tool result を戻す loop が必要\n2. assistant response 自体も history に残さないと次 turn が切れる\n3. tool_result は terminal log ではなく、次 turn の input block である\n\n## 一文で覚える\n\n**agent loop とは、model の要求を現実の観察へ変え、その観察をまた model に返し続ける主循環です。**\n"
  },
  {
    "version": "s02",
    "slug": "s02-tool-use",
    "locale": "ja",
    "title": "s02: Tool Use",
    "kind": "chapter",
    "filename": "s02-tool-use.md",
    "content": "# s02: Tool Use\n\n`s01 > [ s02 ] > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *\"ツールを足すなら、ハンドラーを1つ足すだけ\"* -- ループは変わらない。新ツールは dispatch map に登録するだけ。\n>\n> **Harness 層**: ツール分配 -- モデルが届く範囲を広げる。\n\n## 問題\n\n`bash`だけでは、エージェントは何でもシェル経由で行う。`cat`は予測不能に切り詰め、`sed`は特殊文字で壊れ、すべてのbash呼び出しが制約のないセキュリティ面になる。`read_file`や`write_file`のような専用ツールなら、ツールレベルでパスのサンドボックス化を強制できる。\n\n重要な点: ツールを追加してもループの変更は不要。\n\n## 解決策\n\n```\n+--------+      +-------+      +------------------+\n|  User  | ---> |  LLM  | ---> | Tool Dispatch    |\n| prompt |      |       |      | {                |\n+--------+      +---+---+      |   bash: run_bash |\n                    ^           |   read: run_read |\n                    |           |   write: run_wr  |\n                    +-----------+   edit: run_edit |\n                    tool_result | }                |\n                                +------------------+\n\nThe dispatch map is a dict: {tool_name: handler_function}.\nOne lookup replaces any if/elif chain.\n```\n\n## 仕組み\n\n1. 各ツールにハンドラ関数を定義する。パスのサンドボックス化でワークスペース外への脱出を防ぐ。\n\n```python\ndef safe_path(p: str) -> Path:\n    path = (WORKDIR / p).resolve()\n    if not path.is_relative_to(WORKDIR):\n        raise ValueError(f\"Path escapes workspace: {p}\")\n    return path\n\ndef run_read(path: str, limit: int = None) -> str:\n    text = safe_path(path).read_text()\n    lines = text.splitlines()\n    if limit and limit < len(lines):\n        lines = lines[:limit]\n    return \"\\n\".join(lines)[:50000]\n```\n\n2. ディスパッチマップがツール名とハンドラを結びつける。\n\n```python\nTOOL_HANDLERS = {\n    \"bash\":       lambda **kw: run_bash(kw[\"command\"]),\n    \"read_file\":  lambda **kw: run_read(kw[\"path\"], kw.get(\"limit\")),\n    \"write_file\": lambda **kw: run_write(kw[\"path\"], kw[\"content\"]),\n    \"edit_file\":  lambda **kw: run_edit(kw[\"path\"], kw[\"old_text\"],\n                                        kw[\"new_text\"]),\n}\n```\n\n3. ループ内で名前によりハンドラをルックアップする。ループ本体はs01から不変。\n\n```python\nfor block in response.content:\n    if block.type == \"tool_use\":\n        handler = TOOL_HANDLERS.get(block.name)\n        output = handler(**block.input) if handler \\\n            else f\"Unknown tool: {block.name}\"\n        results.append({\n            \"type\": \"tool_result\",\n            \"tool_use_id\": block.id,\n            \"content\": output,\n        })\n```\n\nツール追加 = ハンドラ追加 + スキーマ追加。ループは決して変わらない。\n\n## s01からの変更点\n\n| Component      | Before (s01)       | After (s02)                |\n|----------------|--------------------|----------------------------|\n| Tools          | 1 (bash only)      | 4 (bash, read, write, edit)|\n| Dispatch       | Hardcoded bash call | `TOOL_HANDLERS` dict       |\n| Path safety    | None               | `safe_path()` sandbox      |\n| Agent loop     | Unchanged          | Unchanged                  |\n\n## 試してみる\n\n```sh\ncd learn-claude-code\npython agents/s02_tool_use.py\n```\n\n1. `Read the file requirements.txt`\n2. `Create a file called greet.py with a greet(name) function`\n3. `Edit greet.py to add a docstring to the function`\n4. `Read greet.py to verify the edit worked`\n\n## 教学上の簡略化\n\nこの章で本当に学ぶべきなのは、細かな production 差分ではありません。\n\n学ぶべき中心は次の 4 点です。\n\n1. モデルに見せる tool schema がある\n2. 実装側には handler がある\n3. 両者は dispatch map で結ばれる\n4. 実行結果は `tool_result` として主ループへ戻る\n\nより完成度の高い system では、この周りに権限、hook、並列実行、結果永続化、外部 capability routing などが増えていきます。\n\nしかし、それらをここで全部追い始めると、初学者は\n\n- schema と handler の違い\n- dispatch map の役割\n- `tool_result` がなぜ主ループへ戻るのか\n\nという本章の主眼を見失いやすくなります。\n\nこの段階では、まず\n\n**新しい tool を足しても主ループ自体は作り替えなくてよい**\n\nという設計の強さを、自分で実装して理解できれば十分です。\n"
  },
  {
    "version": null,
    "slug": "s02a-tool-control-plane",
    "locale": "ja",
    "title": "s02a: Tool Control Plane",
    "kind": "bridge",
    "filename": "s02a-tool-control-plane.md",
    "content": "# s02a: Tool Control Plane\n\n> これは `s02` を深く理解するための橋渡し文書です。  \n> 問いたいのは:\n>\n> **なぜ tool system は単なる `tool_name -> handler` 表では足りないのか。**\n\n## 先に結論\n\n最小 demo では dispatch map だけでも動きます。\n\nしかし高完成度の system では tool layer は次の責任をまとめて持ちます。\n\n- tool schema をモデルへ見せる\n- tool 名から実行先を解決する\n- 実行前に permission を通す\n- hook / classifier / side check を差し込む\n- 実行中 progress を扱う\n- 結果を整形して loop へ戻す\n- 実行で変わる共有 state へアクセスする\n\nつまり tool layer は:\n\n**関数表ではなく、共有 execution plane**\n\nです。\n\n## 最小の心智モデル\n\n```text\nmodel emits tool_use\n  |\n  v\ntool spec lookup\n  |\n  v\npermission / hook / validation\n  |\n  v\nactual execution\n  |\n  v\ntool result shaping\n  |\n  v\nwrite-back to loop\n```\n\n## `dispatch map` だけでは足りない理由\n\n単なる map だと、せいぜい:\n\n- この名前ならこの関数\n\nしか表せません。\n\nでも実システムで必要なのは:\n\n- モデルへ何を見せるか\n- 実行前に何を確認するか\n- 実行中に何を表示するか\n- 実行後にどんな result block を返すか\n- どの shared context を触れるか\n\nです。\n\n## 主要なデータ構造\n\n### `ToolSpec`\n\nモデルに見せる tool の定義です。\n\n```python\ntool = {\n    \"name\": \"read_file\",\n    \"description\": \"...\",\n    \"input_schema\": {...},\n}\n```\n\n### `ToolDispatchMap`\n\n名前から handler を引く表です。\n\n```python\ndispatch = {\n    \"read_file\": run_read,\n    \"bash\": run_bash,\n}\n```\n\nこれは必要ですが、これだけでは足りません。\n\n### `ToolUseContext`\n\ntool が共有状態へ触るための文脈です。\n\nたとえば:\n\n- app state getter / setter\n- permission context\n- notifications\n- file-state cache\n- current agent identity\n\nなどが入ります。\n\n### `ToolResultEnvelope`\n\nloop へ返すときの整形済み result です。\n\n```python\n{\n    \"type\": \"tool_result\",\n    \"tool_use_id\": \"...\",\n    \"content\": \"...\",\n}\n```\n\n高完成度版では content だけでなく:\n\n- progress\n- warnings\n- structured result\n\nなども関わります。\n\n## 実行面として見ると何が変わるか\n\n### 1. Tool は「名前」ではなく「実行契約」になる\n\n1つの tool には:\n\n- 入力 schema\n- 実行権限\n- 実行時 context\n- 出力の形\n\nがひとまとまりで存在します。\n\n### 2. Permission と Hook の差が見えやすくなる\n\n- permission: 実行してよいか\n- hook: 実行の周辺で何を足すか\n\n### 3. Native / Task / Agent / MCP を同じ平面で見やすくなる\n\n参照実装でも重要なのは:\n\n**能力の出どころが違っても、loop から見れば 1 つの tool execution plane に入る**\n\nという点です。\n\n## 初学者がやりがちな誤り\n\n### 1. tool spec と handler を混同する\n\n- spec はモデル向け説明\n- handler は実行コード\n\n### 2. permission を handler の中へ埋め込む\n\nこれをやると gate が共有層にならず、system が読みにくくなります。\n\n### 3. result shaping を軽く見る\n\ntool 実行結果は「文字列が返ればよい」ではありません。\n\nloop が読み戻しやすい形に整える必要があります。\n\n### 4. 実行状態を `messages[]` だけで持とうとする\n\ntool 実行は app state や runtime state を触ることがあります。\n\n## 一文で覚える\n\n**tool system が本物らしくなるのは、名前から関数を呼べた瞬間ではなく、schema・gate・context・result を含む共有 execution plane として見えた瞬間です。**\n"
  },
  {
    "version": null,
    "slug": "s02b-tool-execution-runtime",
    "locale": "ja",
    "title": "s02b: Tool Execution Runtime",
    "kind": "bridge",
    "filename": "s02b-tool-execution-runtime.md",
    "content": "# s02b: Tool Execution Runtime\n\n> この bridge doc は tool の登録方法ではなく、次の問いを扱います。\n>\n> **model が複数の tool call を出したとき、何を基準に並列化し、進捗を出し、結果順を安定させ、context をマージするのか。**\n\n## なぜこの資料が必要か\n\n`s02` では正しく次を教えています。\n\n- tool schema\n- dispatch map\n- `tool_result` の main loop への回流\n\n出発点としては十分です。\n\nただしシステムが大きくなると、本当に難しくなるのはもっと深い層です。\n\n- どの tool は並列実行できるか\n- どの tool は直列でなければならないか\n- 遅い tool は途中 progress を出すべきか\n- 並列結果を完了順で返すのか、元の順序で返すのか\n- tool 実行が共有 context を変更するのか\n- 並列変更をどう安全にマージするのか\n\nこれらはもはや「登録」の話ではありません。\n\nそれは:\n\n**tool execution runtime**\n\nの話です。\n\n## まず用語\n\n### tool execution runtime とは\n\nここでの runtime は言語 runtime の意味ではありません。\n\nここでは:\n\n> tool call が実際に動き始めた後、システムがそれらをどう調度し、追跡し、回写するか\n\nという実行規則のことです。\n\n### concurrency safe とは\n\nconcurrency safe とは:\n\n> 同種の仕事と同時に走っても共有 state を壊しにくい\n\nという意味です。\n\nよくある read-only tool は安全なことが多いです。\n\n- `read_file`\n- いくつかの search tool\n- 読み取り専用の MCP tool\n\n一方で write 系は安全でないことが多いです。\n\n- `write_file`\n- `edit_file`\n- 共有 app state を変える tool\n\n### progress message とは\n\nprogress message とは:\n\n> tool はまだ終わっていないが、「今何をしているか」を先に上流へ見せる更新\n\nのことです。\n\n### context modifier とは\n\nある tool は text result だけでなく共有 runtime context も変更します。\n\n例えば:\n\n- notification queue を更新する\n- 実行中 tool の状態を更新する\n- app state を変更する\n\nこの共有 state 変更を context modifier と考えられます。\n\n## 最小の心智モデル\n\ntool 実行を次のように平坦化しないでください。\n\n```text\ntool_use -> handler -> result\n```\n\nより実像に近い理解は次です。\n\n```text\ntool_use blocks\n  ->\nconcurrency safety で partition\n  ->\n並列 lane か直列 lane を選ぶ\n  ->\n必要なら progress を吐く\n  ->\n安定順で結果を回写する\n  ->\nqueued context modifiers をマージする\n```\n\nここで大事なのは二つです。\n\n- 並列化は「全部まとめて走らせる」ではない\n- 共有 context は完了順で勝手に書き換えない\n\n## 主要 record\n\n### 1. `ToolExecutionBatch`\n\n教材版なら次の程度の batch 概念で十分です。\n\n```python\nbatch = {\n    \"is_concurrency_safe\": True,\n    \"blocks\": [tool_use_1, tool_use_2, tool_use_3],\n}\n```\n\n意味は単純です。\n\n- tool を常に 1 個ずつ扱うわけではない\n- runtime はまず execution batch に分ける\n\n### 2. `TrackedTool`\n\n完成度を上げたいなら各 tool を明示的に追跡します。\n\n```python\ntracked_tool = {\n    \"id\": \"toolu_01\",\n    \"name\": \"read_file\",\n    \"status\": \"queued\",   # queued / executing / completed / yielded\n    \"is_concurrency_safe\": True,\n    \"pending_progress\": [],\n    \"results\": [],\n    \"context_modifiers\": [],\n}\n```\n\nこれにより runtime は次に答えられます。\n\n- 何が待機中か\n- 何が実行中か\n- 何が完了したか\n- 何がすでに progress を出したか\n\n### 3. `MessageUpdate`\n\ntool 実行は最終結果 1 個だけを返すとは限りません。\n\n最小理解は次で十分です。\n\n```python\nupdate = {\n    \"message\": maybe_message,\n    \"new_context\": current_context,\n}\n```\n\n高完成度 runtime では、更新は通常二つに分かれます。\n\n- すぐ上流へ見せる message update\n- 後で merge すべき内部 context update\n\n### 4. queued context modifiers\n\nこれは見落とされやすいですが、とても重要です。\n\n並列 batch で安全なのは:\n\n> 先に終わった tool がその順で共有 context を先に変える\n\nことではありません。\n\nより安全なのは:\n\n> context modifier を一旦 queue し、最後に元の tool 順序で merge する\n\nことです。\n\n```python\nqueued_context_modifiers = {\n    \"toolu_01\": [modify_ctx_a],\n    \"toolu_02\": [modify_ctx_b],\n}\n```\n\n## 最小実装の進め方\n\n### Step 1: concurrency safety を判定する\n\n```python\ndef is_concurrency_safe(tool_name: str, tool_input: dict) -> bool:\n    return tool_name in {\"read_file\", \"search_files\"}\n```\n\n### Step 2: 実行前に partition する\n\n```python\nbatches = partition_tool_calls(tool_uses)\n\nfor batch in batches:\n    if batch[\"is_concurrency_safe\"]:\n        run_concurrently(batch[\"blocks\"])\n    else:\n        run_serially(batch[\"blocks\"])\n```\n\n### Step 3: 並列 lane では progress を先に出せるようにする\n\n```python\nfor update in run_concurrently(...):\n    if update.get(\"message\"):\n        yield update[\"message\"]\n```\n\n### Step 4: context merge は安定順で行う\n\n```python\nqueued_modifiers = {}\n\nfor update in concurrent_updates:\n    if update.get(\"context_modifier\"):\n        queued_modifiers[update[\"tool_id\"]].append(update[\"context_modifier\"])\n\nfor tool in original_batch_order:\n    for modifier in queued_modifiers.get(tool[\"id\"], []):\n        context = modifier(context)\n```\n\nここは教材 repo でも簡略化しすぎず、しかし主線を崩さずに教えられる重要点です。\n\n## 開発者が持つべき図\n\n```text\ntool_use blocks\n  |\n  v\npartition by concurrency safety\n  |\n  +-- safe batch ----------> concurrent execution\n  |                            |\n  |                            +-- progress updates\n  |                            +-- final results\n  |                            +-- queued context modifiers\n  |\n  +-- exclusive batch -----> serial execution\n                               |\n                               +-- direct result\n                               +-- direct context update\n```\n\n## なぜ後半では dispatch map より重要になるのか\n\n小さい demo では:\n\n```python\nhandlers[tool_name](tool_input)\n```\n\nで十分です。\n\nしかし高完成度 agent で本当に難しいのは、正しい handler を呼ぶことそのものではありません。\n\n難しいのは:\n\n- 複数 tool を安全に調度する\n- progress を見えるようにする\n- 結果順を安定させる\n- 共有 context を非決定的にしない\n\nだからこそ tool execution runtime は独立した bridge doc として教える価値があります。\n"
  },
  {
    "version": "s03",
    "slug": "s03-todo-write",
    "locale": "ja",
    "title": "s03: TodoWrite",
    "kind": "chapter",
    "filename": "s03-todo-write.md",
    "content": "# s03: TodoWrite\n\n`s00 > s01 > s02 > [ s03 ] > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *planning は model の代わりに考えるためのものではありません。いま何をやっているかを、外から見える state にするためのものです。*\n\n## この章が解く問題\n\n`s02` まで来ると agent はすでに、\n\n- file を読む\n- file を書く\n- command を実行する\n\nことができます。\n\nするとすぐに別の問題が出ます。\n\n- multi-step task で一歩前の確認を忘れる\n- もう終えた確認をまた繰り返す\n- 最初は計画しても、数 turn 後には即興に戻る\n\nこれは model が「考えられない」からではありません。\n\n問題は、\n\n**現在の plan を explicit に置いておく stable state がないこと**\n\nです。\n\nこの章で足すのはより強い tool ではなく、\n\n**今の session で何をどの順で進めているかを外部状態として見えるようにする仕組み**\n\nです。\n\n## 先に言葉をそろえる\n\n### session 内 planning とは何か\n\nここで扱う planning は long-term project management ではありません。\n\n意味は、\n\n> 今回の user request を終えるために、直近の数手を外へ書き出し、途中で更新し続けること\n\nです。\n\n### todo とは何か\n\n`todo` は特定 product の固有名詞として覚える必要はありません。\n\nこの章では単に、\n\n> model が current plan を更新するための入口\n\nとして使います。\n\n### active step とは何か\n\n`active step` は、\n\n> いま本当に進めている 1 手\n\nです。\n\n教材版では `in_progress` で表します。\n\nここで狙っているのは形式美ではなく、\n\n**同時にあれもこれも進めて plan をぼかさないこと**\n\nです。\n\n### reminder とは何か\n\nreminder は model の代わりに plan を作るものではありません。\n\n意味は、\n\n> 数 turn 連続で plan 更新を忘れたときに、軽く plan へ意識を戻すナッジ\n\nです。\n\n## 最初に強調したい境界\n\nこの章は task system ではありません。\n\n`s03` で扱うのは、\n\n- session 内の軽量な current plan\n- 進行中の focus を保つための外部状態\n- turn ごとに書き換わりうる planning panel\n\nです。\n\nここでまだ扱わないもの:\n\n- durable task board\n- dependency graph\n- multi-agent 共有 task graph\n- background runtime task manager\n\nそれらは `s12-s14` であらためて教えます。\n\nこの境界を守らないと、初心者はすぐに次を混同します。\n\n- 今この session で次にやる一手\n- system 全体に長く残る work goal\n\n## 最小心智モデル\n\nこの章を最も簡単に捉えるなら、plan はこういう panel です。\n\n```text\nuser が大きな仕事を頼む\n  |\n  v\nmodel が今の plan を書き出す\n  |\n  v\nplan state\n  - [ ] まだ着手していない\n  - [>] いま進めている\n  - [x] 完了した\n  |\n  v\n1 手進むたびに更新する\n```\n\nつまり流れはこうです。\n\n1. まず current work を数手に割る\n2. 1 つを `in_progress` にする\n3. 終わったら `completed` にする\n4. 次の 1 つを `in_progress` にする\n5. しばらく更新がなければ reminder する\n\nこの 5 手が見えていれば、この章の幹はつかめています。\n\n## この章の核になるデータ構造\n\n### 1. PlanItem\n\n最小の item は次のように考えられます。\n\n```python\n{\n    \"content\": \"Read the failing test\",\n    \"status\": \"pending\" | \"in_progress\" | \"completed\",\n    \"activeForm\": \"Reading the failing test\",\n}\n```\n\n意味は単純です。\n\n- `content`: 何をするか\n- `status`: いまどの段階か\n- `activeForm`: 実行中に自然文でどう見せるか\n\n教材コードによっては `id` や `text` を使っていても本質は同じです。\n\n### 2. PlanningState\n\nitem だけでは足りません。\n\nplan 全体には最低限、次の running state も要ります。\n\n```python\n{\n    \"items\": [...],\n    \"rounds_since_update\": 0,\n}\n```\n\n`rounds_since_update` の意味は、\n\n> 何 turn 連続で plan が更新されていないか\n\nです。\n\nこの値があるから reminder を出せます。\n\n### 3. 状態制約\n\n教材版では次の制約を置くのが有効です。\n\n```text\n同時に in_progress は最大 1 つ\n```\n\nこれは宇宙の真理ではありません。  \nでも初学者にとっては非常に良い制約です。\n\n理由は単純で、\n\n**current focus を system 側から明示できる**\n\nからです。\n\n## 最小実装を段階で追う\n\n### 第 1 段階: plan manager を用意する\n\n```python\nclass TodoManager:\n    def __init__(self):\n        self.items = []\n```\n\n最初はこれで十分です。\n\nここで導入したいのは UI ではなく、\n\n> plan を model の頭の中ではなく harness 側の state として持つ\n\nという発想です。\n\n### 第 2 段階: plan 全体を更新できるようにする\n\n教材版では item をちまちま差分更新するより、\n\n**現在の plan を丸ごと更新する**\n\n方が理解しやすいです。\n\n```python\ndef update(self, items: list) -> str:\n    validated = []\n    in_progress_count = 0\n\n    for item in items:\n        status = item.get(\"status\", \"pending\")\n        if status == \"in_progress\":\n            in_progress_count += 1\n\n        validated.append({\n            \"content\": item[\"content\"],\n            \"status\": status,\n            \"activeForm\": item.get(\"activeForm\", \"\"),\n        })\n\n    if in_progress_count > 1:\n        raise ValueError(\"Only one item can be in_progress\")\n\n    self.items = validated\n    return self.render()\n```\n\nここでやっていることは 2 つです。\n\n- current plan を受け取る\n- 状態制約をチェックする\n\n### 第 3 段階: render して可読にする\n\n```python\ndef render(self) -> str:\n    lines = []\n    for item in self.items:\n        marker = {\n            \"pending\": \"[ ]\",\n            \"in_progress\": \"[>]\",\n            \"completed\": \"[x]\",\n        }[item[\"status\"]]\n        lines.append(f\"{marker} {item['content']}\")\n    return \"\\n\".join(lines)\n```\n\nrender の価値は見た目だけではありません。\n\nplan が text として安定して見えることで、\n\n- user が current progress を理解しやすい\n- model も自分が何をどこまで進めたか確認しやすい\n\n状態になります。\n\n### 第 4 段階: `todo` を 1 つの tool として loop へ接ぐ\n\n```python\nTOOL_HANDLERS = {\n    \"read_file\": run_read,\n    \"write_file\": run_write,\n    \"edit_file\": run_edit,\n    \"bash\": run_bash,\n    \"todo\": lambda **kw: TODO.update(kw[\"items\"]),\n}\n```\n\nここで重要なのは、plan 更新を特別扱いの hidden logic にせず、\n\n**tool call として explicit に loop へ入れる**\n\nことです。\n\n### 第 5 段階: 数 turn 更新がなければ reminder を挿入する\n\n```python\nif rounds_since_update >= 3:\n    results.insert(0, {\n        \"type\": \"text\",\n        \"text\": \"<reminder>Refresh your plan before continuing.</reminder>\",\n    })\n```\n\nこの reminder の意味は「system が代わりに plan を立てる」ではありません。\n\n正しくは、\n\n> plan state がしばらく stale なので、model に current plan を更新させる\n\nです。\n\n## main loop に何が増えるのか\n\nこの章以後、main loop は `messages` だけを持つわけではなくなります。\n\n持つ state が少なくとも 2 本になります。\n\n```text\nmessages\n  -> model が読む会話と観察の history\n\nplanning state\n  -> 今回の session で current work をどう進めるか\n```\n\nこれがこの章の本当の upgrade です。\n\nagent はもはや単に chat history を伸ばしているだけではなく、\n\n**「いま何をしているか」を外から見える panel として維持する**\n\nようになります。\n\n## なぜここで task graph まで教えないのか\n\n初心者は planning の話が出るとすぐ、\n\n> だったら durable task board も同時に作った方がよいのでは\n\nと考えがちです。\n\nでも教学順序としては早すぎます。\n\n理由は、ここで理解してほしいのが\n\n**session 内の軽い plan と、長く残る durable work graph は別物**\n\nという境界だからです。\n\n`s03` は current focus の外部化です。  \n`s12` 以降は durable task system です。\n\n順番を守ると、後で混ざりにくくなります。\n\n## 初学者が混ぜやすいポイント\n\n### 1. plan を model の頭の中だけに置く\n\nこれでは multi-step work がすぐ漂います。\n\n### 2. `in_progress` を複数許してしまう\n\ncurrent focus がぼやけ、plan が checklist ではなく wish list になります。\n\n### 3. plan を一度書いたら更新しない\n\nそれでは plan は living state ではなく dead note です。\n\n### 4. reminder を system の強制 planning と誤解する\n\nreminder は軽いナッジであって、plan の中身を system が代行するものではありません。\n\n### 5. session plan と durable task graph を同一視する\n\nこの章で扱うのは current request を進めるための軽量 state です。\n\n## この章を読み終えたら何が言えるべきか\n\n1. planning は model の代わりに考えることではなく、current progress を外部 state にすること\n2. session plan は durable task system とは別層であること\n3. `in_progress` を 1 つに絞ると初心者の心智が安定すること\n\n## 一文で覚える\n\n**TodoWrite とは、「次に何をするか」を model の頭の中ではなく、system が見える外部 state に書き出すことです。**\n"
  },
  {
    "version": "s04",
    "slug": "s04-subagent",
    "locale": "ja",
    "title": "s04: Subagents",
    "kind": "chapter",
    "filename": "s04-subagent.md",
    "content": "# s04: Subagents\n\n`s00 > s01 > s02 > s03 > [ s04 ] > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *大きな仕事を全部 1 つの context に詰め込む必要はありません。*  \n> subagent の価値は「model を 1 個増やすこと」ではなく、「clean な別 context を 1 つ持てること」にあります。\n\n## この章が解く問題\n\nagent がいろいろな調査や実装を進めると、親の `messages` はどんどん長くなります。\n\nたとえば user の質問が単に\n\n> 「この project は何の test framework を使っているの？」\n\nだけでも、親 agent は答えるために、\n\n- `pyproject.toml` を読む\n- `requirements.txt` を読む\n- `pytest` を検索する\n- 実際に test command を走らせる\n\nかもしれません。\n\nでも本当に親に必要な最終答えは、\n\n> 「主に `pytest` を使っています」\n\nの一文だけかもしれません。\n\nもしこの途中作業を全部親 context に積み続けると、あとで別の質問に答えるときに、\n\n- さっきの局所調査の noise\n- 大量の file read\n- 一時的な bash 出力\n\nが main context を汚染します。\n\nsubagent が解くのはこの問題です。\n\n**局所 task を別 context に閉じ込め、親には必要な summary だけを持ち帰る**\n\nのがこの章の主線です。\n\n## 先に言葉をそろえる\n\n### 親 agent とは何か\n\nいま user と直接やり取りし、main `messages` を持っている actor が親 agent です。\n\n### 子 agent とは何か\n\n親が一時的に派生させ、特定の subtask だけを処理させる actor が子 agent、つまり subagent です。\n\n### context isolation とは何か\n\nこれは単に、\n\n- 親は親の `messages`\n- 子は子の `messages`\n\nを持ち、\n\n> 子の途中経過が自動で親 history に混ざらないこと\n\nを指します。\n\n## 最小心智モデル\n\nこの章は次の図でほぼ言い切れます。\n\n```text\nParent agent\n  |\n  | 1. 局所 task を外へ出すと決める\n  v\nSubagent\n  |\n  | 2. 自分の context で file read / search / tool execution\n  v\nSummary\n  |\n  | 3. 必要な結果だけを親へ返す\n  v\nParent agent continues\n```\n\nここで一番大事なのは次の 1 文です。\n\n**subagent の価値は別 model instance ではなく、別 state boundary にある**\n\nということです。\n\n## 最小実装を段階で追う\n\n### 第 1 段階: 親に `task` tool を持たせる\n\n親 agent は model が明示的に言える入口を持つ必要があります。\n\n> この局所仕事は clean context に外注したい\n\nその最小 schema は非常に簡単で構いません。\n\n```python\n{\n    \"name\": \"task\",\n    \"description\": \"Run a subtask in a clean context and return a summary.\",\n    \"input_schema\": {\n        \"type\": \"object\",\n        \"properties\": {\n            \"prompt\": {\"type\": \"string\"}\n        },\n        \"required\": [\"prompt\"]\n    }\n}\n```\n\n### 第 2 段階: subagent は自分専用の `messages` で始める\n\nsubagent の本体はここです。\n\n```python\ndef run_subagent(prompt: str) -> str:\n    sub_messages = [{\"role\": \"user\", \"content\": prompt}]\n    ...\n```\n\n親の `messages` をそのまま共有しないことが、最小の isolation です。\n\n### 第 3 段階: 子に渡す tool は絞る\n\nsubagent は親と完全に同じ tool set を持つ必要はありません。\n\nむしろ最初は絞った方がよいです。\n\nたとえば、\n\n- `read_file`\n- 検索系 tool\n- read-only 寄りの `bash`\n\nだけを持たせ、\n\n- さらに `task` 自体は子に渡さない\n\nようにすれば、無限再帰を避けやすくなります。\n\n### 第 4 段階: 子は最後に summary だけ返す\n\n一番大事なのはここです。\n\nsubagent は内部 history を親に全部戻しません。\n\n戻すのは必要な summary だけです。\n\n```python\nreturn {\n    \"type\": \"tool_result\",\n    \"tool_use_id\": block.id,\n    \"content\": summary_text,\n}\n```\n\nこれにより親 context は、\n\n- 必要な答え\n- もしくは短い結論\n\nだけを保持し、局所ノイズから守られます。\n\n## この章の核になるデータ構造\n\nこの章で 1 つだけ覚えるなら、次の骨格です。\n\n```python\nclass SubagentContext:\n    messages: list\n    tools: list\n    handlers: dict\n    max_turns: int\n```\n\n意味は次の通りです。\n\n- `messages`: 子自身の context\n- `tools`: 子が使える道具\n- `handlers`: その tool が実際にどの code を呼ぶか\n- `max_turns`: 子が無限に走り続けないための上限\n\nつまり subagent は「関数呼び出し」ではなく、\n\n**自分の state と tool boundary を持つ小さな agent**\n\nです。\n\n## なぜ本当に useful なのか\n\n### 1. 親 context を軽く保てる\n\n局所 task の途中経過が main conversation に積み上がりません。\n\n### 2. subtask の prompt を鋭くできる\n\n子に渡す prompt は次のように非常に集中できます。\n\n- 「この directory の test framework を 1 文で答えて」\n- 「この file の bug を探して原因だけ返して」\n- 「3 file を読んで module 関係を summary して」\n\n### 3. 後の multi-agent chapter の準備になる\n\nsubagent は long-lived teammate より前に学ぶべき最小の delegation model です。\n\nまず「1 回限りの clean delegation」を理解してから、\n\n- persistent teammate\n- structured protocol\n- autonomous claim\n\nへ進むと心智がずっと滑らかになります。\n\n## 0-to-1 の実装順序\n\n### Version 1: blank-context subagent\n\n最初はこれで十分です。\n\n- `task` tool\n- `run_subagent(prompt)`\n- 子専用 `messages`\n- 最後に summary を返す\n\n### Version 2: tool set を制限する\n\n親より小さく安全な tool set を渡します。\n\n### Version 3: safety bound を足す\n\n最低限、\n\n- 最大 turn 数\n- tool failure 時の終了条件\n\nは入れてください。\n\n### Version 4: fork を検討する\n\nこの順番を守ることが大事です。\n\n最初から fork を入れる必要はありません。\n\n## fork とは何か、なぜ「次の段階」なのか\n\n最小 subagent は blank context から始めます。\n\nでも subtask によっては、親が直前まで話していた内容を知らないと困ることがあります。\n\nたとえば、\n\n> 「さっき決めた方針に沿って、この module へ test を追加して」\n\nのような場面です。\n\nそのとき使うのが `fork` です。\n\n```python\nsub_messages = list(parent_messages)\nsub_messages.append({\"role\": \"user\", \"content\": prompt})\n```\n\nfork の本質は、\n\n**空白から始めるのではなく、親の既存 context を引き継いで子を始めること**\n\nです。\n\nただし teaching order としては、blank-context subagent を理解してからの方が安全です。\n\n先に fork を入れると、初心者は\n\n- 何が isolation で\n- 何が inherited context なのか\n\nを混ぜやすくなります。\n\n## 初学者が混ぜやすいポイント\n\n### 1. subagent を「並列アピール機能」だと思う\n\nsubagent の第一目的は concurrency 自慢ではなく、context hygiene です。\n\n### 2. 子の history を全部親へ戻してしまう\n\nそれでは isolation の価値がほとんど消えます。\n\n### 3. 最初から役割を増やしすぎる\n\nexplorer、reviewer、planner、tester などを一気に作る前に、\n\n**clean context の一回限り worker**\n\nを正しく作る方が先です。\n\n### 4. 子に `task` を持たせて無限に spawn させる\n\n境界がないと recursion で system が荒れます。\n\n### 5. `max_turns` のような safety bound を持たない\n\n局所 task だからこそ、終わらない子を放置しない設計が必要です。\n\n## この章を読み終えたら何が言えるべきか\n\n1. subagent の価値は clean context を作ることにある\n2. 子は親と別の `messages` を持つべきである\n3. 親へ戻すのは内部 history 全量ではなく summary でよい\n\n## 一文で覚える\n\n**Subagent とは、局所 task を clean context へ切り出し、親には必要な結論だけを持ち帰るための最小 delegation mechanism です。**\n"
  },
  {
    "version": "s05",
    "slug": "s05-skill-loading",
    "locale": "ja",
    "title": "s05: Skills",
    "kind": "chapter",
    "filename": "s05-skill-loading.md",
    "content": "# s05: Skills\n\n`s01 > s02 > s03 > s04 > [ s05 ] > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *\"必要な知識を、必要な時に読み込む\"* -- system prompt ではなく tool_result で注入。\n>\n> **Harness 層**: オンデマンド知識 -- モデルが求めた時だけ渡すドメイン専門性。\n\n## 問題\n\nエージェントにドメイン固有のワークフローを遵守させたい: gitの規約、テストパターン、コードレビューチェックリスト。すべてをシステムプロンプトに入れると、使われないスキルにトークンを浪費する。10スキル x 2000トークン = 20,000トークン、ほとんどが任意のタスクに無関係だ。\n\n## 解決策\n\n```\nSystem prompt (Layer 1 -- always present):\n+--------------------------------------+\n| You are a coding agent.              |\n| Skills available:                    |\n|   - git: Git workflow helpers        |  ~100 tokens/skill\n|   - test: Testing best practices     |\n+--------------------------------------+\n\nWhen model calls load_skill(\"git\"):\n+--------------------------------------+\n| tool_result (Layer 2 -- on demand):  |\n| <skill name=\"git\">                   |\n|   Full git workflow instructions...  |  ~2000 tokens\n|   Step 1: ...                        |\n| </skill>                             |\n+--------------------------------------+\n```\n\n第1層: スキル*名*をシステムプロンプトに(低コスト)。第2層: スキル*本体*をtool_resultに(オンデマンド)。\n\n## 仕組み\n\n1. 各スキルは `SKILL.md` ファイルを含むディレクトリとして配置される。\n\n```\nskills/\n  pdf/\n    SKILL.md       # ---\\n name: pdf\\n description: Process PDF files\\n ---\\n ...\n  code-review/\n    SKILL.md       # ---\\n name: code-review\\n description: Review code\\n ---\\n ...\n```\n\n2. SkillLoaderが `SKILL.md` を再帰的に探索し、ディレクトリ名をスキル識別子として使用する。\n\n```python\nclass SkillLoader:\n    def __init__(self, skills_dir: Path):\n        self.skills = {}\n        for f in sorted(skills_dir.rglob(\"SKILL.md\")):\n            text = f.read_text()\n            meta, body = self._parse_frontmatter(text)\n            name = meta.get(\"name\", f.parent.name)\n            self.skills[name] = {\"meta\": meta, \"body\": body}\n\n    def get_descriptions(self) -> str:\n        lines = []\n        for name, skill in self.skills.items():\n            desc = skill[\"meta\"].get(\"description\", \"\")\n            lines.append(f\"  - {name}: {desc}\")\n        return \"\\n\".join(lines)\n\n    def get_content(self, name: str) -> str:\n        skill = self.skills.get(name)\n        if not skill:\n            return f\"Error: Unknown skill '{name}'.\"\n        return f\"<skill name=\\\"{name}\\\">\\n{skill['body']}\\n</skill>\"\n```\n\n3. 第1層はシステムプロンプトに配置。第2層は通常のツールハンドラ。\n\n```python\nSYSTEM = f\"\"\"You are a coding agent at {WORKDIR}.\nSkills available:\n{SKILL_LOADER.get_descriptions()}\"\"\"\n\nTOOL_HANDLERS = {\n    # ...base tools...\n    \"load_skill\": lambda **kw: SKILL_LOADER.get_content(kw[\"name\"]),\n}\n```\n\nモデルはどのスキルが存在するかを知り(低コスト)、関連する時にだけ読み込む(高コスト)。\n\n## s04からの変更点\n\n| Component      | Before (s04)     | After (s05)                |\n|----------------|------------------|----------------------------|\n| Tools          | 5 (base + task)  | 5 (base + load_skill)      |\n| System prompt  | Static string    | + skill descriptions       |\n| Knowledge      | None             | skills/\\*/SKILL.md files   |\n| Injection      | None             | Two-layer (system + result)|\n\n## 試してみる\n\n```sh\ncd learn-claude-code\npython agents/s05_skill_loading.py\n```\n\n1. `What skills are available?`\n2. `Load the agent-builder skill and follow its instructions`\n3. `I need to do a code review -- load the relevant skill first`\n4. `Build an MCP server using the mcp-builder skill`\n\n## 高完成度システムではどう広がるか\n\nこの章の核心は 2 層モデルです。  \nまず軽い一覧で「何があるか」を知らせ、必要になったときだけ本文を深く読み込む。これはそのまま有効です。\n\nより完成度の高いシステムでは、その周りに次のような広がりが出ます。\n\n| 観点 | 教材版 | 高完成度システム |\n|------|--------|------------------|\n| 発見レイヤー | プロンプト内に名前一覧 | 予算付きの専用インベントリやリマインダ面 |\n| 読み込み | `load_skill` が本文を返す | 同じ文脈へ注入、別ワーカーで実行、補助コンテキストとして添付など |\n| ソース | `skills/` ディレクトリのみ | user、project、bundled、plugin、外部ソースなど |\n| 適用範囲 | 常に見える | タスク種別、触ったファイル、明示指示に応じて有効化 |\n| 引数 | なし | スキルへパラメータやテンプレート値を渡せる |\n| ライフサイクル | 一度読むだけ | compact や再開後に復元されることがある |\n| ガードレール | なし | スキルごとの許可範囲や行動制約を持てる |\n\n教材としては、2 層モデルだけで十分です。  \nここで学ぶべき本質は：\n\n**専門知識は最初から全部抱え込まず、必要な時だけ深く読み込む**  \nという設計です。\n"
  },
  {
    "version": "s06",
    "slug": "s06-context-compact",
    "locale": "ja",
    "title": "s06: Context Compact",
    "kind": "chapter",
    "filename": "s06-context-compact.md",
    "content": "# s06: Context Compact\n\n`s01 > s02 > s03 > s04 > s05 > [ s06 ] > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *\"コンテキストはいつか溢れる、空ける手段が要る\"* -- 4レバー圧縮で無限セッションを実現。\n\n## 問題\n\nコンテキストウィンドウは有限だ。1000行のファイルに対する`read_file`1回で約4000トークンを消費する。30ファイルを読み20回のbashコマンドを実行すると、100,000トークン超。圧縮なしでは、エージェントは大規模コードベースで作業できない。\n\n## 解決策\n\nツール出力時から手動トリガーまで、4つの圧縮レバー:\n\n```\nEvery tool call:\n+------------------+\n| Tool call result |\n+------------------+\n        |\n        v\n[Lever 0: persisted-output]     (at tool execution time)\n  Large outputs (>50KB, bash >30KB) are written to disk\n  and replaced with a <persisted-output> preview marker.\n        |\n        v\n[Lever 1: micro_compact]        (silent, every turn)\n  Replace tool_result > 3 turns old\n  with \"[Previous: used {tool_name}]\"\n  (preserves read_file results as reference material)\n        |\n        v\n[Check: tokens > 50000?]\n   |               |\n   no              yes\n   |               |\n   v               v\ncontinue    [Lever 2: auto_compact]\n              Save transcript to .transcripts/\n              LLM summarizes conversation.\n              Replace all messages with [summary].\n                    |\n                    v\n            [Lever 3: compact tool]\n              Model calls compact explicitly.\n              Same summarization as auto_compact.\n```\n\n## 仕組み\n\n0. **レバー 0 -- persisted-output**: ツール出力がサイズ閾値を超えた場合、ディスクに書き込みプレビューマーカーに置換する。巨大な出力がコンテキストウィンドウに入るのを防ぐ。\n\n```python\nPERSIST_OUTPUT_TRIGGER_CHARS_DEFAULT = 50000\nPERSIST_OUTPUT_TRIGGER_CHARS_BASH = 30000   # bashはより低い閾値を使用\n\ndef maybe_persist_output(tool_use_id, output, trigger_chars=None):\n    if len(output) <= trigger:\n        return output\n    stored_path = _persist_tool_result(tool_use_id, output)\n    return _build_persisted_marker(stored_path, output)\n    # Returns: <persisted-output>\n    #   Output too large (48.8KB). Full output saved to: .task_outputs/tool-results/abc123.txt\n    #   Preview (first 2.0KB):\n    #   ... first 2000 chars ...\n    # </persisted-output>\n```\n\nモデルは後から`read_file`で保存パスにアクセスし、完全な内容を取得できる。\n\n1. **レバー 1 -- micro_compact**: 各LLM呼び出しの前に、古いツール結果をプレースホルダーに置換する。`read_file`の結果は参照資料として保持する。\n\n```python\nPRESERVE_RESULT_TOOLS = {\"read_file\"}\n\ndef micro_compact(messages: list) -> list:\n    tool_results = [...]  # collect all tool_result entries\n    if len(tool_results) <= KEEP_RECENT:\n        return messages\n    for part in tool_results[:-KEEP_RECENT]:\n        if tool_name in PRESERVE_RESULT_TOOLS:\n            continue   # keep reference material\n        part[\"content\"] = f\"[Previous: used {tool_name}]\"\n    return messages\n```\n\n2. **レバー 2 -- auto_compact**: トークンが閾値を超えたら、完全なトランスクリプトをディスクに保存し、LLMに要約を依頼する。\n\n```python\ndef auto_compact(messages: list) -> list:\n    transcript_path = TRANSCRIPT_DIR / f\"transcript_{int(time.time())}.jsonl\"\n    with open(transcript_path, \"w\") as f:\n        for msg in messages:\n            f.write(json.dumps(msg, default=str) + \"\\n\")\n    response = client.messages.create(\n        model=MODEL,\n        messages=[{\"role\": \"user\", \"content\":\n            \"Summarize this conversation for continuity...\"\n            + json.dumps(messages, default=str)[:80000]}],\n        max_tokens=2000,\n    )\n    return [\n        {\"role\": \"user\", \"content\": f\"[Compressed]\\n\\n{response.content[0].text}\"},\n    ]\n```\n\n3. **レバー 3 -- manual compact**: `compact`ツールが同じ要約処理をオンデマンドでトリガーする。\n\n4. ループが4つのレバーすべてを統合する:\n\n```python\ndef agent_loop(messages: list):\n    while True:\n        micro_compact(messages)                        # Lever 1\n        if estimate_tokens(messages) > THRESHOLD:\n            messages[:] = auto_compact(messages)       # Lever 2\n        response = client.messages.create(...)\n        # ... tool execution with persisted-output ... # Lever 0\n        if manual_compact:\n            messages[:] = auto_compact(messages)       # Lever 3\n```\n\nトランスクリプトがディスク上に完全な履歴を保持する。大きな出力は`.task_outputs/tool-results/`に保存される。何も真に失われず、アクティブなコンテキストの外に移動されるだけ。\n\n## s05からの変更点\n\n| Component         | Before (s05)     | After (s06)                |\n|-------------------|------------------|----------------------------|\n| Tools             | 5                | 5 (base + compact)         |\n| Context mgmt      | None             | Four-lever compression     |\n| Persisted-output  | None             | Large outputs -> disk + preview |\n| Micro-compact     | None             | Old results -> placeholders|\n| Auto-compact      | None             | Token threshold trigger    |\n| Transcripts       | None             | Saved to .transcripts/     |\n\n## 試してみる\n\n```sh\ncd learn-claude-code\npython agents/s06_context_compact.py\n```\n\n1. `Read every Python file in the agents/ directory one by one` (micro-compactが古い結果を置換するのを観察する)\n2. `Keep reading files until compression triggers automatically`\n3. `Use the compact tool to manually compress the conversation`\n\n## 高完成度システムではどう広がるか\n\n教材版は compact を理解しやすくするために、仕組みを大きく 4 本に絞っています。  \nより完成度の高いシステムでは、その周りに追加の段階が増えます。\n\n| レイヤー | 教材版 | 高完成度システム |\n|---------|--------|------------------|\n| 大きな出力 | 大きすぎる結果をディスクへ逃がす | 複数ツールの合計量も見ながら、文脈に入る前に予算調整する |\n| 軽い整理 | 単純な micro-compact | フル要約の前に複数の軽量整理パスを入れる |\n| フル compact | 閾値を超えたら要約 | 事前 compact、回復用 compact、エラー後 compact など役割分担が増える |\n| 回復 | 要約 1 本に置き換える | compact 後に最近のファイル、計画、スキル、非同期状態などを戻す |\n| 起動条件 | 自動または手動ツール | ユーザー操作、内部閾値、回復処理など複数の入口 |\n\nここで覚えるべき核心は変わりません。\n\n**compact は「履歴を捨てること」ではなく、「細部をアクティブ文脈の外へ移し、連続性を保つこと」**  \nです。\n"
  },
  {
    "version": "s07",
    "slug": "s07-permission-system",
    "locale": "ja",
    "title": "s07: Permission System",
    "kind": "chapter",
    "filename": "s07-permission-system.md",
    "content": "# s07: Permission System\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > [ s07 ] > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *model は「こうしたい」と提案できます。けれど本当に実行する前には、必ず安全 gate を通さなければなりません。*\n\n## この章の核心目標\n\n`s06` まで来ると agent はすでに、\n\n- file を読む\n- file を書く\n- command を実行する\n- plan を持つ\n- context を compact する\n\nことができます。\n\n能力が増えるほど、当然危険も増えます。\n\n- 間違った file を書き換える\n- 危険な shell command を実行する\n- user がまだ許可していない操作に踏み込む\n\nだからここから先は、\n\n**「model の意図」がそのまま「実行」へ落ちる**\n\n構造をやめなければなりません。\n\nこの章で入れるのは、\n\n**tool request を実行前に判定する permission pipeline**\n\nです。\n\n## 併読すると楽になる資料\n\n- model の提案と system の実実行が混ざるなら [`s00a-query-control-plane.md`](./s00a-query-control-plane.md)\n- なぜ tool request を直接 handler に落としてはいけないか不安なら [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md)\n- `PermissionRule`、`PermissionDecision`、`tool_result` が混ざるなら [`data-structures.md`](./data-structures.md)\n\n## 先に言葉をそろえる\n\n### permission system とは何か\n\npermission system は真偽値 1 個ではありません。\n\nむしろ次の 3 問に順番に答える pipeline です。\n\n1. これは即拒否すべきか\n2. 自動で許可してよいか\n3. 残りは user に確認すべきか\n\n### permission mode とは何か\n\nmode は、その session 全体の安全姿勢です。\n\nたとえば、\n\n- 慎重に進める\n- 読み取りだけ許す\n- 安全そうなものは自動通過させる\n\nといった大きな方針です。\n\n### rule とは何か\n\nrule は、\n\n> ある tool request に当たったらどう振る舞うか\n\nを表す小さな条項です。\n\n最小形なら次のような record で表せます。\n\n```python\n{\n    \"tool\": \"bash\",\n    \"content\": \"sudo *\",\n    \"behavior\": \"deny\",\n}\n```\n\n意味は、\n\n- `bash` に対して\n- command 内容が `sudo *` に当たれば\n- 拒否する\n\nです。\n\n## 最小 permission system の形\n\n0 から手で作るなら、最小で正しい pipeline は 4 段で十分です。\n\n```text\ntool_call\n  |\n  v\n1. deny rules\n  -> 危険なら即拒否\n  |\n  v\n2. mode check\n  -> 現在 mode に照らして判定\n  |\n  v\n3. allow rules\n  -> 安全で明確なら自動許可\n  |\n  v\n4. ask user\n  -> 残りは確認に回す\n```\n\nこの 4 段で teaching repo の主線としては十分に強いです。\n\n## なぜ順番がこの形なのか\n\n### 1. deny を先に見る理由\n\nある種の request は mode に関係なく危険です。\n\nたとえば、\n\n- 明白に危険な shell command\n- workspace の外へ逃げる path\n\nなどです。\n\nこうしたものは「いま auto mode だから」などの理由で通すべきではありません。\n\n### 2. mode を次に見る理由\n\nmode はその session の大きな姿勢だからです。\n\nたとえば `plan` mode なら、\n\n> まだ review / analysis 段階なので write 系をまとめて抑える\n\nという全体方針を早い段で効かせたいわけです。\n\n### 3. allow を後に見る理由\n\ndeny と mode を抜けたあとで、\n\n> これは何度も出てくる安全な操作だから自動で通してよい\n\nというものを allow します。\n\nたとえば、\n\n- `read_file`\n- code search\n- `git status`\n\nなどです。\n\n### 4. ask を最後に置く理由\n\n前段で明確に決められなかった灰色領域だけを user に回すためです。\n\nこれで、\n\n- 危険なものは system が先に止める\n- 明らかに安全なものは system が先に通す\n- 本当に曖昧なものだけ user が判断する\n\nという自然な構図になります。\n\n## 最初に実装すると良い 3 つの mode\n\n最初から mode を増やしすぎる必要はありません。\n\nまずは次の 3 つで十分です。\n\n| mode | 意味 | 向いている場面 |\n|---|---|---|\n| `default` | rule に当たらないものは user に確認 | 普通の対話 |\n| `plan` | write を止め、read 中心で進める | planning / review / analysis |\n| `auto` | 明らかに安全な read は自動許可 | 高速探索 |\n\nこの 3 つだけでも、\n\n- 慎重さ\n- 計画モード\n- 流暢さ\n\nのバランスを十分教えられます。\n\n## この章の核になるデータ構造\n\n### 1. PermissionRule\n\n```python\nPermissionRule = {\n    \"tool\": str,\n    \"behavior\": \"allow\" | \"deny\" | \"ask\",\n    \"path\": str | None,\n    \"content\": str | None,\n}\n```\n\n必ずしも最初から `path` と `content` の両方を使う必要はありません。\n\nでも少なくとも rule は次を表現できる必要があります。\n\n- どの tool に対する rule か\n- 当たったらどう振る舞うか\n\n### 2. Permission Mode\n\n```python\nmode = \"default\" | \"plan\" | \"auto\"\n```\n\nこれは個々の rule ではなく session 全体の posture です。\n\n### 3. PermissionDecision\n\n```python\n{\n    \"behavior\": \"allow\" | \"deny\" | \"ask\",\n    \"reason\": \"why this decision was made\",\n}\n```\n\nここで `reason` を持つのが大切です。\n\nなぜなら permission system は「通した / 止めた」だけではなく、\n\n**なぜそうなったかを説明できるべき**\n\nだからです。\n\n## 最小実装を段階で追う\n\n### 第 1 段階: 判定関数を書く\n\n```python\ndef check_permission(tool_name: str, tool_input: dict) -> dict:\n    # 1. deny rules\n    for rule in deny_rules:\n        if matches(rule, tool_name, tool_input):\n            return {\"behavior\": \"deny\", \"reason\": \"matched deny rule\"}\n\n    # 2. mode check\n    if mode == \"plan\" and tool_name in WRITE_TOOLS:\n        return {\"behavior\": \"deny\", \"reason\": \"plan mode blocks writes\"}\n    if mode == \"auto\" and tool_name in READ_ONLY_TOOLS:\n        return {\"behavior\": \"allow\", \"reason\": \"auto mode allows reads\"}\n\n    # 3. allow rules\n    for rule in allow_rules:\n        if matches(rule, tool_name, tool_input):\n            return {\"behavior\": \"allow\", \"reason\": \"matched allow rule\"}\n\n    # 4. fallback\n    return {\"behavior\": \"ask\", \"reason\": \"needs confirmation\"}\n```\n\n重要なのは code の華やかさではなく、\n\n**先に分類し、その後で分岐する**\n\nという構造です。\n\n### 第 2 段階: tool 実行直前に接ぐ\n\npermission は tool request が来たあと、handler を呼ぶ前に入ります。\n\n```python\ndecision = perms.check(tool_name, tool_input)\n\nif decision[\"behavior\"] == \"deny\":\n    return f\"Permission denied: {decision['reason']}\"\n\nif decision[\"behavior\"] == \"ask\":\n    ok = ask_user(...)\n    if not ok:\n        return \"Permission denied by user\"\n\nreturn handler(**tool_input)\n```\n\nこれで初めて、\n\n**tool request と real execution の間に control gate**\n\nが立ちます。\n\n## `bash` を特別に気にする理由\n\nすべての tool の中で `bash` は特別に危険です。\n\nなぜなら、\n\n- `read_file` は読むだけ\n- `write_file` は書くだけ\n- でも `bash` は理論上ほとんど何でもできる\n\nからです。\n\nしたがって `bash` をただの文字列入力として見るのは危険です。\n\n成熟した system では、`bash` を小さな executable language として扱います。\n\n教材版でも最低限、次のような危険要素は先に弾く方がよいです。\n\n- `sudo`\n- `rm -rf`\n- 危険な redirection\n- suspicious command substitution\n- 明白な shell metacharacter chaining\n\n核心は 1 文です。\n\n**bash は普通の text ではなく、可実行 action の記述**\n\nです。\n\n## 初学者が混ぜやすいポイント\n\n### 1. permission を yes/no の 2 値で考える\n\n実際には `deny / allow / ask` の 3 分岐以上が必要です。\n\n### 2. mode を rule の代わりにしようとする\n\nmode は全体 posture、rule は個別条項です。役割が違います。\n\n### 3. `bash` を普通の string と同じ感覚で通す\n\nexecution power が桁違いです。\n\n### 4. deny / allow より先に user へ全部投げる\n\nそれでは system 側の safety design を学べません。\n\n### 5. decision に reason を残さない\n\nあとで「なぜ止まったか」が説明できなくなります。\n\n## 拒否トラッキングの意味\n\n教材コードでは、連続拒否を数える簡単な circuit breaker を持たせるのも有効です。\n\nなぜなら agent が同じ危険 request を何度も繰り返すとき、\n\n- mode が合っていない\n- plan を作り直すべき\n- 別 route を選ぶべき\n\nという合図になるからです。\n\nこれは高度な observability ではなく、\n\n**permission failure も agent の progress 状態の一部である**\n\nと教えるための最小観測です。\n\n## この章を読み終えたら何が言えるべきか\n\n1. model の意図は handler へ直結させず、permission pipeline を通すべき\n2. `default / plan / auto` の 3 mode だけでも十分に teaching mainline が作れる\n3. `bash` は普通の text 入力ではなく、高い実行力を持つ tool なので特別に警戒すべき\n\n## 一文で覚える\n\n**Permission System とは、model の意図をそのまま実行に落とさず、deny / mode / allow / ask の pipeline で安全に変換する層です。**\n"
  },
  {
    "version": "s08",
    "slug": "s08-hook-system",
    "locale": "ja",
    "title": "s08: Hook System",
    "kind": "chapter",
    "filename": "s08-hook-system.md",
    "content": "# s08: Hook System\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > [ s08 ] > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *ループそのものを書き換えなくても、ライフサイクルの周囲に拡張点を置ける。*\n\n## この章が解決する問題\n\n`s07` までで、agent はかなり実用的になりました。\n\nしかし実際には、ループの外側で足したい振る舞いが増えていきます。\n\n- 監査ログ\n- 実行追跡\n- 通知\n- 追加の安全チェック\n- 実行前後の補助メッセージ\n\nこうした周辺機能を毎回メインループに直接書き込むと、すぐに主線が読みにくくなります。\n\nそこで必要なのが Hook です。\n\n## 主線とどう併読するか\n\n- Hook を「主ループの中へ if/else を足すこと」だと思い始めたら、まず [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) に戻ります。\n- 主ループ、tool handler、hook の副作用が同じ層に見えてきたら、[`entity-map.md`](./entity-map.md) で「主状態を進めるもの」と「横から観測するもの」を分けます。\n- この先で prompt、recovery、teams まで読むつもりなら、[`s00e-reference-module-map.md`](./s00e-reference-module-map.md) を近くに置いておくと、「control plane + sidecar 拡張」が何度も出てきても崩れにくくなります。\n\n## Hook を最も簡単に言うと\n\nHook は:\n\n**主ループの決まった節目で、追加動作を差し込む拡張点**\n\nです。\n\nここで大切なのは、Hook が主ループの代わりになるわけではないことです。  \n主ループは引き続き:\n\n- モデル呼び出し\n- ツール実行\n- 結果の追記\n\nを担当します。\n\n## 最小の心智モデル\n\n```text\ntool_call from model\n     |\n     v\n[PreToolUse hooks]\n     |\n     v\n[execute tool]\n     |\n     v\n[PostToolUse hooks]\n     |\n     v\nappend result and continue\n```\n\nこの形なら、ループの主線を壊さずに拡張できます。\n\n## まず教えるべき 3 つのイベント\n\n| イベント | いつ発火するか | 主な用途 |\n|---|---|---|\n| `SessionStart` | セッション開始時 | 初期通知、ウォームアップ |\n| `PreToolUse` | ツール実行前 | 監査、ブロック、補助判断 |\n| `PostToolUse` | ツール実行後 | 結果記録、通知、追跡 |\n\nこれだけで教学版としては十分です。\n\n## 重要な境界\n\n### Hook は主状態遷移を置き換えない\n\nHook がやるのは「観察して補助すること」です。\n\nメッセージ履歴、停止条件、ツール呼び出しの主責任は、あくまでメインループに残します。\n\n### Hook には整ったイベント情報を渡す\n\n理想的には、各 Hook は同じ形の情報を受け取ります。\n\nたとえば:\n\n- `event`\n- `tool_name`\n- `tool_input`\n- `tool_output`\n- `error`\n\nこの形が揃っていると、Hook を増やしても心智が崩れません。\n\n## 最小実装\n\n### 1. 設定を読む\n\n```python\nhooks = {\n    \"PreToolUse\": [...],\n    \"PostToolUse\": [...],\n    \"SessionStart\": [...],\n}\n```\n\n### 2. 実行関数を作る\n\n```python\ndef run_hooks(event_name: str, ctx: dict):\n    for hook in hooks.get(event_name, []):\n        run_one_hook(hook, ctx)\n```\n\n### 3. ループに接続する\n\n```python\nrun_hooks(\"PreToolUse\", ctx)\noutput = handler(**tool_input)\nrun_hooks(\"PostToolUse\", ctx)\n```\n\n## 初学者が混乱しやすい点\n\n### 1. Hook を第二の主ループのように考える\n\nそうすると制御が分裂して、一気に分かりにくくなります。\n\n### 2. Hook ごとに別のデータ形を渡す\n\n新しい Hook を足すたびに、読む側の心智コストが増えてしまいます。\n\n### 3. 何でも Hook に入れようとする\n\nHook は便利ですが、メインの状態遷移まで押し込む場所ではありません。\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s08_hook_system.py\n```\n\n見るポイント:\n\n1. どのイベントで Hook が走るか\n2. Hook が主ループを壊さずに追加動作だけを行っているか\n3. イベント情報の形が揃っているか\n"
  },
  {
    "version": "s09",
    "slug": "s09-memory-system",
    "locale": "ja",
    "title": "s09: Memory System",
    "kind": "chapter",
    "filename": "s09-memory-system.md",
    "content": "# s09: Memory System\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > [ s09 ] > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *memory は会話の全部を保存する場所ではない。次のセッションでも残すべき事実だけを小さく持つ場所である。*\n\n## この章が解決する問題\n\nmemory がなければ、新しいセッションは毎回ゼロから始まります。\n\nその結果、agent は何度も同じことを忘れます。\n\n- ユーザーの好み\n- すでに何度も訂正された注意点\n- コードだけでは分かりにくいプロジェクト事情\n- 外部参照の場所\n\nそこで必要になるのが memory です。\n\n## 最初に立てるべき境界\n\nこの章で最も大事なのは:\n\n**何でも memory に入れない**\n\nことです。\n\nmemory に入れるべきなのは:\n\n- セッションをまたいでも価値がある\n- 現在のリポジトリを読み直すだけでは分かりにくい\n\nこうした情報だけです。\n\n## 主線とどう併読するか\n\n- memory を「長い context の置き場」だと思ってしまうなら、[`s06-context-compact.md`](./s06-context-compact.md) に戻って compact と durable memory を分けます。\n- `messages[]`、summary block、memory store が頭の中で混ざってきたら、[`data-structures.md`](./data-structures.md) を見ながら読みます。\n- このあと `s10` へ進むなら、[`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md) を横に置くと、memory が次の入力へどう戻るかをつかみやすくなります。\n\n## 初学者向けの 4 分類\n\n### 1. `user`\n\n安定したユーザーの好み。\n\n例:\n\n- `pnpm` を好む\n- 回答は短めがよい\n\n### 2. `feedback`\n\nユーザーが明示的に直した点。\n\n例:\n\n- 生成ファイルは勝手に触らない\n- テストの更新前に確認する\n\n### 3. `project`\n\nコードを見ただけでは分かりにくい持続的事情。\n\n### 4. `reference`\n\n外部資料や外部ボードへの参照先。\n\n## 入れてはいけないもの\n\n| 入れないもの | 理由 |\n|---|---|\n| ディレクトリ構造 | コードを読めば分かる |\n| 関数名やシグネチャ | ソースが真実だから |\n| 現在タスクの進捗 | task / plan の責務 |\n| 一時的なブランチ名 | すぐ古くなる |\n| 秘密情報 | 危険 |\n\n## 最小の心智モデル\n\n```text\nconversation\n   |\n   | 長期的に残すべき事実が出る\n   v\nsave_memory\n   |\n   v\n.memory/\n  ├── MEMORY.md\n  ├── prefer_pnpm.md\n  └── ask_before_codegen.md\n   |\n   v\n次回セッション開始時に再読込\n```\n\n## 重要なデータ構造\n\n### 1. 1 メモリ = 1 ファイル\n\n```md\n---\nname: prefer_pnpm\ndescription: User prefers pnpm over npm\ntype: user\n---\nThe user explicitly prefers pnpm for package management commands.\n```\n\n### 2. 小さな索引\n\n```md\n# Memory Index\n\n- prefer_pnpm [user]\n- ask_before_codegen [feedback]\n```\n\n索引は内容そのものではなく、「何があるか」を素早く知るための地図です。\n\n## 最小実装\n\n```python\nMEMORY_TYPES = (\"user\", \"feedback\", \"project\", \"reference\")\n```\n\n```python\ndef save_memory(name, description, mem_type, content):\n    path = memory_dir / f\"{slugify(name)}.md\"\n    path.write_text(render_frontmatter(name, description, mem_type) + content)\n    rebuild_index()\n```\n\n次に、セッション開始時に読み込みます。\n\n```python\nmemories = memory_store.load_all()\n```\n\nそして `s10` で prompt 組み立てに入れます。\n\n## 近い概念との違い\n\n### memory\n\n次回以降も役立つ事実。\n\n### task\n\nいま何を完了したいか。\n\n### plan\n\nこのターンでどう進めるか。\n\n### `CLAUDE.md`\n\nより安定した指示文書や standing rules。\n\n## 初学者がよくやる間違い\n\n### 1. コードを読めば分かることまで保存する\n\nそれは memory ではなく、重複です。\n\n### 2. 現在の作業状況を memory に入れる\n\nそれは task / plan の責務です。\n\n### 3. memory を絶対真実のように扱う\n\nmemory は古くなり得ます。\n\n安全な原則は:\n\n**memory は方向を与え、現在観測は真実を与える。**\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s09_memory_system.py\n```\n"
  },
  {
    "version": "s10",
    "slug": "s10-system-prompt",
    "locale": "ja",
    "title": "s10: System Prompt",
    "kind": "chapter",
    "filename": "s10-system-prompt.md",
    "content": "# s10: System Prompt\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > [ s10 ] > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *system prompt は巨大な固定文字列ではなく、複数ソースから組み立てるパイプラインである。*\n\n## なぜこの章が必要か\n\n最初は 1 本の system prompt 文字列でも動きます。\n\nしかし機能が増えると、入力の材料が増えます。\n\n- 安定した役割説明\n- ツール一覧\n- skills\n- memory\n- `CLAUDE.md`\n- 現在ディレクトリや日時のような動的状態\n\nこうなると、1 本の固定文字列では心智が崩れます。\n\n## 主線とどう併読するか\n\n- prompt をまだ「大きな謎の文字列」として見てしまうなら、[`s00a-query-control-plane.md`](./s00a-query-control-plane.md) に戻って、モデル入力がどの control 層を通るかを見直します。\n- どの順で何を組み立てるかを安定させたいなら、[`s10a-message-prompt-pipeline.md`](./s10a-message-prompt-pipeline.md) をこの章の橋渡し資料として併読します。\n- system rules、tool docs、memory、runtime state が 1 つの入力塊に見えてきたら、[`data-structures.md`](./data-structures.md) で入力片の出所を分け直します。\n\n## 最小の心智モデル\n\n```text\n1. core identity\n2. tools\n3. skills\n4. memory\n5. CLAUDE.md chain\n6. dynamic runtime context\n```\n\n最後に順に連結します。\n\n```text\ncore\n+ tools\n+ skills\n+ memory\n+ claude_md\n+ dynamic_context\n= final model input\n```\n\n## 最も重要な境界\n\n分けるべきなのは:\n\n- 安定したルール\n- 毎ターン変わる補足情報\n\n安定したもの:\n\n- 役割\n- 安全ルール\n- ツール契約\n- 長期指示\n\n動的なもの:\n\n- 現在日時\n- cwd\n- 現在モード\n- このターンだけの注意\n\n## 最小 builder\n\n```python\nclass SystemPromptBuilder:\n    def build(self) -> str:\n        parts = []\n        parts.append(self._build_core())\n        parts.append(self._build_tools())\n        parts.append(self._build_skills())\n        parts.append(self._build_memory())\n        parts.append(self._build_claude_md())\n        parts.append(self._build_dynamic())\n        return \"\\n\\n\".join(p for p in parts if p)\n```\n\nここで重要なのは、各メソッドが 1 つの責務だけを持つことです。\n\n## 1 本の大文字列より良い理由\n\n### 1. どこから来た情報か分かる\n\n### 2. 部分ごとにテストしやすい\n\n### 3. 安定部分と動的部分を分けて育てられる\n\n## `system prompt` と `system reminder`\n\nより分かりやすい考え方は:\n\n- `system prompt`: 安定した土台\n- `system reminder`: このターンだけの追加注意\n\nこうすると、長期ルールと一時的ノイズが混ざりにくくなります。\n\n## `CLAUDE.md` が独立した段なのはなぜか\n\n`CLAUDE.md` は memory でも skill でもありません。\n\nより安定した指示文書の層です。\n\n教学版では、次のように積み上げると理解しやすいです。\n\n1. ユーザー級\n2. プロジェクト根\n3. サブディレクトリ級\n\n重要なのは:\n\n**指示源は上書き一発ではなく、層として積める**\n\nということです。\n\n## memory とこの章の関係\n\nmemory は保存するだけでは意味がありません。\n\nモデル入力に再び入って初めて、agent の行動に効いてきます。\n\nだから:\n\n- `s09` で記憶する\n- `s10` で入力に組み込む\n\nという流れになります。\n\n## 初学者が混乱しやすい点\n\n### 1. system prompt を固定文字列だと思う\n\n### 2. 毎回変わる情報も全部同じ塊に入れる\n\n### 3. skills、memory、`CLAUDE.md` を同じものとして扱う\n\n似て見えても責務は違います。\n\n- `skills`: 任意の能力パッケージ\n- `memory`: セッションをまたぐ事実\n- `CLAUDE.md`: 立ち続ける指示文書\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s10_system_prompt.py\n```\n"
  },
  {
    "version": null,
    "slug": "s10a-message-prompt-pipeline",
    "locale": "ja",
    "title": "s10a: Message / Prompt 組み立てパイプライン",
    "kind": "bridge",
    "filename": "s10a-message-prompt-pipeline.md",
    "content": "# s10a: Message / Prompt 組み立てパイプライン\n\n> これは `s10` を補う橋渡し文書です。  \n> ここでの問いは:\n>\n> **モデルが実際に見る入力は、system prompt 1 本だけなのか。**\n\n## 結論\n\n違います。\n\n高完成度の system では、モデル入力は複数 source の合成物です。\n\nたとえば:\n\n- stable system prompt blocks\n- normalized messages\n- memory section\n- dynamic reminders\n- tool instructions\n\nつまり system prompt は大事ですが、**入力全体の一部**です。\n\n## 最小の心智モデル\n\n```text\nstable rules\n  +\ntool surface\n  +\nmemory / CLAUDE.md / skills\n  +\nnormalized messages\n  +\ndynamic reminders\n  =\nfinal model input\n```\n\n## 主要な構造\n\n### `PromptParts`\n\n入力 source を組み立て前に分けて持つ構造です。\n\n```python\nparts = {\n    \"core\": \"...\",\n    \"tools\": \"...\",\n    \"memory\": \"...\",\n    \"skills\": \"...\",\n    \"dynamic\": \"...\",\n}\n```\n\n### `SystemPromptBlock`\n\n1 本の巨大文字列ではなく、section 単位で扱うための単位です。\n\n```python\nblock = {\n    \"text\": \"...\",\n    \"cache_scope\": None,\n}\n```\n\n### `NormalizedMessage`\n\nAPI に渡す前に整えられた messages です。\n\n```python\n{\n    \"role\": \"user\",\n    \"content\": [\n        {\"type\": \"text\", \"text\": \"...\"}\n    ],\n}\n```\n\n## なぜ分ける必要があるか\n\n### 1. 何が stable で何が dynamic かを分けるため\n\n- system rules は比較的 stable\n- current messages は dynamic\n- reminders はより短命\n\n### 2. どの source が何を足しているか追えるようにするため\n\nsource を混ぜて 1 本にすると:\n\n- memory がどこから来たか\n- skill がいつ入ったか\n- reminder がなぜ入ったか\n\nが見えにくくなります。\n\n### 3. compact / recovery / retry の説明がしやすくなるため\n\n入力 source が分かれていると:\n\n- 何を再利用するか\n- 何を要約するか\n- 何を次ターンで作り直すか\n\nが明確になります。\n\n## 初学者が混ぜやすい境界\n\n### `Message` と `PromptBlock`\n\n- `Message`: 会話履歴\n- `PromptBlock`: system 側の説明断片\n\n### `Memory` と `Prompt`\n\n- memory は内容 source\n- prompt pipeline は source を組む仕組み\n\n### `Tool instructions` と `Messages`\n\n- tool instructions は model が使える surface の説明\n- messages は今まで起きた対話 / 結果\n\n## 一文で覚える\n\n**system prompt は入力の全部ではなく、複数 source を束ねた pipeline の 1 つの section です。**\n"
  },
  {
    "version": "s11",
    "slug": "s11-error-recovery",
    "locale": "ja",
    "title": "s11: Error Recovery",
    "kind": "chapter",
    "filename": "s11-error-recovery.md",
    "content": "# s11: Error Recovery\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > [ s11 ] > s12 > s13 > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *error は例外イベントではなく、main loop が最初から用意しておくべき通常分岐です。*\n\n## この章が解く問題\n\n`s10` まで来ると agent はもう demo ではありません。\n\nすでに system には、\n\n- main loop\n- tool use\n- planning\n- compaction\n- permission\n- hook\n- memory\n- prompt assembly\n\nがあります。\n\nこうなると failure も自然に増えます。\n\n- model output が途中で切れる\n- context が大きすぎて request が入らない\n- API timeout や rate limit で一時的に失敗する\n\nもし recovery がなければ、main loop は最初の失敗で止まります。\n\nそして初心者はよく、\n\n> agent が不安定なのは model が弱いからだ\n\nと誤解します。\n\nしかし実際には多くの failure は、\n\n**task そのものが失敗したのではなく、この turn の続け方を変える必要があるだけ**\n\nです。\n\nこの章の目標は 1 つです。\n\n**「error が出たら停止」から、「error の種類を見て recovery path を選ぶ」へ進むこと**\n\nです。\n\n## 併読すると楽になる資料\n\n- 今の query がなぜまだ続いているのか見失ったら [`s00c-query-transition-model.md`](./s00c-query-transition-model.md)\n- compact と recovery が同じ mechanism に見えたら [`s06-context-compact.md`](./s06-context-compact.md)\n- このあと `s12` へ進む前に、recovery state と durable task state を混ぜたくなったら [`data-structures.md`](./data-structures.md)\n\n## 先に言葉をそろえる\n\n### recovery とは何か\n\nrecovery は「error をなかったことにする」ことではありません。\n\n意味は次です。\n\n- これは一時的 failure かを判定する\n- 一時的なら有限回の補救動作を試す\n- だめなら明示的に fail として返す\n\n### retry budget とは何か\n\nretry budget は、\n\n> 最大で何回までこの recovery path を試すか\n\nです。\n\n例:\n\n- continuation は最大 3 回\n- transport retry は最大 3 回\n\nこれがないと loop が無限に回る危険があります。\n\n### state machine とは何か\n\nこの章での state machine は難しい theory ではありません。\n\n単に、\n\n> normal execution と各 recovery branch を、明確な状態遷移として見ること\n\nです。\n\nこの章から query の進行は次のように見えるようになります。\n\n- normal\n- continue after truncation\n- compact then retry\n- backoff then retry\n- final fail\n\n## 最小心智モデル\n\n最初は 3 種類の failure だけ区別できれば十分です。\n\n```text\n1. output truncated\n   model はまだ言い終わっていないが token が尽きた\n\n2. context too large\n   request 全体が model window に入らない\n\n3. transient transport failure\n   timeout / rate limit / temporary connection issue\n```\n\nそれぞれに対応する recovery path はこうです。\n\n```text\nLLM call\n  |\n  +-- stop_reason == \"max_tokens\"\n  |      -> continuation message を入れる\n  |      -> retry\n  |\n  +-- prompt too long\n  |      -> compact する\n  |      -> retry\n  |\n  +-- timeout / rate limit / connection error\n         -> 少し待つ\n         -> retry\n```\n\nこれが最小ですが、十分に正しい recovery model です。\n\n## この章の核になるデータ構造\n\n### 1. Recovery State\n\n```python\nrecovery_state = {\n    \"continuation_attempts\": 0,\n    \"compact_attempts\": 0,\n    \"transport_attempts\": 0,\n}\n```\n\n役割は 2 つあります。\n\n- 各 recovery path ごとの retry 回数を分けて数える\n- 無限 recovery を防ぐ\n\n### 2. Recovery Decision\n\n```python\n{\n    \"kind\": \"continue\" | \"compact\" | \"backoff\" | \"fail\",\n    \"reason\": \"why this branch was chosen\",\n}\n```\n\nここで大事なのは、\n\n**error の見た目と、次に選ぶ動作を分ける**\n\nことです。\n\nこの分離があると loop が読みやすくなります。\n\n### 3. Continuation Message\n\n```python\nCONTINUE_MESSAGE = (\n    \"Output limit hit. Continue directly from where you stopped. \"\n    \"Do not restart or repeat.\"\n)\n```\n\nこの message は地味ですが非常に重要です。\n\nなぜなら model は「続けて」とだけ言うと、\n\n- 最初から言い直す\n- もう一度要約し直す\n- 直前の内容を繰り返す\n\nことがあるからです。\n\n## 最小実装を段階で追う\n\n### 第 1 段階: recovery chooser を作る\n\n```python\ndef choose_recovery(stop_reason: str | None, error_text: str | None) -> dict:\n    if stop_reason == \"max_tokens\":\n        return {\"kind\": \"continue\", \"reason\": \"output truncated\"}\n\n    if error_text and \"prompt\" in error_text and \"long\" in error_text:\n        return {\"kind\": \"compact\", \"reason\": \"context too large\"}\n\n    if error_text and any(word in error_text for word in [\n        \"timeout\", \"rate\", \"unavailable\", \"connection\"\n    ]):\n        return {\"kind\": \"backoff\", \"reason\": \"transient transport failure\"}\n\n    return {\"kind\": \"fail\", \"reason\": \"unknown or non-recoverable error\"}\n```\n\nこの関数がやっている本質は、\n\n**まず分類し、そのあと branch を返す**\n\nという 1 点です。\n\n### 第 2 段階: main loop に差し込む\n\n```python\nwhile True:\n    try:\n        response = client.messages.create(...)\n        decision = choose_recovery(response.stop_reason, None)\n    except Exception as e:\n        response = None\n        decision = choose_recovery(None, str(e).lower())\n\n    if decision[\"kind\"] == \"continue\":\n        messages.append({\"role\": \"user\", \"content\": CONTINUE_MESSAGE})\n        continue\n\n    if decision[\"kind\"] == \"compact\":\n        messages = auto_compact(messages)\n        continue\n\n    if decision[\"kind\"] == \"backoff\":\n        time.sleep(backoff_delay(...))\n        continue\n\n    if decision[\"kind\"] == \"fail\":\n        break\n\n    # normal tool handling\n```\n\nここで一番大事なのは、\n\n- catch したら即 stop\n\nではなく、\n\n- 何の失敗かを見る\n- どの recovery path を試すか決める\n\nという構造です。\n\n## 3 つの主 recovery path が埋めている穴\n\n### 1. continuation\n\nこれは「model が言い終わる前に output budget が切れた」問題を埋めます。\n\n本質は、\n\n> task が失敗したのではなく、1 turn の出力空間が足りなかった\n\nということです。\n\n最小形はこうです。\n\n```python\nif response.stop_reason == \"max_tokens\":\n    if state[\"continuation_attempts\"] >= 3:\n        return \"Error: output recovery exhausted\"\n    state[\"continuation_attempts\"] += 1\n    messages.append({\"role\": \"user\", \"content\": CONTINUE_MESSAGE})\n    continue\n```\n\n### 2. compact\n\nこれは「task が無理」ではなく、\n\n> active context が大きすぎて request が入らない\n\nときに使います。\n\nここで大事なのは、compact を delete と考えないことです。\n\ncompact は、\n\n**過去を、そのままの原文ではなく、まだ続行可能な summary へ変換する**\n\n操作です。\n\n最小例:\n\n```python\ndef auto_compact(messages: list) -> list:\n    summary = summarize_messages(messages)\n    return [{\n        \"role\": \"user\",\n        \"content\": \"This session was compacted. Continue from this summary:\\n\" + summary,\n    }]\n```\n\n最低限 summary に残したいのは次です。\n\n- 今の task は何か\n- 何をすでに終えたか\n- 重要 decision は何か\n- 次に何をするつもりか\n\n### 3. backoff\n\nこれは timeout、rate limit、temporary connection issue のような\n\n**時間を置けば通るかもしれない failure**\n\nに対して使います。\n\n考え方は単純です。\n\n```python\nif decision[\"kind\"] == \"backoff\":\n    if state[\"transport_attempts\"] >= 3:\n        break\n    state[\"transport_attempts\"] += 1\n    time.sleep(backoff_delay(state[\"transport_attempts\"]))\n    continue\n```\n\nここで大切なのは「retry すること」よりも、\n\n**retry にも budget があり、同じ速度で無限に叩かないこと**\n\nです。\n\n## compact と recovery を混ぜない\n\nこれは初学者が特に混ぜやすい点です。\n\n- `s06` の compact は context hygiene のために行うことがある\n- `s11` の compact recovery は request failure から戻るために行う\n\n同じ compact という操作でも、\n\n**目的が違います。**\n\n目的が違えば、それを呼ぶ branch も別に見るべきです。\n\n## recovery は query の continuation 理由でもある\n\n`s11` の重要な学びは、error handling を `except` の奥へ隠さないことです。\n\nむしろ次を explicit に持つ方が良いです。\n\n- なぜまだ続いているのか\n- 何回その branch を試したのか\n- 次にどの branch を試すのか\n\nすると recovery は hidden plumbing ではなく、\n\n**query transition を説明する状態**\n\nになります。\n\n## 初学者が混ぜやすいポイント\n\n### 1. すべての failure に同じ retry をかける\n\ntruncation と transport error は同じ問題ではありません。\n\n### 2. retry budget を持たない\n\n無限 loop の原因になります。\n\n### 3. compact と recovery を 1 つの話にしてしまう\n\ncontext hygiene と failure recovery は目的が違います。\n\n### 4. continuation message を曖昧にする\n\n「続けて」だけでは model が restart / repeat しやすいです。\n\n### 5. なぜ続行しているのかを state に残さない\n\ndebug も teaching も急に難しくなります。\n\n## この章を読み終えたら何が言えるべきか\n\n1. 多くの error は task failure ではなく、「この turn の続け方を変えるべき」信号である\n2. recovery は `continue / compact / backoff / fail` の branch として考えられる\n3. recovery path ごとに budget を持たないと loop が壊れやすい\n\n## 一文で覚える\n\n**Error Recovery とは、failure を見た瞬間に止まるのではなく、failure の種類に応じて continuation path を選び直す control layer です。**\n"
  },
  {
    "version": "s12",
    "slug": "s12-task-system",
    "locale": "ja",
    "title": "s12: Task System",
    "kind": "chapter",
    "filename": "s12-task-system.md",
    "content": "# s12: Task System\n\n`s01 > s02 > s03 > s04 > s05 > s06 | s07 > s08 > s09 > s10 > s11 > [ s12 ]`\n\n> *\"大きな目標を小タスクに分解し、順序付けし、ディスクに記録する\"* -- ファイルベースのタスクグラフ、マルチエージェント協調の基盤。\n>\n> **Harness 層**: 永続タスク -- どの会話よりも長く生きる目標。\n\n## 問題\n\ns03のTodoManagerはメモリ上のフラットなチェックリストに過ぎない: 順序なし、依存関係なし、ステータスは完了か未完了のみ。実際の目標には構造がある -- タスクBはタスクAに依存し、タスクCとDは並行実行でき、タスクEはCとDの両方を待つ。\n\n明示的な関係がなければ、エージェントは何が実行可能で、何がブロックされ、何が同時に走れるかを判断できない。しかもリストはメモリ上にしかないため、コンテキスト圧縮(s06)で消える。\n\n## 主線とどう併読するか\n\n- `s03` からそのまま来たなら、[`data-structures.md`](./data-structures.md) へ戻って `TodoItem` / `PlanState` と `TaskRecord` を分けます。\n- object 境界が混ざり始めたら、[`entity-map.md`](./entity-map.md) で message、task、runtime task、teammate を分離してから戻ります。\n- 次に `s13` を読むなら、[`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) を横に置いて、durable task と runtime task を同じ言葉で潰さないようにします。\n\n## 解決策\n\nフラットなチェックリストをディスクに永続化する**タスクグラフ**に昇格させる。各タスクは1つのJSONファイルで、ステータス・前方依存(`blockedBy`)を持つ。タスクグラフは常に3つの問いに答える:\n\n- **何が実行可能か?** -- `pending`ステータスで`blockedBy`が空のタスク。\n- **何がブロックされているか?** -- 未完了の依存を待つタスク。\n- **何が完了したか?** -- `completed`のタスク。完了時に後続タスクを自動的にアンブロックする。\n\n```\n.tasks/\n  task_1.json  {\"id\":1, \"status\":\"completed\"}\n  task_2.json  {\"id\":2, \"blockedBy\":[1], \"status\":\"pending\"}\n  task_3.json  {\"id\":3, \"blockedBy\":[1], \"status\":\"pending\"}\n  task_4.json  {\"id\":4, \"blockedBy\":[2,3], \"status\":\"pending\"}\n\nタスクグラフ (DAG):\n                 +----------+\n            +--> | task 2   | --+\n            |    | pending  |   |\n+----------+     +----------+    +--> +----------+\n| task 1   |                          | task 4   |\n| completed| --> +----------+    +--> | blocked  |\n+----------+     | task 3   | --+     +----------+\n                 | pending  |\n                 +----------+\n\n順序:       task 1 は 2 と 3 より先に完了する必要がある\n並行:       task 2 と 3 は同時に実行できる\n依存:       task 4 は 2 と 3 の両方を待つ\nステータス: pending -> in_progress -> completed\n```\n\nこのタスクグラフは後続の runtime / platform 章の協調バックボーンになる: バックグラウンド実行(`s13`)、マルチエージェントチーム(`s15+`)、worktree 分離(`s18`)はすべてこの durable な構造の恩恵を受ける。\n\n## 仕組み\n\n1. **TaskManager**: タスクごとに1つのJSONファイル、依存グラフ付きCRUD。\n\n```python\nclass TaskManager:\n    def __init__(self, tasks_dir: Path):\n        self.dir = tasks_dir\n        self.dir.mkdir(exist_ok=True)\n        self._next_id = self._max_id() + 1\n\n    def create(self, subject, description=\"\"):\n        task = {\"id\": self._next_id, \"subject\": subject,\n                \"status\": \"pending\", \"blockedBy\": [],\n                \"owner\": \"\"}\n        self._save(task)\n        self._next_id += 1\n        return json.dumps(task, indent=2)\n```\n\n2. **依存解除**: タスク完了時に、他タスクの`blockedBy`リストから完了IDを除去し、後続タスクをアンブロックする。\n\n```python\ndef _clear_dependency(self, completed_id):\n    for f in self.dir.glob(\"task_*.json\"):\n        task = json.loads(f.read_text())\n        if completed_id in task.get(\"blockedBy\", []):\n            task[\"blockedBy\"].remove(completed_id)\n            self._save(task)\n```\n\n3. **ステータス遷移 + 依存配線**: `update`がステータス変更と依存エッジを担う。\n\n```python\ndef update(self, task_id, status=None,\n           add_blocked_by=None, remove_blocked_by=None):\n    task = self._load(task_id)\n    if status:\n        task[\"status\"] = status\n        if status == \"completed\":\n            self._clear_dependency(task_id)\n    if add_blocked_by:\n        task[\"blockedBy\"] = list(set(task[\"blockedBy\"] + add_blocked_by))\n    if remove_blocked_by:\n        task[\"blockedBy\"] = [x for x in task[\"blockedBy\"] if x not in remove_blocked_by]\n    self._save(task)\n```\n\n4. 4つのタスクツールをディスパッチマップに追加する。\n\n```python\nTOOL_HANDLERS = {\n    # ...base tools...\n    \"task_create\": lambda **kw: TASKS.create(kw[\"subject\"]),\n    \"task_update\": lambda **kw: TASKS.update(kw[\"task_id\"], kw.get(\"status\")),\n    \"task_list\":   lambda **kw: TASKS.list_all(),\n    \"task_get\":    lambda **kw: TASKS.get(kw[\"task_id\"]),\n}\n```\n\n`s12` 以降、タスクグラフが durable なマルチステップ作業のデフォルトになる。`s03` の Todo は軽量な単一セッション用チェックリストとして残る。\n\n## s06からの変更点\n\n| コンポーネント | Before (s06) | After (s12) |\n|---|---|---|\n| Tools | 5 | 8 (`task_create/update/list/get`) |\n| 計画モデル | フラットチェックリスト (メモリ) | 依存関係付きタスクグラフ (ディスク) |\n| 関係 | なし | `blockedBy` エッジ |\n| ステータス追跡 | 完了か未完了 | `pending` -> `in_progress` -> `completed` |\n| 永続性 | 圧縮で消失 | 圧縮・再起動後も存続 |\n\n## 試してみる\n\n```sh\ncd learn-claude-code\npython agents/s12_task_system.py\n```\n\n1. `Create 3 tasks: \"Setup project\", \"Write code\", \"Write tests\". Make them depend on each other in order.`\n2. `List all tasks and show the dependency graph`\n3. `Complete task 1 and then list tasks to see task 2 unblocked`\n4. `Create a task board for refactoring: parse -> transform -> emit -> test, where transform and emit can run in parallel after parse`\n\n## 教学上の境界\n\nこのリポジトリで本当に重要なのは、完全な製品向け保存層の再現ではありません。\n\n重要なのは:\n\n- durable なタスク記録\n- 明示的な依存エッジ\n- 分かりやすい状態遷移\n- 後続章が再利用できる構造\n\nこの 4 点を自分で実装できれば、タスクシステムの核心はつかめています。\n"
  },
  {
    "version": "s13",
    "slug": "s13-background-tasks",
    "locale": "ja",
    "title": "s13: バックグラウンドタスク",
    "kind": "chapter",
    "filename": "s13-background-tasks.md",
    "content": "# s13: バックグラウンドタスク\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > [ s13 ] > s14 > s15 > s16 > s17 > s18 > s19`\n\n> *遅い command は横で待たせればよく、main loop まで一緒に止まる必要はありません。*\n\n## この章が解く問題\n\n前の章までの tool call は、基本的に次の形でした。\n\n```text\nmodel が tool を要求する\n  ->\nすぐ実行する\n  ->\nすぐ結果を返す\n```\n\n短い command ならこれで問題ありません。\n\nでも次のような処理はすぐに詰まります。\n\n- `npm install`\n- `pytest`\n- `docker build`\n- 重い code generation\n- 長時間の lint / typecheck\n\nもし main loop がその完了を同期的に待ち続けると、2 つの問題が起きます。\n\n- model は待ち時間のあいだ次の判断へ進めない\n- user は別の軽い作業を進めたいのに、agent 全体が足止めされる\n\nこの章で入れるのは、\n\n**遅い実行を background へ逃がし、main loop は次の仕事へ進めるようにすること**\n\nです。\n\n## 併読すると楽になる資料\n\n- `task goal` と `live execution slot` がまだ混ざるなら [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n- `RuntimeTaskRecord` と task board の境界を見直したいなら [`data-structures.md`](./data-structures.md)\n- background execution が「別の main loop」に見えてきたら [`s02b-tool-execution-runtime.md`](./s02b-tool-execution-runtime.md)\n\n## 先に言葉をそろえる\n\n### foreground とは何か\n\nここで言う foreground は、\n\n> この turn の中で今すぐ結果が必要なので、main loop がその場で待つ実行\n\nです。\n\n### background とは何か\n\nbackground は謎の裏世界ではありません。\n\n意味は単純で、\n\n> command を別の execution line に任せ、main loop は先に別のことを進める\n\nことです。\n\n### 通知キューとは何か\n\nbackground task が終わっても、その完全な出力をいきなり model へ丸ごと押し込む必要はありません。\n\nいったん queue に要約通知として積み、\n\n> 次の model call の直前にまとめて main loop へ戻す\n\nのが分かりやすい設計です。\n\n## 最小心智モデル\n\nこの章で最も大切な 1 文は次です。\n\n**並行になるのは実行と待機であって、main loop 自体が増えるわけではありません。**\n\n図にするとこうです。\n\n```text\nMain loop\n  |\n  +-- background_run(\"pytest\")\n  |      -> すぐ task_id を返す\n  |\n  +-- そのまま別の仕事を続ける\n  |\n  +-- 次の model call の前\n         -> drain_notifications()\n         -> 結果要約を messages へ注入\n\nBackground lane\n  |\n  +-- 実際に subprocess を実行\n  +-- 終了後に result preview を queue へ積む\n```\n\nこの図を保ったまま理解すれば、後でもっと複雑な runtime へ進んでも心智が崩れにくくなります。\n\n## この章の核になるデータ構造\n\n### 1. RuntimeTaskRecord\n\nこの章で扱う background task は durable task board の task とは別物です。\n\n教材コードでは、background 実行はおおむね次の record を持ちます。\n\n```python\ntask = {\n    \"id\": \"a1b2c3d4\",\n    \"command\": \"pytest\",\n    \"status\": \"running\",\n    \"started_at\": 1710000000.0,\n    \"finished_at\": None,\n    \"result_preview\": \"\",\n    \"output_file\": \".runtime-tasks/a1b2c3d4.log\",\n}\n```\n\n各 field の意味は次の通りです。\n\n- `id`: runtime slot の識別子\n- `command`: 今走っている command\n- `status`: `running` / `completed` / `timeout` / `error`\n- `started_at`: いつ始まったか\n- `finished_at`: いつ終わったか\n- `result_preview`: model に戻す短い要約\n- `output_file`: 完全出力の保存先\n\n教材版ではこれを disk 上にも分けて残します。\n\n```text\n.runtime-tasks/\n  a1b2c3d4.json\n  a1b2c3d4.log\n```\n\nこれで読者は、\n\n- `json` は状態 record\n- `log` は完全出力\n- model へ戻すのはまず preview\n\nという 3 層を自然に見分けられます。\n\n### 2. Notification\n\nbackground result はまず notification queue に入ります。\n\n```python\nnotification = {\n    \"task_id\": \"a1b2c3d4\",\n    \"status\": \"completed\",\n    \"command\": \"pytest\",\n    \"preview\": \"42 tests passed\",\n    \"output_file\": \".runtime-tasks/a1b2c3d4.log\",\n}\n```\n\nnotification の役割は 1 つだけです。\n\n> main loop に「結果が戻ってきた」と知らせること\n\nここに完全出力の全量を埋め込む必要はありません。\n\n## 最小実装を段階で追う\n\n### 第 1 段階: background manager を持つ\n\n最低限必要なのは次の 2 つの状態です。\n\n- `tasks`: いま存在する runtime task\n- `_notification_queue`: main loop にまだ回収されていない結果\n\n```python\nclass BackgroundManager:\n    def __init__(self):\n        self.tasks = {}\n        self._notification_queue = []\n        self._lock = threading.Lock()\n```\n\nここで lock を置いているのは、background thread と main loop が同じ queue / dict を触るからです。\n\n### 第 2 段階: `run()` はすぐ返す\n\nbackground 化の一番大きな変化はここです。\n\n```python\ndef run(self, command: str) -> str:\n    task_id = str(uuid.uuid4())[:8]\n    self.tasks[task_id] = {\n        \"id\": task_id,\n        \"status\": \"running\",\n        \"command\": command,\n        \"started_at\": time.time(),\n    }\n\n    thread = threading.Thread(\n        target=self._execute,\n        args=(task_id, command),\n        daemon=True,\n    )\n    thread.start()\n    return task_id\n```\n\n重要なのは thread 自体より、\n\n**main loop が結果ではなく `task_id` を受け取り、先に進める**\n\nことです。\n\n### 第 3 段階: subprocess が終わったら notification を積む\n\n```python\ndef _execute(self, task_id: str, command: str):\n    try:\n        result = subprocess.run(..., timeout=300)\n        status = \"completed\"\n        preview = (result.stdout + result.stderr)[:500]\n    except subprocess.TimeoutExpired:\n        status = \"timeout\"\n        preview = \"command timed out\"\n\n    with self._lock:\n        self.tasks[task_id][\"status\"] = status\n        self._notification_queue.append({\n            \"task_id\": task_id,\n            \"status\": status,\n            \"preview\": preview,\n        })\n```\n\nここでの設計意図ははっきりしています。\n\n- execution lane は command を実際に走らせる\n- notification queue は main loop へ戻すための要約を持つ\n\n役割を分けることで、result transport が見やすくなります。\n\n### 第 4 段階: 次の model call 前に queue を drain する\n\n```python\ndef agent_loop(messages: list):\n    while True:\n        notifications = BG.drain_notifications()\n        if notifications:\n            notif_text = \"\\n\".join(\n                f\"[bg:{n['task_id']}] {n['preview']}\" for n in notifications\n            )\n            messages.append({\n                \"role\": \"user\",\n                \"content\": f\"<background-results>\\n{notif_text}\\n</background-results>\",\n            })\n            messages.append({\n                \"role\": \"assistant\",\n                \"content\": \"Noted background results.\",\n            })\n```\n\nこの構造が大切です。\n\n結果は「いつでも割り込んで model へ押し込まれる」のではなく、\n\n**次の model call の入口でまとめて注入される**\n\nからです。\n\n### 第 5 段階: preview と full output を分ける\n\n教材コードでは `result_preview` と `output_file` を分けています。\n\nこれは初心者にも非常に大事な設計です。\n\nなぜなら background result にはしばしば次の問題があるからです。\n\n- 出力が長い\n- model に全量を見せる必要がない\n- user だけ詳細 log を見れば十分なことが多い\n\nそこでまず model には短い preview を返し、必要なら後で `read_file` 等で full log を読む形にします。\n\n### 第 6 段階: stalled task も見られるようにする\n\n教材コードは `STALL_THRESHOLD_S` を持ち、長く走りすぎている task を拾えます。\n\n```python\ndef detect_stalled(self) -> list[str]:\n    now = time.time()\n    stalled = []\n    for task_id, info in self.tasks.items():\n        if info[\"status\"] != \"running\":\n            continue\n        elapsed = now - info.get(\"started_at\", now)\n        if elapsed > STALL_THRESHOLD_S:\n            stalled.append(task_id)\n    return stalled\n```\n\nここで学ぶべき本質は sophisticated monitoring ではありません。\n\n**background 化したら「開始したまま返ってこないもの」を見張る観点が必要になる**\n\nということです。\n\n## これは task board の task とは違う\n\nここは混ざりやすいので強調します。\n\n`s12` の `task` は durable goal node です。\n\n一方この章の background task は、\n\n> いま実行中の live runtime slot\n\nです。\n\n同じ `task` という言葉を使っても指している層が違います。\n\nだから分からなくなったら、本文だけを往復せずに次へ戻るべきです。\n\n- [`entity-map.md`](./entity-map.md)\n- [`data-structures.md`](./data-structures.md)\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n\n## 前の章とどうつながるか\n\nこの章は `s12` の durable task graph を否定する章ではありません。\n\nむしろ、\n\n- `s12` が「何の仕事が存在するか」を管理し\n- `s13` が「いまどの command が走っているか」を管理する\n\nという役割分担を教える章です。\n\n後の `s14`、`s17`、`s18` へ行く前に、\n\n**goal と runtime slot を分けて見る癖**\n\nをここで作っておくことが重要です。\n\n## 初学者が混ぜやすいポイント\n\n### 1. background execution を「もう 1 本の main loop」と考える\n\n実際に増えているのは subprocess waiting lane であって、main conversational loop ではありません。\n\n### 2. result を queue ではなく即座に messages へ乱暴に書き込む\n\nこれでは model input の入口が分散し、system の流れが追いにくくなります。\n\n### 3. full output と preview を分けない\n\n長い log で context がすぐあふれます。\n\n### 4. runtime task と durable task を同一視する\n\n「いま走っている command」と「長く残る work goal」は別物です。\n\n### 5. queue 操作に lock を使わない\n\nbackground thread と main loop の競合で状態が壊れやすくなります。\n\n### 6. timeout / error を `completed` と同じように扱う\n\n戻すべき情報は同じではありません。終了理由は explicit に残すべきです。\n\n## 教学上の境界\n\nこの章でまず理解すべき中心は、製品用の完全な async runtime ではありません。\n\n中心は次の 3 行です。\n\n- 遅い仕事を foreground から切り離す\n- 結果は notification として main loop に戻す\n- runtime slot は durable task board とは別層で管理する\n\nここが腹落ちしてから、\n\n- より複雑な scheduler\n- 複数種類の background lane\n- 分散 worker\n\nへ進めば十分です。\n"
  },
  {
    "version": null,
    "slug": "s13a-runtime-task-model",
    "locale": "ja",
    "title": "s13a: Runtime Task Model",
    "kind": "bridge",
    "filename": "s13a-runtime-task-model.md",
    "content": "# s13a: Runtime Task Model\n\n> この bridge doc はすぐに混ざる次の点をほどくためのものです。\n>\n> **work graph 上の task と、いま実行中の task は同じものではありません。**\n\n## 主線とどう併読するか\n\n次の順で読むのが最も分かりやすいです。\n\n- まず [`s12-task-system.md`](./s12-task-system.md) を読み、durable な work graph を固める\n- 次に [`s13-background-tasks.md`](./s13-background-tasks.md) を読み、background execution を見る\n- 用語が混ざり始めたら [`glossary.md`](./glossary.md) を見直す\n- field を正確に合わせたいなら [`data-structures.md`](./data-structures.md) と [`entity-map.md`](./entity-map.md) を見直す\n\n## なぜこの橋渡しが必要か\n\n主線自体は正しいです。\n\n- `s12` は task system\n- `s13` は background tasks\n\nただし bridge layer を一枚挟まないと、読者は二種類の「task」をすぐに同じ箱へ入れてしまいます。\n\n例えば:\n\n- 「auth module を実装する」という work-graph task\n- 「pytest を走らせる」という background execution\n- 「alice がコード修正をしている」という teammate execution\n\nどれも日常語では task と呼べますが、同じ層にはありません。\n\n## 二つの全く違う task\n\n### 1. work-graph task\n\nこれは `s12` の durable node です。\n\n答えるものは:\n\n- 何をやるか\n- どの仕事がどの仕事に依存するか\n- 誰が owner か\n- 進捗はどうか\n\nつまり:\n\n> 目標として管理される durable work unit\n\nです。\n\n### 2. runtime task\n\nこちらが答えるものは:\n\n- 今どの execution unit が生きているか\n- それが何の type か\n- running / completed / failed / killed のどれか\n- 出力がどこにあるか\n\nつまり:\n\n> runtime の中で生きている execution slot\n\nです。\n\n## 最小の心智モデル\n\nまず二つの表として分けて考えてください。\n\n```text\nwork-graph task\n  - durable\n  - goal / dependency oriented\n  - 寿命が長い\n\nruntime task\n  - execution oriented\n  - output / status oriented\n  - 寿命が短い\n```\n\n両者の関係は「どちらか一方」ではありません。\n\n```text\n1 つの work-graph task\n  から\n1 個以上の runtime task が派生しうる\n```\n\n例えば:\n\n```text\nwork-graph task:\n  \"Implement auth module\"\n\nruntime tasks:\n  1. background で test を走らせる\n  2. coder teammate を起動する\n  3. 外部 service を monitor する\n```\n\n## なぜこの区別が重要か\n\nこの境界が崩れると、後続章がすぐに絡み始めます。\n\n- `s13` の background execution が `s12` の task board と混ざる\n- `s15-s17` の teammate work がどこにぶら下がるか不明になる\n- `s18` の worktree が何に紐づくのか曖昧になる\n\n最短の正しい要約はこれです。\n\n**work-graph task は目標を管理し、runtime task は実行を管理する**\n\n## 主要 record\n\n### 1. `WorkGraphTaskRecord`\n\nこれは `s12` の durable task です。\n\n```python\ntask = {\n    \"id\": 12,\n    \"subject\": \"Implement auth module\",\n    \"status\": \"in_progress\",\n    \"blockedBy\": [],\n    \"blocks\": [13],\n    \"owner\": \"alice\",\n    \"worktree\": \"auth-refactor\",\n}\n```\n\n### 2. `RuntimeTaskState`\n\n教材版の最小形は次の程度で十分です。\n\n```python\nruntime_task = {\n    \"id\": \"b8k2m1qz\",\n    \"type\": \"local_bash\",\n    \"status\": \"running\",\n    \"description\": \"Run pytest\",\n    \"start_time\": 1710000000.0,\n    \"end_time\": None,\n    \"output_file\": \".task_outputs/b8k2m1qz.txt\",\n    \"notified\": False,\n}\n```\n\n重要 field は:\n\n- `type`: どの execution unit か\n- `status`: active か terminal か\n- `output_file`: 結果がどこにあるか\n- `notified`: 結果を system がもう表に出したか\n\n### 3. `RuntimeTaskType`\n\n教材 repo ですべての type を即実装する必要はありません。\n\nただし runtime task は単なる shell 1 種ではなく、型族だと読者に見せるべきです。\n\n最小表は:\n\n```text\nlocal_bash\nlocal_agent\nremote_agent\nin_process_teammate\nmonitor\nworkflow\n```\n\n## 最小実装の進め方\n\n### Step 1: `s12` の task board はそのまま保つ\n\nここへ runtime state を混ぜないでください。\n\n### Step 2: 別の runtime task manager を足す\n\n```python\nclass RuntimeTaskManager:\n    def __init__(self):\n        self.tasks = {}\n```\n\n### Step 3: background work 開始時に runtime task を作る\n\n```python\ndef spawn_bash_task(command: str):\n    task_id = new_runtime_id()\n    runtime_tasks[task_id] = {\n        \"id\": task_id,\n        \"type\": \"local_bash\",\n        \"status\": \"running\",\n        \"description\": command,\n    }\n```\n\n### Step 4: 必要なら work graph へ結び戻す\n\n```python\nruntime_tasks[task_id][\"work_graph_task_id\"] = 12\n```\n\n初日から必須ではありませんが、teams や worktrees へ進むほど重要になります。\n\n## 開発者が持つべき図\n\n```text\nWork Graph\n  task #12: Implement auth module\n        |\n        +-- runtime task A: local_bash (pytest)\n        +-- runtime task B: local_agent (coder worker)\n        +-- runtime task C: monitor (watch service status)\n\nRuntime Task Layer\n  A/B/C each have:\n  - own runtime ID\n  - own status\n  - own output\n  - own lifecycle\n```\n\n## 後続章とのつながり\n\nこの層が明確になると、後続章がかなり読みやすくなります。\n\n- `s13` の background command は runtime task\n- `s15-s17` の teammate も runtime task の一種として見られる\n- `s18` の worktree は主に durable work に紐づくが runtime execution にも影響する\n- `s19` の monitor や async external work も runtime layer に落ちうる\n\n「裏で生きていて仕事を進めているもの」を見たら、まず二つ問います。\n\n- これは work graph 上の durable goal か\n- それとも runtime 上の live execution slot か\n\n## 初学者がやりがちな間違い\n\n### 1. background shell の state を task board に直接入れる\n\ndurable task state と runtime execution state が混ざります。\n\n### 2. 1 つの work-graph task は 1 つの runtime task しか持てないと思う\n\n現実の system では、1 つの goal から複数 execution unit が派生することは普通です。\n\n### 3. 両層で同じ status 語彙を使い回す\n\n例えば:\n\n- durable tasks: `pending / in_progress / completed`\n- runtime tasks: `running / completed / failed / killed`\n\n可能な限り分けた方が安全です。\n\n### 4. `output_file` や `notified` のような runtime 専用 field を軽視する\n\ndurable task board はそこまで気にしませんが、runtime layer は強く依存します。\n"
  },
  {
    "version": "s14",
    "slug": "s14-cron-scheduler",
    "locale": "ja",
    "title": "s14: Cron Scheduler",
    "kind": "chapter",
    "filename": "s14-cron-scheduler.md",
    "content": "# s14: Cron Scheduler\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > [ s14 ] > s15 > s16 > s17 > s18 > s19`\n\n> *バックグラウンドタスクが「遅い仕事をどう続けるか」を扱うなら、スケジューラは「未来のいつ仕事を始めるか」を扱う。*\n\n## この章が解決する問題\n\n`s13` で、遅い処理をバックグラウンドへ逃がせるようになりました。\n\nでもそれは「今すぐ始める仕事」です。\n\n現実には:\n\n- 毎晩実行したい\n- 毎週決まった時刻にレポートを作りたい\n- 30 分後に再確認したい\n\nといった未来トリガーが必要になります。\n\nこの章の核心は:\n\n**未来の意図を今記録して、時刻が来たら新しい仕事として戻す**\n\nことです。\n\n## 教学上の境界\n\nこの章の中心は cron 構文の暗記ではありません。\n\n本当に理解すべきなのは:\n\n**schedule record が通知になり、通知が主ループへ戻る流れ**\n\nです。\n\n## 主線とどう併読するか\n\n- `schedule`、`task`、`runtime task` がまだ同じ object に見えるなら、[`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) に戻ります。\n- 1 つの trigger が最終的にどう主線へ戻るかを見たいなら、[`s00b-one-request-lifecycle.md`](./s00b-one-request-lifecycle.md) と一緒に読みます。\n- 未来トリガーが別の実行系に見えてきたら、[`data-structures.md`](./data-structures.md) で schedule record と runtime record を分け直します。\n\n## 最小の心智モデル\n\n```text\n1. schedule records\n2. time checker\n3. notification queue\n```\n\n流れ:\n\n```text\nschedule_create(...)\n  ->\n記録を保存\n  ->\ntime checker が定期的に一致判定\n  ->\n一致したら scheduled notification を積む\n  ->\n主ループがそれを新しい仕事として受け取る\n```\n\n重要なのは:\n\n**scheduler 自体は第二の agent ではない**\n\nということです。\n\n## 重要なデータ構造\n\n### 1. schedule record\n\n```python\nschedule = {\n    \"id\": \"job_001\",\n    \"cron\": \"0 9 * * 1\",\n    \"prompt\": \"Run the weekly status report.\",\n    \"recurring\": True,\n    \"durable\": True,\n    \"created_at\": 1710000000.0,\n    \"last_fired_at\": None,\n}\n```\n\n### 2. scheduled notification\n\n```python\n{\n    \"type\": \"scheduled_prompt\",\n    \"schedule_id\": \"job_001\",\n    \"prompt\": \"Run the weekly status report.\",\n}\n```\n\n### 3. check interval\n\n教学版なら分単位で十分です。\n\n## 最小実装\n\n```python\ndef create(self, cron_expr: str, prompt: str, recurring: bool = True):\n    job = {\n        \"id\": new_id(),\n        \"cron\": cron_expr,\n        \"prompt\": prompt,\n        \"recurring\": recurring,\n        \"created_at\": time.time(),\n        \"last_fired_at\": None,\n    }\n    self.jobs.append(job)\n    return job\n```\n\n```python\ndef check_loop(self):\n    while True:\n        now = datetime.now()\n        self.check_jobs(now)\n        time.sleep(60)\n```\n\n```python\ndef check_jobs(self, now):\n    for job in self.jobs:\n        if cron_matches(job[\"cron\"], now):\n            self.queue.put({\n                \"type\": \"scheduled_prompt\",\n                \"schedule_id\": job[\"id\"],\n                \"prompt\": job[\"prompt\"],\n            })\n            job[\"last_fired_at\"] = now.timestamp()\n```\n\n最後に主ループへ戻します。\n\n```python\nnotifications = scheduler.drain()\nfor item in notifications:\n    messages.append({\n        \"role\": \"user\",\n        \"content\": f\"[scheduled:{item['schedule_id']}] {item['prompt']}\",\n    })\n```\n\n## なぜ `s13` の後なのか\n\nこの 2 章は近い問いを扱います。\n\n| 仕組み | 中心の問い |\n|---|---|\n| background tasks | 遅い仕事を止めずにどう続けるか |\n| scheduling | 未来の仕事をいつ始めるか |\n\nこの順序の方が、初学者には自然です。\n\n## 初学者がやりがちな間違い\n\n### 1. cron 構文だけに意識を取られる\n\n### 2. `last_fired_at` を持たない\n\n### 3. スケジュールをメモリにしか置かない\n\n### 4. 未来トリガーの仕事を裏で黙って全部実行する\n\nより分かりやすい主線は:\n\n- trigger\n- notify\n- main loop が処理を決める\n\nです。\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s14_cron_scheduler.py\n```\n"
  },
  {
    "version": "s15",
    "slug": "s15-agent-teams",
    "locale": "ja",
    "title": "s15: Agent Teams",
    "kind": "chapter",
    "filename": "s15-agent-teams.md",
    "content": "# s15: Agent Teams\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > [ s15 ] > s16 > s17 > s18 > s19`\n\n> *subagent は一回きりの委譲に向く。team system が解くのは、「誰かが長く online で残り、繰り返し仕事を受け取り、互いに協調できる」状態です。*\n\n## この章が本当に解きたい問題\n\n`s04` の subagent は、main agent が作業を小さく切り出すのに十分役立ちます。\n\nただし subagent には明確な境界があります。\n\n```text\n生成される\n  ->\n少し作業する\n  ->\n要約を返す\n  ->\n消える\n```\n\nこれは一回きりの調査や短い委譲にはとても向いています。  \nしかし、次のような system を作りたいときには足りません。\n\n- テスト担当の agent を長く待機させる\n- リファクタ担当とテスト担当を並行して持ち続ける\n- ある teammate が後のターンでも同じ責任を持ち続ける\n- lead が後で同じ teammate へ再び仕事を振る\n\nつまり今不足しているのは「model call を 1 回増やすこと」ではありません。\n\n不足しているのは:\n\n**名前・役割・inbox・状態を持った、長期的に存在する実行者の集まり**\n\nです。\n\n## 併読のすすめ\n\n- teammate と `s04` の subagent をまだ同じものに見てしまうなら、[`entity-map.md`](./entity-map.md) に戻ります。\n- `s16-s18` まで続けて読むなら、[`team-task-lane-model.md`](./team-task-lane-model.md) を手元に置き、teammate、protocol request、task、runtime slot、worktree lane を混ぜないようにします。\n- 長く生きる teammate と background 実行の runtime slot が混ざり始めたら、[`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md) で goal / execution の境界を先に固めます。\n\n## まず用語をはっきり分ける\n\n### teammate とは何か\n\nここでの `teammate` は:\n\n> 名前、役割、inbox、lifecycle を持ち、複数ターンにまたがって system 内へ残る agent\n\nのことです。\n\n重要なのは「賢い helper」ではなく、**持続する actor** だという点です。\n\n### roster とは何か\n\n`roster` は team member の名簿です。\n\n少なくとも次を答えられる必要があります。\n\n- 今 team に誰がいるか\n- その人の role は何か\n- その人は idle か、working か、shutdown 済みか\n\n### mailbox とは何か\n\n`mailbox` は各 teammate が持つ受信箱です。\n\n他の member はそこへ message を送ります。  \n受信側は、自分の次の work loop に入る前に mailbox を drain します。\n\nこの設計の利点は、協調が次のように見えることです。\n\n- 誰が誰に送ったか\n- どの member がまだ未読か\n- どの message が actor 間通信なのか\n\n## 最小心智モデル\n\nこの章をいちばん壊れにくく理解する方法は、各 teammate を次のように見ることです。\n\n> 自分の `messages`、自分の mailbox、自分の agent loop を持った長期 actor\n\n```text\nlead\n  |\n  +-- spawn alice (tester)\n  +-- spawn bob (refactorer)\n  |\n  +-- send message -> alice inbox\n  +-- send message -> bob inbox\n\nalice\n  |\n  +-- 自分の messages\n  +-- 自分の inbox\n  +-- 自分の agent loop\n\nbob\n  |\n  +-- 自分の messages\n  +-- 自分の inbox\n  +-- 自分の agent loop\n```\n\nこの章の一番大事な対比は次です。\n\n- subagent: 一回きりの探索 helper\n- teammate: 長く存在し続ける協調 member\n\n## それまでの章にどう接続するか\n\n`s15` は単に「人数を増やす章」ではありません。  \n`s12-s14` でできた task / runtime / schedule の上に、**長く残る実行者層**を足す章です。\n\n接続の主線は次です。\n\n```text\nlead が「長く担当させたい仕事」を見つける\n  ->\nteammate を spawn する\n  ->\nteam roster に登録する\n  ->\nmailbox に仕事の手がかりや依頼を送る\n  ->\nteammate が自分の inbox を drain する\n  ->\n自分の agent loop と tools を回す\n  ->\n結果を message / task update として返す\n```\n\nここで見失ってはいけない境界は 4 つです。\n\n1. `s12-s14` が作ったのは work layer であり、ここでは actor layer を足している\n2. `s15` の default はまだ lead 主導である\n3. structured protocol は次章 `s16`\n4. autonomous claim は `s17`\n\nつまりこの章は、team system の中でもまだ:\n\n- 名付ける\n- 残す\n- 送る\n- 受け取る\n\nという基礎層を作っている段階です。\n\n## 主要データ構造\n\n### `TeamMember`\n\n```python\nmember = {\n    \"name\": \"alice\",\n    \"role\": \"tester\",\n    \"status\": \"working\",\n}\n```\n\n教学版では、まずこの 3 つが揃っていれば十分です。\n\n- `name`: 誰か\n- `role`: 何を主に担当するか\n- `status`: 今どういう状態か\n\n最初から大量の field を足す必要はありません。  \nこの章で大事なのは「長く存在する actor が立ち上がること」です。\n\n### `TeamConfig`\n\n```python\nconfig = {\n    \"team_name\": \"default\",\n    \"members\": [member1, member2],\n}\n```\n\n通常は次のような場所に置きます。\n\n```text\n.team/config.json\n```\n\nこの record があると system は再起動後も、\n\n- 以前誰がいたか\n- 誰がどの role を持っていたか\n\nを失わずに済みます。\n\n### `MessageEnvelope`\n\n```python\nmessage = {\n    \"type\": \"message\",\n    \"from\": \"lead\",\n    \"to\": \"alice\",\n    \"content\": \"Please review auth module.\",\n    \"timestamp\": 1710000000.0,\n}\n```\n\n`envelope` は「本文だけでなくメタ情報も含めて包んだ 1 件の message record」です。\n\nこれを使う理由:\n\n- sender が分かる\n- receiver が分かる\n- message type を分けられる\n- mailbox を durable channel として扱える\n\n## 最小実装の進め方\n\n### Step 1: まず roster を持つ\n\n```python\nclass TeammateManager:\n    def __init__(self, team_dir: Path):\n        self.team_dir = team_dir\n        self.config_path = team_dir / \"config.json\"\n        self.config = self._load_config()\n```\n\nこの章の起点は roster です。  \nroster がないまま team を語ると、結局「今この場で数回呼び出した model たち」にしか見えません。\n\n### Step 2: teammate を spawn する\n\n```python\ndef spawn(self, name: str, role: str, prompt: str):\n    member = {\"name\": name, \"role\": role, \"status\": \"working\"}\n    self.config[\"members\"].append(member)\n    self._save_config()\n\n    thread = threading.Thread(\n        target=self._teammate_loop,\n        args=(name, role, prompt),\n        daemon=True,\n    )\n    thread.start()\n```\n\nここで大切なのは thread という実装選択そのものではありません。  \n大切なのは次のことです。\n\n**一度 spawn された teammate は、一回限りの tool call ではなく、継続する lifecycle を持つ**\n\n### Step 3: 各 teammate に mailbox を持たせる\n\n教学版で一番分かりやすいのは JSONL inbox です。\n\n```text\n.team/inbox/alice.jsonl\n.team/inbox/bob.jsonl\n```\n\n送信側:\n\n```python\ndef send(self, sender: str, to: str, content: str):\n    with open(f\"{to}.jsonl\", \"a\") as f:\n        f.write(json.dumps({\n            \"type\": \"message\",\n            \"from\": sender,\n            \"to\": to,\n            \"content\": content,\n            \"timestamp\": time.time(),\n        }) + \"\\n\")\n```\n\n受信側:\n\n1. すべて読む\n2. JSON として parse する\n3. 読み終わったら inbox を drain する\n\nここで教えたいのは storage trick ではありません。\n\n教えたいのは:\n\n**協調は shared `messages[]` ではなく、mailbox boundary を通して起こる**\n\nという構造です。\n\n### Step 4: teammate は毎ラウンド mailbox を先に確認する\n\n```python\ndef teammate_loop(name: str, role: str, prompt: str):\n    messages = [{\"role\": \"user\", \"content\": prompt}]\n\n    while True:\n        inbox = bus.read_inbox(name)\n        for item in inbox:\n            messages.append({\"role\": \"user\", \"content\": json.dumps(item)})\n\n        response = client.messages.create(...)\n        ...\n```\n\nこの step をあいまいにすると、読者はすぐこう誤解します。\n\n- 新しい仕事を与えるたびに teammate を再生成するのか\n- 元の context はどこに残るのか\n\n正しくは:\n\n- teammate は残る\n- messages も残る\n- 新しい仕事は inbox 経由で入る\n- 次ラウンドに入る前に mailbox を見る\n\nです。\n\n## Teammate / Subagent / Runtime Slot をどう分けるか\n\nこの段階で最も混ざりやすいのはこの 3 つです。  \n次の表をそのまま覚えて構いません。\n\n| 仕組み | 何に近いか | lifecycle | 核心境界 |\n|---|---|---|---|\n| subagent | 一回きりの外部委託 helper | 作って、少し働いて、終わる | 小さな探索文脈の隔離 |\n| runtime slot | 実行中の background slot | その実行が終われば消える | 長い execution を追跡する |\n| teammate | 長期に残る team member | idle と working を行き来する | 名前、role、mailbox、独立 loop |\n\n口語的に言い換えると:\n\n- subagent: 「ちょっと調べて戻ってきて」\n- runtime slot: 「これは裏で走らせて、あとで知らせて」\n- teammate: 「あなたは今後しばらくテスト担当ね」\n\n## ここで教えるべき境界\n\nこの章でまず固めるべきは 3 つだけです。\n\n- roster\n- mailbox\n- 独立 loop\n\nこれだけで「長く残る teammate」という実体は十分立ち上がります。\n\nただし、まだここでは教え過ぎない方がよいものがあります。\n\n### 1. protocol request layer\n\nつまり:\n\n- どの message が普通の会話か\n- どの message が `request_id` を持つ構造化 request か\n\nこれは `s16` の範囲です。\n\n### 2. autonomous claim layer\n\nつまり:\n\n- teammate が自分で仕事を探すか\n- どの policy で self-claim するか\n- resume は何を根拠に行うか\n\nこれは `s17` の範囲です。\n\n`s15` の default はあくまで:\n\n- lead が作る\n- lead が送る\n- teammate が受ける\n\nです。\n\n## 初学者が特によくやる間違い\n\n### 1. teammate を「名前付き subagent」にする\n\n名前が付いていても、実装が\n\n```text\nspawn -> work -> summary -> destroy\n```\n\nなら本質的にはまだ subagent です。\n\n### 2. team 全員で 1 本の `messages` を共有する\n\nこれは一見簡単ですが、文脈汚染がすぐ起きます。\n\n各 teammate は少なくとも:\n\n- 自分の messages\n- 自分の inbox\n- 自分の status\n\nを持つべきです。\n\n### 3. roster を durable にしない\n\nsystem を止めた瞬間に「team に誰がいたか」を完全に失うなら、長期 actor layer としてはかなり弱いです。\n\n### 4. mailbox なしで shared variable だけで会話させる\n\n実装は短くできますが、teammate 間協調の境界が見えなくなります。  \n教学 repo では durable mailbox を置いた方が、読者の心智がずっと安定します。\n\n## 学び終わったら言えるべきこと\n\n少なくとも次の 4 つを自分の言葉で説明できれば、この章の主線は掴めています。\n\n1. teammate の本質は「多 model」ではなく「長期に残る actor identity」である\n2. team system の最小構成は「roster + mailbox + 独立 loop」である\n3. subagent と teammate の違いは lifecycle の長さにある\n4. teammate と runtime slot の違いは、「actor identity」か「live execution」かにある\n\n## 次章で何を足すか\n\nこの章が解いているのは:\n\n> team member が長く存在し、互いに message を送り合えるようにすること\n\n次章 `s16` が解くのは:\n\n> message が単なる自由文ではなく、追跡・承認・拒否・期限切れを持つ protocol object になるとき、どう設計するか\n\nつまり `s15` が「team の存在」を作り、`s16` が「team の構造化協調」を作ります。\n"
  },
  {
    "version": "s16",
    "slug": "s16-team-protocols",
    "locale": "ja",
    "title": "s16: Team Protocols",
    "kind": "chapter",
    "filename": "s16-team-protocols.md",
    "content": "# s16: Team Protocols\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > [ s16 ] > s17 > s18 > s19`\n\n> *mailbox があるだけでは「話せる team」に過ぎません。protocol が入って初めて、「規則に従って協調できる team」になります。*\n\n## この章が解く問題\n\n`s15` までで teammate 同士は message を送り合えます。\n\nしかし自由文だけに頼ると、すぐに 2 つの問題が出ます。\n\n- 明確な承認 / 拒否が必要な場面で、曖昧な返事しか残らない\n- request が複数同時に走ると、どの返答がどの件に対応するのか分からなくなる\n\n特に分かりやすいのは次の 2 場面です。\n\n1. graceful shutdown を依頼したい\n2. 高リスク plan を実行前に approval したい\n\n一見別の話に見えても、骨格は同じです。\n\n```text\nrequester が request を送る\n  ->\nreceiver が明確に response する\n  ->\n両者が同じ request_id で対応関係を追える\n```\n\nこの章で追加するのは message の量ではなく、\n\n**追跡可能な request-response protocol**\n\nです。\n\n## 併読すると楽になる資料\n\n- 普通の message と protocol request が混ざったら [`glossary.md`](./glossary.md) と [`entity-map.md`](./entity-map.md)\n- `s17` や `s18` に進む前に境界を固めたいなら [`team-task-lane-model.md`](./team-task-lane-model.md)\n- request が主システムへどう戻るか見直したいなら [`s00b-one-request-lifecycle.md`](./s00b-one-request-lifecycle.md)\n\n## 先に言葉をそろえる\n\n### protocol とは何か\n\nここでの `protocol` は難しい通信理論ではありません。\n\n意味は、\n\n> message の形、処理手順、状態遷移を事前に決めた協調ルール\n\nです。\n\n### request_id とは何か\n\n`request_id` は request の一意な番号です。\n\n役割は 1 つで、\n\n> 後から届く response や status update を、元の request と正確に結びつけること\n\nです。\n\n### request-response pattern とは何か\n\nこれも難しく考える必要はありません。\n\n```text\nrequester: この操作をしたい\nreceiver: 承認する / 拒否する\n```\n\nこの往復を、自然文の雰囲気で済ませず、**構造化 record として残す**のがこの章です。\n\n## 最小心智モデル\n\n教学上は、protocol を 2 層で見ると分かりやすくなります。\n\n```text\n1. protocol envelope\n2. durable request record\n```\n\n### protocol envelope\n\nこれは inbox を流れる 1 通の構造化 message です。\n\n```python\n{\n    \"type\": \"shutdown_request\",\n    \"from\": \"lead\",\n    \"to\": \"alice\",\n    \"request_id\": \"req_001\",\n    \"payload\": {},\n}\n```\n\n### durable request record\n\nこれは request の lifecycle を disk に追う record です。\n\n```python\n{\n    \"request_id\": \"req_001\",\n    \"kind\": \"shutdown\",\n    \"from\": \"lead\",\n    \"to\": \"alice\",\n    \"status\": \"pending\",\n}\n```\n\nこの 2 層がそろうと system は、\n\n- いま何を送ったのか\n- その request は今どの状態か\n\nを両方説明できるようになります。\n\n## この章の核になるデータ構造\n\n### 1. ProtocolEnvelope\n\nprotocol message は普通の message より多くのメタデータを持ちます。\n\n```python\nmessage = {\n    \"type\": \"shutdown_request\",\n    \"from\": \"lead\",\n    \"to\": \"alice\",\n    \"request_id\": \"req_001\",\n    \"payload\": {},\n    \"timestamp\": 1710000000.0,\n}\n```\n\n特に重要なのは次の 3 つです。\n\n- `type`: これは何の protocol message か\n- `request_id`: どの request thread に属するか\n- `payload`: 本文以外の構造化内容\n\n### 2. RequestRecord\n\nrequest record は `.team/requests/` に durable に保存されます。\n\n```python\nrequest = {\n    \"request_id\": \"req_001\",\n    \"kind\": \"shutdown\",\n    \"from\": \"lead\",\n    \"to\": \"alice\",\n    \"status\": \"pending\",\n    \"created_at\": 1710000000.0,\n    \"updated_at\": 1710000000.0,\n}\n```\n\nこの record があることで、system は message を送ったあとでも request の状態を追い続けられます。\n\n教材コードでは実際に次のような path を使います。\n\n```text\n.team/requests/\n  req_001.json\n  req_002.json\n```\n\nこれにより、\n\n- request の状態を再読込できる\n- protocol の途中経過をあとから確認できる\n- main loop が先へ進んでも request thread が消えない\n\nという利点が生まれます。\n\n### 3. 状態機械\n\nこの章の state machine は難しくありません。\n\n```text\npending -> approved\npending -> rejected\npending -> expired\n```\n\nここで大事なのは theory ではなく、\n\n**承認系の協調には「いまどの状態か」を explicit に持つ必要がある**\n\nということです。\n\n## 最小実装を段階で追う\n\n### 第 1 段階: team mailbox の上に protocol line を通す\n\nこの章の本質は新しい message type を 2 個足すことではありません。\n\n本質は、\n\n```text\nrequester が protocol action を開始する\n  ->\nrequest record を保存する\n  ->\nprotocol envelope を inbox に送る\n  ->\nreceiver が request_id 付きで response する\n  ->\nrecord の status を更新する\n```\n\nという一本の durable flow を通すことです。\n\n### 第 2 段階: shutdown protocol を作る\n\ngraceful shutdown は「thread を即 kill する」ことではありません。\n\n正しい流れは次です。\n\n1. shutdown request を作る\n2. teammate が approve / reject を返す\n3. approve なら後始末して終了する\n\nrequest 側の最小形はこうです。\n\n```python\ndef request_shutdown(target: str):\n    request_id = new_id()\n    REQUEST_STORE.create({\n        \"request_id\": request_id,\n        \"kind\": \"shutdown\",\n        \"from\": \"lead\",\n        \"to\": target,\n        \"status\": \"pending\",\n    })\n    BUS.send(\n        \"lead\",\n        target,\n        \"Please shut down gracefully.\",\n        \"shutdown_request\",\n        {\"request_id\": request_id},\n    )\n```\n\nresponse 側は request_id を使って同じ record を更新します。\n\n```python\ndef handle_shutdown_response(request_id: str, approve: bool):\n    record = REQUEST_STORE.update(\n        request_id,\n        status=\"approved\" if approve else \"rejected\",\n    )\n```\n\n### 第 3 段階: plan approval も同じ骨格で扱う\n\n高リスクな変更を teammate が即時実行してしまうと危険なことがあります。\n\nそこで plan approval protocol を入れます。\n\n```python\ndef submit_plan(name: str, plan_text: str):\n    request_id = new_id()\n    REQUEST_STORE.create({\n        \"request_id\": request_id,\n        \"kind\": \"plan_approval\",\n        \"from\": name,\n        \"to\": \"lead\",\n        \"status\": \"pending\",\n        \"plan\": plan_text,\n    })\n```\n\nlead はその `request_id` を見て承認または却下します。\n\n```python\ndef review_plan(request_id: str, approve: bool, feedback: str = \"\"):\n    REQUEST_STORE.update(\n        request_id,\n        status=\"approved\" if approve else \"rejected\",\n        feedback=feedback,\n    )\n```\n\nここで伝えたい中心は、\n\n**shutdown と plan approval は中身は違っても、request-response correlation の骨格は同じ**\n\nという点です。\n\n## Message / Protocol / Request / Task の境界\n\nこの章で最も混ざりやすい 4 つを表で分けます。\n\n| オブジェクト | 何を答えるか | 典型 field |\n|---|---|---|\n| `MessageEnvelope` | 誰が誰に何を送ったか | `from`, `to`, `content` |\n| `ProtocolEnvelope` | それが構造化 request / response か | `type`, `request_id`, `payload` |\n| `RequestRecord` | その協調フローはいまどこまで進んだか | `kind`, `status`, `from`, `to` |\n| `TaskRecord` | 実際の work goal は何か | `subject`, `status`, `owner`, `blockedBy` |\n\nここで絶対に混ぜないでほしい点は次です。\n\n- protocol request は task そのものではない\n- request store は task board ではない\n- protocol は協調フローを追う\n- task は仕事の進行を追う\n\n## `s15` から何が増えたか\n\n`s15` の team system は「話せる team」でした。\n\n`s16` ではそこへ、\n\n- request_id\n- durable request store\n- approved / rejected の explicit status\n- protocol-specific message type\n\nが入ります。\n\nすると team は単なる chat 集合ではなく、\n\n**追跡可能な coordination system**\n\nに進みます。\n\n## 初学者が混ぜやすいポイント\n\n### 1. request を普通の text message と同じように扱う\n\nこれでは承認状態を追えません。\n\n### 2. request_id を持たせない\n\n同時に複数 request が走った瞬間に対応関係が壊れます。\n\n### 3. request の状態を memory 内 dict にしか置かない\n\nプロセスをまたいで追えず、観測性も悪くなります。\n\n### 4. approved / rejected を曖昧な文章だけで表す\n\nstate machine が読めなくなります。\n\n### 5. protocol と task を混同する\n\nplan approval request は「plan を実行してよいか」の協調であって、work item 本体ではありません。\n\n## 前の章とどうつながるか\n\nこの章は `s15` の mailbox-based team を次の段階へ押し上げます。\n\n- `s15`: teammate が message を送れる\n- `s16`: teammate が structured protocol で協調できる\n\nそしてこの先、\n\n- `s17`: idle teammate が自分で task を claim する\n- `s18`: task ごとに isolation lane を持つ\n\nへ進む準備になります。\n\nもしここで protocol の境界が曖昧なままだと、後の autonomy や worktree を読むときに\n\n- 誰が誰に依頼したのか\n- どの state が協調の state で、どれが work の state か\n\nがすぐ混ざります。\n\n## 教学上の境界\n\nこの章でまず教えるべきのは、製品に存在しうる全 protocol の一覧ではありません。\n\n中心は次の 3 点です。\n\n- request と response を同じ `request_id` で結び付けること\n- 承認状態を explicit state として残すこと\n- team coordination を自由文から durable workflow へ進めること\n\nここが見えていれば、後から protocol の種類が増えても骨格は崩れません。\n"
  },
  {
    "version": "s17",
    "slug": "s17-autonomous-agents",
    "locale": "ja",
    "title": "s17: Autonomous Agents",
    "kind": "chapter",
    "filename": "s17-autonomous-agents.md",
    "content": "# s17: Autonomous Agents\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > [ s17 ] > s18 > s19`\n\n> *本当にチームらしくなる瞬間は、人数が増えたときではなく、空いている teammate が次の仕事を自分で拾えるようになったときです。*\n\n## この章が解く問題\n\n`s16` まで来ると、チームにはすでに次のものがあります。\n\n- 長く生きる teammate\n- inbox\n- protocol request / response\n- task board\n\nそれでも、まだ 1 つ大きな詰まりが残っています。\n\n**仕事の割り振りが lead に集中しすぎることです。**\n\nたとえば task board に ready な task が 10 個あっても、\n\n- Alice はこれ\n- Bob はこれ\n- Charlie はこれ\n\nと lead が 1 件ずつ指名し続けるなら、team は増えても coordination の中心は 1 人のままです。\n\nこの章で入れるのは、\n\n**空いている teammate が、自分で board を見て、取ってよい task を安全に claim する仕組み**\n\nです。\n\n## 併読すると楽になる資料\n\n- teammate / task / runtime slot の境界が怪しくなったら [`team-task-lane-model.md`](./team-task-lane-model.md)\n- `auto-claim` を読んで runtime record の置き場所が曖昧なら [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n- 長期 teammate と一回限りの subagent の違いが薄れたら [`entity-map.md`](./entity-map.md)\n\n## 先に言葉をそろえる\n\n### 自治とは何か\n\nここで言う `autonomous` は、\n\n> 何の制御もなく勝手に暴走すること\n\nではありません。\n\n正しくは、\n\n> 事前に与えたルールに従って、空いている teammate が次の仕事を自分で選べること\n\nです。\n\nつまり自治は自由放任ではなく、**規則付きの自律再開**です。\n\n### claim とは何か\n\n`claim` は、\n\n> まだ owner が付いていない task を「今から自分が担当する」と確定させること\n\nです。\n\n「見つける」だけでは不十分で、**owner を書き込み、他の teammate が同じ task を取らないようにする**ところまでが claim です。\n\n### idle とは何か\n\n`idle` は終了でも停止でもありません。\n\n意味は次の通りです。\n\n> 今この teammate には active work がないが、まだ system の中で生きていて、新しい input を待てる状態\n\nです。\n\n## 最小心智モデル\n\nこの章を最も簡単に捉えるなら、teammate の lifecycle を 2 フェーズで見ます。\n\n```text\nWORK\n  |\n  | 今の作業を終える / idle を選ぶ\n  v\nIDLE\n  |\n  +-- inbox に新着がある -> WORK\n  |\n  +-- task board に claimable task がある -> claim -> WORK\n  |\n  +-- 一定時間なにもない -> shutdown\n```\n\nここで大事なのは、\n\n**main loop を無限に回し続けることではなく、idle 中に何を見て、どの順番で resume するか**\n\nです。\n\n## この章の核になるデータ構造\n\n### 1. Claimable Predicate\n\n最初に理解すべきなのは、\n\n> どんな task なら「この teammate が今 claim してよい」と判定できるのか\n\nです。\n\n教材コードでは、判定は単に `status == \"pending\"` では終わりません。\n\n```python\ndef is_claimable_task(task: dict, role: str | None = None) -> bool:\n    return (\n        task.get(\"status\") == \"pending\"\n        and not task.get(\"owner\")\n        and not task.get(\"blockedBy\")\n        and _task_allows_role(task, role)\n    )\n```\n\nこの 4 条件はそれぞれ別の意味を持ちます。\n\n- `status == \"pending\"`: まだ開始していない\n- `not owner`: まだ誰も担当していない\n- `not blockedBy`: 前提 task が残っていない\n- `_task_allows_role(...)`: この teammate の role が claim policy に合っている\n\n最後の条件が特に重要です。\n\ntask は今の教材コードでは次のような role 制約を持てます。\n\n- `claim_role`\n- `required_role`\n\nたとえば、\n\n```python\n{\n    \"id\": 7,\n    \"subject\": \"Implement login page\",\n    \"status\": \"pending\",\n    \"owner\": \"\",\n    \"blockedBy\": [],\n    \"claim_role\": \"frontend\",\n}\n```\n\nなら、空いている teammate 全員が取れるわけではありません。\n\n**frontend role の teammate だけが claim 候補になります。**\n\n### 2. Claim 後の TaskRecord\n\nclaim が成功すると、task record は少なくとも次のように更新されます。\n\n```python\n{\n    \"id\": 7,\n    \"owner\": \"alice\",\n    \"status\": \"in_progress\",\n    \"claimed_at\": 1710000000.0,\n    \"claim_source\": \"auto\",\n}\n```\n\nこの中で初心者が見落としやすいのは `claimed_at` と `claim_source` です。\n\n- `claimed_at`: いつ取られたか\n- `claim_source`: 手動か自動か\n\nこれがあることで system は、\n\n- 今だれが担当しているか\n- その担当は lead の指名か\n- それとも idle scan による auto-claim か\n\nをあとから説明できます。\n\n### 3. Claim Event Log\n\ntask file の更新だけでは、今の最終状態しか見えません。\n\nそこでこの章では claim 操作を別の append-only log にも書きます。\n\n```text\n.tasks/claim_events.jsonl\n```\n\n中身のイメージはこうです。\n\n```python\n{\n    \"event\": \"task.claimed\",\n    \"task_id\": 7,\n    \"owner\": \"alice\",\n    \"role\": \"frontend\",\n    \"source\": \"auto\",\n    \"ts\": 1710000000.0,\n}\n```\n\nこの log があると、\n\n- task がいつ取られたか\n- 誰が取ったか\n- 手動か自動か\n\nが current state とは別に追えます。\n\n### 4. Durable Request Record\n\n`s17` は autonomy を追加する章ですが、`s16` の protocol line を捨てる章ではありません。\n\nそのため shutdown や plan approval の request は引き続き disk に保存されます。\n\n```text\n.team/requests/{request_id}.json\n```\n\nこれは重要です。\n\nなぜなら autonomous teammate は、\n\n> protocol を無視して好きに動く worker\n\nではなく、\n\n> 既存の protocol system の上で、idle 時に自分で次の仕事を探せる teammate\n\nだからです。\n\n### 5. Identity Block\n\ncompact の後や idle からの復帰直後は、teammate が自分の identity を見失いやすくなります。\n\nそのため教材コードには identity block の再注入があります。\n\n```python\n{\n    \"role\": \"user\",\n    \"content\": \"<identity>You are 'alice', role: frontend, team: default. Continue your work.</identity>\",\n}\n```\n\nさらに短い assistant acknowledgement も添えています。\n\n```python\n{\"role\": \"assistant\", \"content\": \"I am alice. Continuing.\"}\n```\n\nこの 2 行は装飾ではありません。\n\nここで守っているのは次の 3 点です。\n\n- 私は誰か\n- どの role か\n- どの team に属しているか\n\n## 最小実装を段階で追う\n\n### 第 1 段階: WORK と IDLE を分ける\n\nまず teammate loop を 2 フェーズに分けます。\n\n```python\nwhile True:\n    run_work_phase(...)\n    should_resume = run_idle_phase(...)\n    if not should_resume:\n        break\n```\n\nこれで初めて、\n\n- いま作業中なのか\n- いま待機中なのか\n- 次に resume する理由は何か\n\nを分けて考えられます。\n\n### 第 2 段階: idle では先に inbox を見る\n\n`idle` に入ったら最初に見るべきは task board ではなく inbox です。\n\n```python\ndef idle_phase(name: str, messages: list) -> bool:\n    inbox = bus.read_inbox(name)\n    if inbox:\n        messages.append({\n            \"role\": \"user\",\n            \"content\": json.dumps(inbox),\n        })\n        return True\n```\n\n理由は単純で、\n\n**明示的に自分宛てに来た仕事の方が、board 上の一般 task より優先度が高い**\n\nからです。\n\n### 第 3 段階: inbox が空なら role 付きで task board を走査する\n\n```python\nunclaimed = scan_unclaimed_tasks(role)\nif unclaimed:\n    task = unclaimed[0]\n    claim_result = claim_task(\n        task[\"id\"],\n        name,\n        role=role,\n        source=\"auto\",\n    )\n```\n\nここでの要点は 2 つです。\n\n- `scan_unclaimed_tasks(role)` は role を無視して全件取るわけではない\n- `source=\"auto\"` を書いて claim の由来を残している\n\nつまり自治とは、\n\n> 何でも空いていれば奪うこと\n\nではなく、\n\n> role、block 状態、owner 状態を見たうえで、今この teammate に許された仕事だけを取ること\n\nです。\n\n### 第 4 段階: claim 後は identity と task hint を両方戻す\n\nclaim 成功後は、そのまま resume してはいけません。\n\n```python\nensure_identity_context(messages, name, role, team_name)\nmessages.append({\n    \"role\": \"user\",\n    \"content\": f\"<auto-claimed>Task #{task['id']}: {task['subject']}</auto-claimed>\",\n})\nmessages.append({\n    \"role\": \"assistant\",\n    \"content\": f\"{claim_result}. Working on it.\",\n})\nreturn True\n```\n\nこの段で context に戻しているのは 2 種類の情報です。\n\n- identity: この teammate は誰か\n- fresh work item: いま何を始めたのか\n\nこの 2 つがそろって初めて、次の WORK phase が迷わず進みます。\n\n### 第 5 段階: 長時間なにもなければ shutdown する\n\nidle teammate を永久に残す必要はありません。\n\n教材版では、\n\n> 一定時間 inbox も task board も空なら shutdown\n\nという単純な出口で十分です。\n\nここでの主眼は resource policy の最適化ではなく、\n\n**idle からの再開条件と終了条件を明示すること**\n\nです。\n\n## なぜ claim は原子的でなければならないか\n\n`atomic` という言葉は難しく見えますが、ここでは次の意味です。\n\n> claim 処理は「全部成功する」か「起きない」かのどちらかでなければならない\n\n理由は race condition です。\n\nAlice と Bob が同時に同じ task を見たら、\n\n- Alice も `owner == \"\"` を見る\n- Bob も `owner == \"\"` を見る\n- 両方が自分を owner として保存する\n\nという事故が起こりえます。\n\nそのため教材コードでも lock を使っています。\n\n```python\nwith claim_lock:\n    task = load(task_id)\n    if task[\"owner\"]:\n        return \"already claimed\"\n    task[\"owner\"] = name\n    task[\"status\"] = \"in_progress\"\n    save(task)\n```\n\n初心者向けに言い換えるなら、\n\n**claim は「見てから書く」までを他の teammate に割り込まれずに一気に行う**\n\n必要があります。\n\n## identity 再注入が重要な理由\n\nこれは地味ですが、自治の品質を大きく左右します。\n\ncompact の後や long-lived teammate の再開時には、context 冒頭から次の情報が薄れがちです。\n\n- 私は誰か\n- 何 role か\n- どの team か\n\nこの状態で work を再開すると、\n\n- role に合わない判断をしやすくなる\n- protocol 上の責務を忘れやすくなる\n- それまでの persona がぶれやすくなる\n\nだから教材版では、\n\n> idle から戻る前、または compact 後に identity が薄いなら再注入する\n\nという復帰ルールを置いています。\n\n## `s17` は `s16` を上書きしない\n\nここは誤解しやすいので強調します。\n\n`s17` で増えるのは autonomy ですが、だからといって `s16` の protocol layer が消えるわけではありません。\n\n両者はこういう関係です。\n\n```text\ns16:\n  request_id を持つ durable protocol\n\ns17:\n  idle teammate が board を見て次の仕事を探せる\n```\n\nつまり `s17` は、\n\n**protocol がある team に autonomy を足す章**\n\nであって、\n\n**自由に動く worker 群へ退化させる章**\n\nではありません。\n\n## 前の章とどうつながるか\n\nこの章は前の複数章が初めて強く結びつく場所です。\n\n- `s12`: task board を作る\n- `s15`: persistent teammate を作る\n- `s16`: request / response protocol を作る\n- `s17`: 指名がなくても次の work を自分で取れるようにする\n\nしたがって `s17` は、\n\n**受け身の team から、自分で回り始める team への橋渡し**\n\nと考えると分かりやすいです。\n\n## 自治するのは long-lived teammate であって subagent ではない\n\nここで `s04` と混ざる人が多いです。\n\nこの章の actor は one-shot subagent ではありません。\n\nこの章の teammate は次の特徴を持ちます。\n\n- 名前がある\n- role がある\n- inbox がある\n- idle state がある\n- 複数回 task を受け取れる\n\n一方、subagent は通常、\n\n- 一度 delegated work を受ける\n- 独立 context で処理する\n- summary を返して終わる\n\nという使い方です。\n\nまた、この章で claim する対象は `s12` の task であり、`s13` の runtime slot ではありません。\n\n## 初学者が混ぜやすいポイント\n\n### 1. `pending` だけ見て `blockedBy` を見ない\n\ntask が `pending` でも dependency が残っていればまだ取れません。\n\n### 2. role 条件を無視する\n\n`claim_role` や `required_role` を見ないと、間違った teammate が task を取ります。\n\n### 3. claim lock を置かない\n\n同一 task の二重 claim が起こります。\n\n### 4. idle 中に board しか見ない\n\nこれでは明示的な inbox message を取りこぼします。\n\n### 5. event log を書かない\n\n「いま誰が持っているか」は分かっても、\n\n- いつ取ったか\n- 自動か手動か\n\nが追えません。\n\n### 6. idle teammate を永遠に残す\n\n教材版では shutdown 条件を持たせた方が lifecycle を理解しやすくなります。\n\n### 7. compact 後に identity を戻さない\n\n長く動く teammate ほど、identity drift が起きやすくなります。\n\n## 教学上の境界\n\nこの章でまず掴むべき主線は 1 本です。\n\n**idle で待つ -> 安全に claim する -> identity を整えて work に戻る**\n\nここで学ぶ中心は自治の骨格であって、\n\n- 高度な scheduler 最適化\n- 分散環境での claim\n- 複雑な fairness policy\n\nではありません。\n\nその先へ進む前に、読者が自分の言葉で次の 1 文を言えることが大切です。\n\n> autonomous teammate とは、空いたときに勝手に暴走する worker ではなく、inbox と task board を規則通りに見て、取ってよい仕事だけを自分で取りにいける長期 actor である。\n"
  },
  {
    "version": "s18",
    "slug": "s18-worktree-task-isolation",
    "locale": "ja",
    "title": "s18: Worktree + Task Isolation",
    "kind": "chapter",
    "filename": "s18-worktree-task-isolation.md",
    "content": "# s18: Worktree + Task Isolation\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > [ s18 ] > s19`\n\n> *task board が答えるのは「何をやるか」、worktree が答えるのは「どこでやるか、しかも互いに踏み荒らさずに」です。*\n\n## この章が解く問題\n\n`s17` までで system はすでに次のことができます。\n\n- task を作る\n- teammate が task を claim する\n- 複数の teammate が並行に作業する\n\nそれでも、全員が同じ working directory で作業するなら、すぐに限界が来ます。\n\n典型的な壊れ方は次の通りです。\n\n- 2 つの task が同じ file を同時に編集する\n- 片方の未完了変更がもう片方の task を汚染する\n- 「この task の変更だけ見たい」が非常に難しくなる\n\nつまり `s12-s17` までで答えられていたのは、\n\n**誰が何をやるか**\n\nまでであって、\n\n**その仕事をどの execution lane で進めるか**\n\nはまだ答えられていません。\n\nそれを担当するのが `worktree` です。\n\n## 併読すると楽になる資料\n\n- task / runtime slot / worktree lane が同じものに見えたら [`team-task-lane-model.md`](./team-task-lane-model.md)\n- task record と worktree record に何を保存すべきか確認したいなら [`data-structures.md`](./data-structures.md)\n- なぜ worktree の章が tasks / teams より後ろに来るか再確認したいなら [`s00e-reference-module-map.md`](./s00e-reference-module-map.md)\n\n## 先に言葉をそろえる\n\n### worktree とは何か\n\nGit に慣れている人なら、\n\n> 同じ repository を別ディレクトリへ独立 checkout した作業コピー\n\nと見て構いません。\n\nまだ Git の言葉に慣れていないなら、まずは次の理解で十分です。\n\n> 1 つの task に割り当てる専用の作業レーン\n\n### isolation とは何か\n\n`isolation` は、\n\n> task A は task A の directory で実行し、task B は task B の directory で実行して、未コミット変更を最初から共有しないこと\n\nです。\n\n### binding とは何か\n\n`binding` は、\n\n> task ID と worktree record を明示的に結びつけること\n\nです。\n\nこれがないと、system は「この directory が何のために存在しているのか」を説明できません。\n\n## 最小心智モデル\n\nこの章は 2 枚の表を別物として見ると一気に分かりやすくなります。\n\n```text\nTask Board\n  - 何をやるか\n  - 誰が持っているか\n  - 今どの状態か\n\nWorktree Registry\n  - どこでやるか\n  - どの branch / path か\n  - どの task に結び付いているか\n```\n\n両者は `task_id` でつながります。\n\n```text\n.tasks/task_12.json\n  {\n    \"id\": 12,\n    \"subject\": \"Refactor auth flow\",\n    \"status\": \"in_progress\",\n    \"worktree\": \"auth-refactor\"\n  }\n\n.worktrees/index.json\n  {\n    \"worktrees\": [\n      {\n        \"name\": \"auth-refactor\",\n        \"path\": \".worktrees/auth-refactor\",\n        \"branch\": \"wt/auth-refactor\",\n        \"task_id\": 12,\n        \"status\": \"active\"\n      }\n    ]\n  }\n```\n\nこの 2 つを見て、\n\n- task は goal を記録する\n- worktree は execution lane を記録する\n\nと分けて理解できれば、この章の幹はつかめています。\n\n## この章の核になるデータ構造\n\n### 1. TaskRecord 側の lane 情報\n\nこの段階の教材コードでは、task 側に単に `worktree` という名前だけがあるわけではありません。\n\n```python\ntask = {\n    \"id\": 12,\n    \"subject\": \"Refactor auth flow\",\n    \"status\": \"in_progress\",\n    \"owner\": \"alice\",\n    \"worktree\": \"auth-refactor\",\n    \"worktree_state\": \"active\",\n    \"last_worktree\": \"auth-refactor\",\n    \"closeout\": None,\n}\n```\n\nそれぞれの意味は次の通りです。\n\n- `worktree`: 今この task がどの lane に結び付いているか\n- `worktree_state`: その lane が `active` / `kept` / `removed` / `unbound` のどれか\n- `last_worktree`: 直近で使っていた lane 名\n- `closeout`: 最後にどういう終わらせ方をしたか\n\nここが重要です。\n\ntask 側はもはや単に「現在の directory 名」を持っているだけではありません。\n\n**いま結び付いている lane と、最後にどう閉じたかまで記録し始めています。**\n\n### 2. WorktreeRecord\n\nworktree registry 側の record は path の写しではありません。\n\n```python\nworktree = {\n    \"name\": \"auth-refactor\",\n    \"path\": \".worktrees/auth-refactor\",\n    \"branch\": \"wt/auth-refactor\",\n    \"task_id\": 12,\n    \"status\": \"active\",\n    \"last_entered_at\": 1710000000.0,\n    \"last_command_at\": 1710000012.0,\n    \"last_command_preview\": \"pytest tests/auth -q\",\n    \"closeout\": None,\n}\n```\n\nここで答えているのは path だけではありません。\n\n- いつ lane に入ったか\n- 最近何を実行したか\n- どんな closeout が最後に行われたか\n\nつまり worktree record は、\n\n**directory mapping ではなく、観測可能な execution lane record**\n\nです。\n\n### 3. CloseoutRecord\n\ncloseout は「最後に削除したかどうか」だけではありません。\n\n教材コードでは次のような record を残します。\n\n```python\ncloseout = {\n    \"action\": \"keep\",\n    \"reason\": \"Need follow-up review\",\n    \"at\": 1710000100.0,\n}\n```\n\nこれにより system は、\n\n- keep したのか\n- remove したのか\n- なぜそうしたのか\n\nを state として残せます。\n\n初心者にとって大事なのはここです。\n\n**closeout は単なる cleanup コマンドではなく、execution lane の終わり方を明示する操作**\n\nです。\n\n### 4. Event Record\n\nworktree は lifecycle が長いので event log も必要です。\n\n```python\n{\n    \"event\": \"worktree.closeout.keep\",\n    \"task_id\": 12,\n    \"worktree\": \"auth-refactor\",\n    \"reason\": \"Need follow-up review\",\n    \"ts\": 1710000100.0,\n}\n```\n\nなぜ state file だけでは足りないかというと、lane の lifecycle には複数段階があるからです。\n\n- create\n- enter\n- run\n- keep\n- remove\n- remove failed\n\nappend-only の event があれば、いまの最終状態だけでなく、\n\n**そこへ至る途中の挙動**\n\nも追えます。\n\n## 最小実装を段階で追う\n\n### 第 1 段階: 先に task を作り、そのあと lane を作る\n\n順番は非常に大切です。\n\n```python\ntask = tasks.create(\"Refactor auth flow\")\nworktrees.create(\"auth-refactor\", task_id=task[\"id\"])\n```\n\nこの順番にする理由は、\n\n**worktree は task の代替ではなく、task にぶら下がる execution lane**\n\nだからです。\n\n最初に goal があり、そのあと goal に lane を割り当てます。\n\n### 第 2 段階: worktree を作り、registry に書く\n\n```python\ndef create(self, name: str, task_id: int):\n    path = self.root / \".worktrees\" / name\n    branch = f\"wt/{name}\"\n\n    run_git([\"worktree\", \"add\", \"-b\", branch, str(path), \"HEAD\"])\n\n    record = {\n        \"name\": name,\n        \"path\": str(path),\n        \"branch\": branch,\n        \"task_id\": task_id,\n        \"status\": \"active\",\n    }\n    self.index[\"worktrees\"].append(record)\n    self._save_index()\n```\n\nここで registry は次を答えられるようになります。\n\n- lane 名\n- 実 directory\n- branch\n- 対応 task\n- active かどうか\n\n### 第 3 段階: task record 側も同時に更新する\n\nlane registry を書くだけでは不十分です。\n\n```python\ndef bind_worktree(task_id: int, name: str):\n    task = tasks.load(task_id)\n    task[\"worktree\"] = name\n    task[\"last_worktree\"] = name\n    task[\"worktree_state\"] = \"active\"\n    if task[\"status\"] == \"pending\":\n        task[\"status\"] = \"in_progress\"\n    tasks.save(task)\n```\n\nなぜ両側へ書く必要があるか。\n\nもし registry だけ更新して task board 側を更新しなければ、\n\n- task 一覧から lane が見えない\n- closeout 時にどの task を終わらせるか分かりにくい\n- crash 後の再構成が不自然になる\n\nからです。\n\n### 第 4 段階: lane に入ることと、lane で command を実行することを分ける\n\n教材コードでは `enter` と `run` を分けています。\n\n```python\nworktree_enter(\"auth-refactor\")\nworktree_run(\"auth-refactor\", \"pytest tests/auth -q\")\n```\n\n底では本質的に次のことをしています。\n\n```python\ndef enter(self, name: str):\n    self._update_entry(name, last_entered_at=time.time())\n    self.events.emit(\"worktree.enter\", ...)\n\ndef run(self, name: str, command: str):\n    subprocess.run(command, cwd=worktree_path, ...)\n```\n\n特に大事なのは `cwd=worktree_path` です。\n\n同じ `pytest` でも、どの `cwd` で走るかによって影響範囲が変わります。\n\n`enter` を別操作として教える理由は、読者に次の境界を見せるためです。\n\n- lane を割り当てた\n- 実際にその lane へ入った\n- その lane で command を実行した\n\nこの 3 段階が分かれているからこそ、\n\n- `last_entered_at`\n- `last_command_at`\n- `last_command_preview`\n\nのような観測項目が自然に見えてきます。\n\n### 第 5 段階: 終わるときは closeout を明示する\n\n教材上は、`keep` と `remove` をバラバラの小技として見せるより、\n\n> closeout という 1 つの判断に 2 分岐ある\n\nと見せた方が心智が安定します。\n\n```python\nworktree_closeout(\n    name=\"auth-refactor\",\n    action=\"keep\",  # or \"remove\"\n    reason=\"Need follow-up review\",\n    complete_task=False,\n)\n```\n\nこれで読者は次のことを一度に理解できます。\n\n- lane の終わらせ方には選択肢がある\n- その選択には理由を持たせられる\n- closeout は task record / lane record / event log に反映される\n\nもちろん実装下層では、\n\n- `worktree_keep(name)`\n- `worktree_remove(name, reason=..., complete_task=True)`\n\nのような分離 API を持っていても構いません。\n\nただし教学の主線では、\n\n**closeout decision -> keep / remove**\n\nという形にまとめた方が初心者には伝わります。\n\n## なぜ `status` と `worktree_state` を分けるのか\n\nこれは非常に大事な区別です。\n\n初学者はよく、\n\n> task に `status` があるなら十分ではないか\n\nと考えます。\n\nしかし実際は答えている質問が違います。\n\n- `task.status`: その仕事が `pending` / `in_progress` / `completed` のどれか\n- `worktree_state`: その execution lane が `active` / `kept` / `removed` / `unbound` のどれか\n\nたとえば、\n\n```text\ntask は completed\nでも worktree は kept\n```\n\nという状態は自然に起こります。\n\nreview 用に directory を残しておきたいからです。\n\nしたがって、\n\n**goal state と lane state は同じ field に潰してはいけません。**\n\n## なぜ worktree は「Git の小技」で終わらないのか\n\n初見では「別 directory を増やしただけ」に見えるかもしれません。\n\nでも教学上の本質はそこではありません。\n\n本当に重要なのは、\n\n**task と execution directory の対応関係を明示 record として持つこと**\n\nです。\n\nそれがあるから system は、\n\n- どの lane がどの task に属するか\n- 完了時に何を closeout すべきか\n- crash 後に何を復元すべきか\n\nを説明できます。\n\n## 前の章とどうつながるか\n\nこの章は前段を次のように結びます。\n\n- `s12`: task ID を与える\n- `s15-s17`: teammate と claim を与える\n- `s18`: 各 task に独立 execution lane を与える\n\n流れで書くとこうです。\n\n```text\ntask を作る\n  ->\nteammate が claim する\n  ->\nsystem が worktree lane を割り当てる\n  ->\ncommands がその lane の directory で走る\n  ->\n終了時に keep / remove を選ぶ\n```\n\nここまで来ると multi-agent の並行作業が「同じ場所に集まる chaos」ではなく、\n\n**goal と lane を分けた協調システム**\n\nとして見えてきます。\n\n## worktree は task そのものではない\n\nここは何度でも繰り返す価値があります。\n\n- task は「何をやるか」\n- worktree は「どこでやるか」\n\nです。\n\n同様に、\n\n- runtime slot は「今動いている execution」\n- worktree lane は「どの directory / branch で動くか」\n\nという別軸です。\n\nもしこの辺りが混ざり始めたら、次を開いて整理し直してください。\n\n- [`team-task-lane-model.md`](./team-task-lane-model.md)\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n- [`entity-map.md`](./entity-map.md)\n\n## 初学者が混ぜやすいポイント\n\n### 1. registry だけあって task record に `worktree` がない\n\ntask board から lane の情報が見えなくなります。\n\n### 2. task ID はあるのに command が repo root で走っている\n\n`cwd` が切り替わっていなければ isolation は成立していません。\n\n### 3. `remove` だけを覚えて closeout の意味を教えない\n\n読者は「directory を消す小技」としか理解できなくなります。\n\n### 4. remove 前に dirty state を気にしない\n\n教材版でも最低限、\n\n**消す前に未コミット変更を確認する**\n\nという原則は持たせるべきです。\n\n### 5. `worktree_state` や `closeout` を持たない\n\nlane の終わり方が state として残らなくなります。\n\n### 6. lane を増やすだけで掃除しない\n\n長く使うと registry も directory もすぐ乱れます。\n\n### 7. event log を持たない\n\ncreate / remove failure や binding ミスの調査が極端にやりづらくなります。\n\n## 教学上の境界\n\nこの章でまず教えるべき中心は、製品レベルの Git 運用細目ではありません。\n\n中心は次の 3 行です。\n\n- task が「何をやるか」を記録する\n- worktree が「どこでやるか」を記録する\n- enter / run / closeout が execution lane の lifecycle を構成する\n\nmerge 自動化、複雑な回収 policy、cross-machine execution などは、その幹が見えてからで十分です。\n\nこの章を読み終えた読者が次の 1 文を言えれば成功です。\n\n> task system は仕事の目標を管理し、worktree system はその仕事を安全に進めるための独立レーンを管理する。\n"
  },
  {
    "version": "s19",
    "slug": "s19-mcp-plugin",
    "locale": "ja",
    "title": "s19: MCP & Plugin",
    "kind": "chapter",
    "filename": "s19-mcp-plugin.md",
    "content": "# s19: MCP & Plugin\n\n`s00 > s01 > s02 > s03 > s04 > s05 > s06 > s07 > s08 > s09 > s10 > s11 > s12 > s13 > s14 > s15 > s16 > s17 > s18 > [ s19 ]`\n\n> *すべての能力を主プログラムへ直書きする必要はない。外部能力も同じ routing 面へ接続できる。*\n\n## この章が本当に教えるもの\n\n前の章までは、ツールの多くが自分の Python コード内にありました。\n\nこれは教学として正しい出発点です。\n\nしかしシステムが大きくなると、自然に次の要望が出ます。\n\n> \"外部プログラムの能力を、毎回主プログラムを書き換えずに使えないか?\"\n\nそれに答えるのが MCP です。\n\n## MCP を一番簡単に言うと\n\nMCP は:\n\n**agent が外部 capability server と会話するための標準的な方法**\n\nと考えれば十分です。\n\n主線は次の 4 ステップです。\n\n1. 外部 server を起動する\n2. どんなツールがあるか聞く\n3. 必要な呼び出しをその server へ転送する\n4. 結果を標準化して主ループへ戻す\n\n## なぜ最後の章なのか\n\nMCP は出発点ではありません。\n\n先に理解しておくべきものがあります。\n\n- agent loop\n- tool routing\n- permissions\n- tasks\n- worktree isolation\n\nそれらが見えてからだと、MCP は:\n\n**新しい capability source**\n\nとして自然に理解できます。\n\n## 主線とどう併読するか\n\n- MCP を「遠隔 tool」だけで理解しているなら、[`s19a-mcp-capability-layers.md`](./s19a-mcp-capability-layers.md) を読んで tools、resources、prompts、plugin discovery を 1 つの platform boundary へ戻します。\n- 外部 capability がなぜ同じ execution surface へ戻るのかを確かめたいなら、[`s02b-tool-execution-runtime.md`](./s02b-tool-execution-runtime.md) を併読します。\n- query control と外部 capability routing が頭の中で分離し始めたら、[`s00a-query-control-plane.md`](./s00a-query-control-plane.md) に戻ります。\n\n## 最小の心智モデル\n\n```text\nLLM\n  |\n  | tool を呼びたい\n  v\nAgent tool router\n  |\n  +-- native tool  -> local Python handler\n  |\n  +-- MCP tool     -> external MCP server\n                        |\n                        v\n                    return result\n```\n\n## 重要な 3 要素\n\n### 1. `MCPClient`\n\n役割:\n\n- server へ接続\n- tool 一覧取得\n- tool 呼び出し\n\n### 2. 命名規則\n\n外部ツールとローカルツールが衝突しないように prefix を付けます。\n\n```text\nmcp__{server}__{tool}\n```\n\n例:\n\n```text\nmcp__postgres__query\nmcp__browser__open_tab\n```\n\n### 3. 1 本の unified router\n\n```python\nif tool_name.startswith(\"mcp__\"):\n    return mcp_router.call(tool_name, arguments)\nelse:\n    return native_handler(arguments)\n```\n\n## Plugin は何をするか\n\nMCP が:\n\n> 外部 server とどう会話するか\n\nを扱うなら、plugin は:\n\n> その server をどう発見し、どう設定するか\n\nを扱います。\n\n最小 plugin は:\n\n```text\n.claude-plugin/\n  plugin.json\n```\n\nだけでも十分です。\n\n## 最小設定\n\n```json\n{\n  \"name\": \"my-db-tools\",\n  \"version\": \"1.0.0\",\n  \"mcpServers\": {\n    \"postgres\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-postgres\"]\n    }\n  }\n}\n```\n\nこれは要するに:\n\n> \"この server が必要なら、このコマンドで起動する\"\n\nと主プログラムへ教えているだけです。\n\n## システム全体へどう接続するか\n\nMCP が急に難しく見えるのは、別世界の仕組みとして見てしまうときです。  \nより安定した心智モデルは次です。\n\n```text\nstartup\n  ->\nplugin loader が manifest を見つける\n  ->\nserver config を取り出す\n  ->\nMCP client が connect / list_tools する\n  ->\nexternal tools を同じ tool pool に正規化して入れる\n\nruntime\n  ->\nLLM が tool_use を出す\n  ->\n共有 permission gate\n  ->\nnative route または MCP route\n  ->\nresult normalization\n  ->\n同じ loop へ tool_result を返す\n```\n\n入口は違っても、control plane と execution plane は同じです。\n\n## 重要なデータ構造\n\n### 1. server config\n\n```python\n{\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"...\"],\n    \"env\": {}\n}\n```\n\n### 2. 標準化された外部ツール定義\n\n```python\n{\n    \"name\": \"mcp__postgres__query\",\n    \"description\": \"Run a SQL query\",\n    \"input_schema\": {...}\n}\n```\n\n### 3. client registry\n\n```python\nclients = {\n    \"postgres\": mcp_client_instance\n}\n```\n\n## 絶対に崩してはいけない境界\n\nこの章で最も重要なのは:\n\n**外部ツールも同じ permission 面を通る**\n\nということです。\n\nMCP が permission を素通りしたら、外側に安全穴を開けるだけです。\n\n## Plugin / Server / Tool を同じ層にしない\n\n| 層 | 何か | 何を担当するか |\n|---|---|---|\n| plugin manifest | 設定宣言 | どの server を見つけて起動するかを教える |\n| MCP server | 外部 process / connection | 能力の集合を expose する |\n| MCP tool | server が出す 1 つの callable capability | モデルが実際に呼ぶ対象 |\n\n最短で覚えるなら:\n\n- plugin = discovery\n- server = connection\n- tool = invocation\n\n## 初学者が迷いやすい点\n\n### 1. いきなりプロトコル細部へ入る\n\n先に見るべきは capability routing です。\n\n### 2. MCP を別世界だと思う\n\n実際には、同じ routing、同じ permission、同じ result append に戻します。\n\n### 3. 正規化を省く\n\n外部ツールをローカルツールと同じ形へ揃えないと、後の心智が急に重くなります。\n\n## Try It\n\n```sh\ncd learn-claude-code\npython agents/s19_mcp_plugin.py\n```\n"
  },
  {
    "version": null,
    "slug": "s19a-mcp-capability-layers",
    "locale": "ja",
    "title": "s19a: MCP Capability Layers",
    "kind": "bridge",
    "filename": "s19a-mcp-capability-layers.md",
    "content": "# s19a: MCP Capability Layers\n\n> `s19` の主線は引き続き tools-first で進めるべきです。\n> その上で、この bridge doc は次の心智を足します。\n>\n> **MCP は単なる外部 tool 接続ではなく、複数の capability layer を持つ platform です。**\n\n## 主線とどう併読するか\n\nMCP を主線から外れずに学ぶなら次の順がよいです。\n\n- まず [`s19-mcp-plugin.md`](./s19-mcp-plugin.md) を読み、tools-first の入口を固める\n- 次に [`s02a-tool-control-plane.md`](./s02a-tool-control-plane.md) を見直し、外部 capability がどう unified tool bus に戻るかを見る\n- state record が混ざり始めたら [`data-structures.md`](./data-structures.md) を見直す\n- concept boundary が混ざり始めたら [`glossary.md`](./glossary.md) と [`entity-map.md`](./entity-map.md) を見直す\n\n## なぜ別立てで必要か\n\n教材 repo として、正文を external tools から始めるのは正しいです。\n\n最も入りやすい入口は:\n\n- 外部 server に接続する\n- tool 定義を受け取る\n- tool を呼ぶ\n- 結果を agent へ戻す\n\nしかし完成度を上げようとすると、すぐ次の問いに出会います。\n\n- server は stdio / HTTP / SSE / WebSocket のどれでつながるのか\n- なぜ `connected` の server もあれば `pending` や `needs-auth` の server もあるのか\n- resources や prompts は tools とどう並ぶのか\n- elicitation はなぜ特別な対話になるのか\n- OAuth のような auth flow はどの層で理解すべきか\n\ncapability-layer map がないと、MCP は急に散らばって見えます。\n\n## まず用語\n\n### capability layer とは\n\ncapability layer は:\n\n> 大きな system の中の 1 つの責務面\n\nです。\n\nMCP のすべてを 1 つの袋に入れないための考え方です。\n\n### transport とは\n\ntransport は接続通路です。\n\n- stdio\n- HTTP\n- SSE\n- WebSocket\n\n### elicitation とは\n\nこれは見慣れない用語ですが、教材版では次の理解で十分です。\n\n> MCP server 側が追加情報を要求し、user からさらに入力を引き出す対話\n\nつまり常に:\n\n> agent calls tool -> tool returns result\n\nだけとは限らず、server 側から:\n\n> 続けるためにもっと入力が必要\n\nと言ってくる場合があります。\n\n## 最小の心智モデル\n\nMCP を 6 層で見ると整理しやすいです。\n\n```text\n1. Config Layer\n   server 設定がどう表現されるか\n\n2. Transport Layer\n   何の通路で接続するか\n\n3. Connection State Layer\n   connected / pending / failed / needs-auth\n\n4. Capability Layer\n   tools / resources / prompts / elicitation\n\n5. Auth Layer\n   認証が必要か、認証状態は何か\n\n6. Router Integration Layer\n   tool routing / permission / notifications にどう戻るか\n```\n\nここで最重要なのは:\n\n**tools は一層であって、MCP の全体ではない**\n\nという点です。\n\n## なぜ正文は tools-first のままでよいか\n\n教材として大事なポイントです。\n\nMCP に複数 layer があっても、正文主線はまず次で十分です。\n\n### Step 1: 外部 tools から入る\n\nこれは読者がすでに学んだものと最も自然につながります。\n\n- local tools\n- external tools\n- 1 本の shared router\n\n### Step 2: その上で他の layer があると知らせる\n\n例えば:\n\n- resources\n- prompts\n- elicitation\n- auth\n\n### Step 3: どこまで実装するかを決める\n\nこれが教材 repo の目的に合っています。\n\n**まず似た system を作り、その後で platform layer を厚くする**\n\n## 主要 record\n\n### 1. `ScopedMcpServerConfig`\n\n教材版でも最低限この概念は見せるべきです。\n\n```python\nconfig = {\n    \"name\": \"postgres\",\n    \"type\": \"stdio\",\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"...\"],\n    \"scope\": \"project\",\n}\n```\n\n`scope` が重要なのは、server config が 1 つの場所からだけ来るとは限らないからです。\n\n### 2. MCP connection state\n\n```python\nserver_state = {\n    \"name\": \"postgres\",\n    \"status\": \"connected\",   # pending / failed / needs-auth / disabled\n    \"config\": {...},\n}\n```\n\n### 3. `MCPToolSpec`\n\n```python\ntool = {\n    \"name\": \"mcp__postgres__query\",\n    \"description\": \"...\",\n    \"input_schema\": {...},\n}\n```\n\n### 4. `ElicitationRequest`\n\n```python\nrequest = {\n    \"server_name\": \"some-server\",\n    \"message\": \"Please provide additional input\",\n    \"requested_schema\": {...},\n}\n```\n\nここでの教材上の要点は、elicitation を今すぐ全部実装することではありません。\n\n要点は:\n\n**MCP は常に一方向の tool invocation だけとは限らない**\n\nという点です。\n\n## より整理された図\n\n```text\nMCP Config\n  |\n  v\nTransport\n  |\n  v\nConnection State\n  |\n  +-- connected\n  +-- pending\n  +-- needs-auth\n  +-- failed\n  |\n  v\nCapabilities\n  +-- tools\n  +-- resources\n  +-- prompts\n  +-- elicitation\n  |\n  v\nRouter / Permission / Notification Integration\n```\n\n## なぜ auth を主線の中心にしない方がよいか\n\nauth は platform 全体では本物の layer です。\n\nしかし正文が早い段階で OAuth や vendor 固有 detail へ落ちると、初学者は system shape を失います。\n\n教材としては次の順がよいです。\n\n- まず auth layer が存在すると知らせる\n- 次に `connected` と `needs-auth` が違う connection state だと教える\n- さらに進んだ platform work の段階で auth state machine を詳しく扱う\n\nこれなら正確さを保ちつつ、主線を壊しません。\n\n## `s19` と `s02a` との関係\n\n- `s19` 本文は tools-first の external capability path を教える\n- この note は broader platform map を補う\n- `s02a` は MCP capability が unified tool control plane にどう戻るかを補う\n\n三つを合わせて初めて、読者は本当の構図を持てます。\n\n**MCP は外部 capability platform であり、tools はその最初の切り口にすぎない**\n\n## 初学者がやりがちな間違い\n\n### 1. MCP を外部 tool catalog だけだと思う\n\nその理解だと resources / prompts / auth / elicitation が後で急に見えて混乱します。\n\n### 2. transport や OAuth detail に最初から沈み込む\n\nこれでは主線が壊れます。\n\n### 3. MCP tool を permission の外に置く\n\nsystem boundary に危険な横穴を開けます。\n\n### 4. server config・connection state・exposed capabilities を一つに混ぜる\n\nこの三層は概念的に分けておくべきです。\n"
  },
  {
    "version": null,
    "slug": "teaching-scope",
    "locale": "ja",
    "title": "教材の守備範囲",
    "kind": "bridge",
    "filename": "teaching-scope.md",
    "content": "# 教材の守備範囲\n\n> この文書は、この教材が何を教え、何を意図的に主線から外すかを明示するためのものです。\n\n## この教材の目標\n\nこれは、ある実運用コードベースを逐行で注釈するためのリポジトリではありません。\n\n本当の目標は:\n\n**高完成度の coding-agent harness を 0 から自力で作れるようにすること**\n\nです。\n\nそのために守るべき条件は 3 つあります。\n\n1. 学習者が本当に自分で作り直せること\n2. 主線が side detail に埋もれないこと\n3. 実在しない mechanism を学ばせないこと\n\n## 主線章で必ず明示すべきこと\n\n各章は次をはっきりさせるべきです。\n\n- その mechanism が何の問題を解くか\n- どの module / layer に属するか\n- どんな state を持つか\n- どんな data structure を導入するか\n- loop にどうつながるか\n- runtime flow がどう変わるか\n\n## 主線を支配させない方がよいもの\n\n次の話題は存在してよいですが、初心者向け主線の中心に置くべきではありません。\n\n- packaging / build / release flow\n- cross-platform compatibility glue\n- telemetry / enterprise policy wiring\n- historical compatibility branches\n- product 固有の naming accident\n- 上流コードとの逐行一致\n\n## ここでいう高忠実度とは何か\n\n高忠実度とは、すべての周辺 detail を 1:1 で再現することではありません。\n\nここで寄せるべき対象は:\n\n- core runtime model\n- module boundaries\n- key records\n- state transitions\n- major subsystem cooperation\n\nつまり:\n\n**幹には忠実に、枝葉は教材として意識的に簡略化する**\n\nということです。\n\n## 想定読者\n\n標準的な想定読者は:\n\n- 基本的な Python は読める\n- 関数、クラス、list、dict は分かる\n- ただし agent platform は初学者でもよい\n\nしたがって文章は:\n\n- 先に概念を説明する\n- 1つの概念を1か所で完結させる\n- `what -> why -> how` の順で進める\n\nのが望ましいです。\n\n## 各章の推奨構成\n\n1. これが無いと何が困るか\n2. 先に新しい言葉を説明する\n3. 最小の心智モデルを示す\n4. 主要 record / data structure を示す\n5. 最小で正しい実装を示す\n6. loop への接続点を示す\n7. 初学者がやりがちな誤りを示す\n8. 高完成度版で後から足すものを示す\n\n## 用語の扱い\n\n次の種類の語が出るときは、名前だけ投げず意味を説明した方がよいです。\n\n- design pattern\n- data structure\n- concurrency term\n- protocol / networking term\n- 一般的ではない engineering vocabulary\n\n例:\n\n- state machine\n- scheduler\n- queue\n- worktree\n- DAG\n- protocol envelope\n\n## 最小正解版の原則\n\n現実の mechanism は複雑でも、教材は最初から全分岐を見せる必要はありません。\n\nよい順序は:\n\n1. 最小で正しい版を示す\n2. それで既に解ける core problem を示す\n3. 後で何を足すかを示す\n\n例:\n\n- permission: `deny -> mode -> allow -> ask`\n- error recovery: 主要な回復枝から始める\n- task system: records / dependencies / unlocks から始める\n- team protocol: request / response + `request_id` から始める\n\n## 逆向きソースの使い方\n\n逆向きで得たソースは:\n\n**保守者の校正材料**\n\nとして使うのが正しいです。\n\n役割は:\n\n- 主線 mechanism の説明がズレていないか確かめる\n- 重要な境界や record が抜けていないか確かめる\n- 教材実装が fiction に流れていないか確かめる\n\n読者がそれを見ないと本文を理解できない構成にしてはいけません。\n\n## 一文で覚える\n\n**よい教材は、細部をたくさん言うことより、重要な細部を完全に説明し、重要でない細部を安全に省くことによって質が決まります。**\n"
  },
  {
    "version": null,
    "slug": "team-task-lane-model",
    "locale": "ja",
    "title": "Team Task Lane Model",
    "kind": "bridge",
    "filename": "team-task-lane-model.md",
    "content": "# Team Task Lane Model\n\n> `s15-s18` に入ると、関数名よりも先に混ざりやすいものがあります。\n>\n> それは、\n>\n> **誰が働き、誰が調整し、何が目標を記録し、何が実行レーンを提供しているのか**\n>\n> という層の違いです。\n\n## この橋渡し資料が解決すること\n\n`s15-s18` を通して読むと、次の言葉が一つの曖昧な塊になりやすくなります。\n\n- teammate\n- protocol request\n- task\n- runtime task\n- worktree\n\n全部「仕事が進む」ことに関係していますが、同じ層ではありません。\n\nここを分けないと、後半が急に分かりにくくなります。\n\n- teammate は task と同じなのか\n- `request_id` と `task_id` は何が違うのか\n- worktree は runtime task の一種なのか\n- task が終わっているのに、なぜ worktree が kept のままなのか\n\nこの資料は、その層をきれいに分けるためのものです。\n\n## 読む順番\n\n1. [`s15-agent-teams.md`](./s15-agent-teams.md) で長寿命 teammate を確認する\n2. [`s16-team-protocols.md`](./s16-team-protocols.md) で追跡可能な request-response を確認する\n3. [`s17-autonomous-agents.md`](./s17-autonomous-agents.md) で自律 claim を確認する\n4. [`s18-worktree-task-isolation.md`](./s18-worktree-task-isolation.md) で隔離 execution lane を確認する\n\n用語が混ざってきたら、次も見直してください。\n\n- [`entity-map.md`](./entity-map.md)\n- [`data-structures.md`](./data-structures.md)\n- [`s13a-runtime-task-model.md`](./s13a-runtime-task-model.md)\n\n## まずはこの区別を固定する\n\n```text\nteammate\n  = 長期に協力する主体\n\nprotocol request\n  = チーム内で追跡される調整要求\n\ntask\n  = 何をやるべきか\n\nruntime task / execution slot\n  = 今まさに動いている実行単位\n\nworktree\n  = 他の変更とぶつからずに仕事を進める実行ディレクトリ\n```\n\n特に混ざりやすいのは最後の3つです。\n\n- `task`\n- `runtime task`\n- `worktree`\n\n毎回、次の3つを別々に問い直してください。\n\n- これは目標か\n- これは実行中の単位か\n- これは隔離された実行ディレクトリか\n\n## 一番小さい図\n\n```text\nTeam Layer\n  teammate: alice (frontend)\n\nProtocol Layer\n  request_id=req_01\n  kind=plan_approval\n  status=pending\n\nWork Graph Layer\n  task_id=12\n  subject=\"Implement login page\"\n  owner=\"alice\"\n  status=\"in_progress\"\n\nRuntime Layer\n  runtime_id=rt_01\n  type=in_process_teammate\n  status=running\n\nExecution Lane Layer\n  worktree=login-page\n  path=.worktrees/login-page\n  status=active\n```\n\nこの中で、仕事そのものの目標を表しているのは一つだけです。\n\n> `task_id=12`\n\n他は、その目標のまわりで協調・実行・分離を支える層です。\n\n## 1. Teammate: 誰が協力しているか\n\n`s15` で導入される層です。\n\nここが答えること：\n\n- 長寿命 worker の名前\n- 役割\n- `working` / `idle` / `shutdown`\n- 独立した inbox を持つか\n\n例：\n\n```python\nmember = {\n    \"name\": \"alice\",\n    \"role\": \"frontend\",\n    \"status\": \"idle\",\n}\n```\n\n大事なのは「agent をもう1個増やす」ことではありません。\n\n> 繰り返し仕事を受け取れる長寿命の身元\n\nこれが本質です。\n\n## 2. Protocol Request: 何を調整しているか\n\n`s16` の層です。\n\nここが答えること：\n\n- 誰が誰に依頼したか\n- どんな種類の request か\n- pending なのか、もう解決済みなのか\n\n例：\n\n```python\nrequest = {\n    \"request_id\": \"a1b2c3d4\",\n    \"kind\": \"plan_approval\",\n    \"from\": \"alice\",\n    \"to\": \"lead\",\n    \"status\": \"pending\",\n}\n```\n\nこれは普通の会話ではありません。\n\n> 状態更新を続けられる調整記録\n\nです。\n\n## 3. Task: 何をやるのか\n\nこれは `s12` の durable work-graph task であり、`s17` で teammate が claim する対象です。\n\nここが答えること：\n\n- 目標は何か\n- 誰が担当しているか\n- 何にブロックされているか\n- 進捗状態はどうか\n\n例：\n\n```python\ntask = {\n    \"id\": 12,\n    \"subject\": \"Implement login page\",\n    \"status\": \"in_progress\",\n    \"owner\": \"alice\",\n    \"blockedBy\": [],\n}\n```\n\nキーワードは：\n\n**目標**\n\nディレクトリでも、protocol でも、process でもありません。\n\n## 4. Runtime Task / Execution Slot: 今なにが走っているか\n\nこの層は `s13` の橋渡し資料ですでに説明されていますが、`s15-s18` ではさらに重要になります。\n\n例：\n\n- background shell が走っている\n- 長寿命 teammate が今作業している\n- monitor が外部状態を見ている\n\nこれらは、\n\n> 実行中の slot\n\nとして理解するのが一番きれいです。\n\n例：\n\n```python\nruntime = {\n    \"id\": \"rt_01\",\n    \"type\": \"in_process_teammate\",\n    \"status\": \"running\",\n    \"work_graph_task_id\": 12,\n}\n```\n\n大事な境界：\n\n- 1つの task から複数の runtime task が派生しうる\n- runtime task は durable な目標そのものではなく、実行インスタンスである\n\n## 5. Worktree: どこでやるのか\n\n`s18` で導入される execution lane 層です。\n\nここが答えること：\n\n- どの隔離ディレクトリを使うか\n- どの task と結び付いているか\n- その lane は `active` / `kept` / `removed` のどれか\n\n例：\n\n```python\nworktree = {\n    \"name\": \"login-page\",\n    \"path\": \".worktrees/login-page\",\n    \"task_id\": 12,\n    \"status\": \"active\",\n}\n```\n\nキーワードは：\n\n**実行境界**\n\ntask そのものではなく、その task を進めるための隔離レーンです。\n\n## 層はどうつながるか\n\n```text\nteammate\n  protocol request で協調し\n  task を claim し\n  execution slot として走り\n  worktree lane の中で作業する\n```\n\nもっと具体的に言うなら：\n\n> `alice` が `task #12` を claim し、`login-page` worktree lane の中でそれを進める\n\nこの言い方は、\n\n> \"alice is doing the login-page worktree task\"\n\nのような曖昧な言い方よりずっと正確です。\n\n後者は次の3層を一つに潰してしまいます。\n\n- teammate\n- task\n- worktree\n\n## よくある間違い\n\n### 1. teammate と task を同じものとして扱う\n\nteammate は実行者、task は目標です。\n\n### 2. `request_id` と `task_id` を同じ種類の ID だと思う\n\n片方は調整、片方は目標です。\n\n### 3. runtime slot を durable task だと思う\n\n実行は終わっても、durable task は残ることがあります。\n\n### 4. worktree を task そのものだと思う\n\nworktree は execution lane でしかありません。\n\n### 5. 「並列で動く」とだけ言って層の名前を出さない\n\n良い教材は「agent がたくさんいる」で止まりません。\n\n次のように言える必要があります。\n\n> teammate は長期協力を担い、request は調整を追跡し、task は目標を記録し、runtime slot は実行を担い、worktree は実行ディレクトリを隔離する。\n\n## 読み終えたら言えるようになってほしいこと\n\n1. `s17` の自律 claim は `s12` の work-graph task を取るのであって、`s13` の runtime slot を取るのではない。\n2. `s18` の worktree は task に execution lane を結び付けるのであって、task をディレクトリへ変えるのではない。\n"
  }
]